Programmatically start workflow


Programmatically starting a workflow requires the following code:

Guid wfBaseId = new Guid("{6BE0ED92-BB12-4F8F-9687-E12DC927E4AD}");
SPSite site = ...;
SPWeb web = site.OpenWeb();
SPList list = web.Lists["listname"];
SPListItem item = list.Items[0];
SPWorkflowAssociation associationTemplate= list.WorkflowAssociations.GetAssociationByBaseID(wfBaseId);
site.WorkflowManager.StartWorkflow(item, associationTemplate, "<root />");

The workflow base ID can be found in the workflow.xml in the corresponding feature folder.

If you have a SharePoint Designer 2007 workflow it can be obtained by opening the workflow.xoml.wfconfig.xml file in a text editor:

If you don't have initiation data don't pass null or an empty string to the StartWorkflow method or the workflow will fail ! Instead use a single empty XML node (see sample code above).

 


Links to this post

Comments

Friday, 18 Jan 2008 08:12 by Paul Galvin
This is excellent to know. Thanks!

Monday, 21 Jan 2008 09:08 by Michaël Hompus
You really should use the "using" statement to dispose the SPSite and SPWeb objects. This can save you a lot of memory. So it should be something like using (SPSite site = ...) using (SPWeb web = site.OpenWeb()) { Guid wfBaseId = new Guid("{6BE0ED92-BB12-4F8F-9687-E12DC927E4AD}"); SPList list = web.Lists["listname"]; SPListItem item = list.Items[0]; SPWorkflowAssociation associationTemplate= list.WorkflowAssociations.GetAssociationByBaseID(wfBaseId); site.WorkflowManager.StartWorkflow(item, associationTemplate, ""); }

Monday, 21 Jan 2008 05:08 by Steven Van de Craen
Michaël, glad to see you're up to speed with some of the best practices. I omitted it in code because it wasn't relevant to the sample. Besides, the SPSite object could be a reference to the SPContext.Current.Site instance which you should never dispose manually. Who knows what lies beneath those three dots ;)

Wednesday, 20 Feb 2008 11:36 by Rich Lasker
I seem to have a problem with the GetAssociationByBaseID. It is always returning null. If I loop through the SPWorkflowAssociations collection and match the Guid with the BaseId in a foreach loop then I can match it and everything works fine, but using the method always results in a null object.

Thursday, 28 Feb 2008 04:27 by Dirk
Hello steven, I tried to make use of your code to solve a similar problem I was having with starting a workflow. However, my workflow is custom made and launches an Infopath form on activation. When using your code, the "Eventdata" ( ""); in your example) is used and the initial form is not launched. Can your code be adapted to correct this?

Sunday, 2 Mar 2008 08:13 by Steven Van de Craen
Dirk, starting it programmatically will not bring up the initiation form. You will have to supply the correct XML for this form as a string (like "" in the above sample.

Monday, 28 Apr 2008 05:42 by ed
This bit of powershelling also works: [System.Reflection.Assembly]::Load("Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c") $Site= new-object Microsoft.SharePoint.SPSite("http://blah.blah") $cultinf = System.Globalization.CultureInfo]::CurrentCulture $web = $site.AllWebs["dokumenten-center"] $seiten = $web.Lists["pages"] $listitem = $seiten.Items[0] $assoctpl = $seiten.WorkflowAssociations.GetAssociationByName("My Friendly WfName", $cultinf) #$assoctpl $site.WorkflowManager.StartWorkflow($listitem, $assoctpl, "")

Monday, 28 Apr 2008 06:20 by Steven Van de Craen
Ed, thanks for sharing that sample. I'm starting to jump aboard the Powershell train and it's a coincidence that you post this comment right now.

Monday, 13 Oct 2008 11:26 by Deepak
Thanks for this great code. Do you any have idea how to stop the same sharpoint designer workflow from VS? Thanks in advance. Deepak Jindal

Tuesday, 14 Oct 2008 10:36 by Steven Van de Craen
Don't know by hard but should be pretty obvious. What are you trying to achieve ? Cancelling (set status to cancelled + delete tasks) or something different ? Check out the SPWorkflow type or instance...

Thursday, 20 Nov 2008 01:13 by Sam
I am using your code to initiate a simple Designer created workflow. However, I keep getting the following error: Request for the permission of type 'System.Security.Permissions.FileIOPermission, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' failed. Your thoughts would be appreciated, thank you.

Thursday, 20 Nov 2008 05:12 by Steven Van de Craen
Your code doesn't have enough permissions to do that. Either sign and deploy to GAC, specify CAS permissions or set the web.config trust-level to 'Full'. The latter is only advised for development machines !

Saturday, 22 Nov 2008 09:31 by Sam
Thats brilliant Steven. I thought I had already added to the GAC - shows you what thought did. Thanks again.

Tuesday, 3 Feb 2009 12:23 by Latha
Steven I used your code what exact you have used in the above line but i got the exception is Exception from HRESULT: 0x8102009B my code is here, do you have any solution for this?, the workflow which i used i have created that throgh sharepoint designer public void StartWorkFlow(int listItemID) { string approvalWorkFlowGUID = GetConfigSetting("ApprovalWorkFlowGUID"); try { SPSecurity.RunWithElevatedPrivileges(delegate() { using (SPSite mySiteCollection = new SPSite(siteUrl)) { using (SPWeb mySite = mySiteCollection.OpenWeb()) { try { mySite.AllowUnsafeUpdates = true; SPList oSPList = mySite.Lists[strProcessListName]; SPListItem oSpListItem = oSPList.GetItemById(listItemID); Guid wfBaseId = new Guid(approvalWorkFlowGUID); SPWorkflowAssociation associationTemplate = oSPList.WorkflowAssociations.GetAssociationByBaseID(wfBaseId); mySiteCollection.WorkflowManager.StartWorkflow(oSpListItem, associationTemplate, associationTemplate.AssociationData); oSpListItem.Update(); } catch (Exception ex) { EventLog.LogError("iProcessUpdation - StartWorkFlow", ex.Message); } } } }); } catch (Exception ex) { EventLog.LogError("iProcessUpdation - StartWorkFlow", ex.Message); } }

Wednesday, 4 Feb 2009 04:56 by Steven Van de Craen
Latha, debug the contents of the associationTemplate.AssociationData and verify that it is valid association data xml.

Thursday, 5 Feb 2009 07:06 by Latha
thanks Steven for your reply, yes i verified that also in your code you hard coded like "", in mycode when i debug that, it comes like "", i dont know wheather that is correct or not, i dont have much idea about start workflow programmatically. i refered some of the link like your link then i started to working because my recurirement is like this one more thing i have created the Approval workflow with sharepoint designer.. is it giving any problem for that? do you have any reference material to learn how to start workflow programatically i mean should i give any permission for workflow? where i have to give permission? because might be i have missed something thats why i am asking.

Thursday, 5 Feb 2009 07:13 by Latha
thanks Steven for your reply, yes i verified that also in your code you hard coded like , in mycode when i debug that, it comes like , i dont know wheather that is correct or not, i dont have much idea about start workflow programmatically. i refered some of the link like your link then i started to working because my recurirement is like this one more thing i have created the Approval workflow with sharepoint designer.. is it giving any problem for that? do you have any reference material to learn how to start workflow programatically i mean should i give any permission for workflow? where i have to give permission? because might be i have missed something thats why i am asking.

Thursday, 5 Feb 2009 07:14 by Latha
thanks Steven for your reply, yes i verified that also in your code you hard coded like root, in mycode when i debug that, it comes like Data , i dont know wheather that is correct or not, i dont have much idea about start workflow programmatically. i refered some of the link like your link then i started to working because my recurirement is like this one more thing i have created the Approval workflow with sharepoint designer.. is it giving any problem for that? do you have any reference material to learn how to start workflow programatically i mean should i give any permission for workflow? where i have to give permission? because might be i have missed something thats why i am asking. sorry sending again and again the data and root are not displaying in the previous comment

Sunday, 8 Feb 2009 09:28 by Steven Van de Craen
Latha, never pass null or "" to the initiation data. It should be an XML string. If your workflow doesn't require initiation data than provide an empty XML node as string (see my sample). Check this as follows; when you start the workflow on an item does it ask you to enter data into the initation form ? Also I see now that you use AssociationData for InitiationData. If both are empty it might not be an issue but it's not a very good idea to do this.

Saturday, 23 May 2009 02:39 by David
Totally unnecesary to go through the GUID thing. .GetAssociationByName will do the same thing by Workflow Name. Otherwise, good bit of info.

Monday, 25 May 2009 04:07 by Priyanka
Hi Steven, I am facing an error while at this line in my code: objWorkflowManager.StartWorkflow(photoItem, objWorkflowAssociation, objWorkflowAssociation.AssociationData); Error is: Attempted to perform an unauthorized operation I have enclosed the entire code in SPSecurity.RunWithElevatedPrivileges() and also all the SPWeb and other objects are declared within. Additionally I do not face any problem when trying to start the workflow when logged in as system account or contributors to the website. The problem comes when I try starting logged in as a limited access account which is a visitor to the site. That is why am using RunWithElevatedPrivileges. My requirement is such that I cannot assign more permissions to this readonly account, but they should be able to start the workflow which is part of a request they make of the site. Am I missing anything. And other permissions or security I need to configure, any ideas please???

Wednesday, 27 May 2009 01:09 by Steven Van de Craen
Priyanka, Are you getting a new SPSite via the constructor or from the SPContext ? You shouldn't need additional configuration.

Wednesday, 17 Jun 2009 11:47 by Manas
Hi, I want to start the workflow from list view page (AllItems.aspx). For this, I have created a custom field which renders a "Start Workflow" button, through "DisplayPattern" of that field. I have put some javascript code in hidden content editor webpart in AllItems.aspx page. So clicking on that "Start Workflow" Button navigates the user to the initiation page of the workflow, where user have to click on "Start" button to actually start the workflow. Now I want to start the workflow from AllItems.aspx itself. Does anybody know how to do this ? Thanks, Manas

Thursday, 18 Jun 2009 04:09 by Steven Van de Craen
Manas, that's different for each workflow. Your best shot is probably to have a custom ASPX or ASHX start the desired workflow. You could call it via javascript (plain redirect or ajax call).

Friday, 19 Jun 2009 10:44 by Manas
Yes, I got the solution. I am calling the StartWorkflow method in workflow webservice through XmlHttpRequest. And it works :)

Friday, 7 Aug 2009 02:43 by Dmitry
Hi, Manas! I have same task - start workflow from AllItems.aspx But I faced some problems. Can you show me the way you do it? or send me you code: red_falcon@mail.ru

Wednesday, 12 Aug 2009 04:40 by Bo
Hi, I used the same code to start the workflow, but I am getting this exception error msg: "System.ArgumentException: Value does not fall within the expected range". its telling me this line is causing the error: "Site.WorkflowManager.StartWorkflow(item, associationTemplate, "")" I have checked the reference to the item and associationTemplate is correct. Any help would be great appreciated. thanks!

Thursday, 13 Aug 2009 09:38 by amol
Hi Steven , I am using same code as u r sample one SPSecurity.RunWithElevatedPrivileges(delegate() { using (SPSite site = new SPSite(SPContext.Current.Site.ID)) { site.AllowUnsafeUpdates = true; using (SPWeb web = site.OpenWeb("LeaveManagement")) { web.AllowUnsafeUpdates = true; web.Update(); Guid wfBaseId = new Guid(""); SPWorkflowAssociation associationTemplate = list.WorkflowAssociations.GetAssociationByBaseID(wfBaseId); site.WorkflowManager.StartWorkflow(LeaveItem, associationTemplate, "");web.AllowUnsafeUpdates = false;web.Update();}site.AllowUnsafeUpdates = false;}}); but i got error : Updates are currently disallowed on GET requests. To allow updates on a GET, set the 'AllowUnsafeUpdates' property on SPWeb. please help

Tuesday, 25 Aug 2009 05:18 by Steven Van de Craen
Amol, given that you're using SPContext I take it you're running from within a Web Part. I've reproduced your code changing some values to the oob Approval Workflow and such but no issues at all. I even commented out every AllowUnsafeUpdates of yours and it kept on working. Could you explain in more detail what you're doing ?

Wednesday, 20 Jan 2010 08:44 by Umesh Bhatt
Thanks Steve. This was an import lesson. I was missing the " part and my workflow did work after supplying that parameter.

Friday, 29 Jan 2010 04:37 by Dao
I use your code except different workflow guid. However, I got System.ArgumentNullException: Vlaue cannot be null at Microsoft.SharePoint.Workflow.SPWorkflowManager.StartWorkflow(SPListItem item, SPWorkflowAssociation association, String eventData, Boolean isAutoStart)..... I also got a same error when trying an empty "" instead of "". I spent many days and tried to debug but got no solution yet. Any help would be highly appreciated.

Friday, 29 Jan 2010 05:13 by Dao
I have debug and somehow my associationTemplate is null. I actually have this custom workflow working when I start it manually.

Friday, 29 Jan 2010 08:54 by Dao
I finally found a solution. I applied document library name in the bracket web.Lists["mydocumentlibraryname"] instead of "listname".

Monday, 9 Aug 2010 08:25 by John
Thanks for the post Steven, i've gotten it to work on test environment, but when i tried to make it works on production environment it gave me an error. Here is my code SPList oList = oSPWeb.Lists["Workflow Tasks"]; SPListItemCollection items = oList.GetItems(oQuery); Guid wfBaseId = new Guid("{02A20696-8AD2-432D-BECA-E6D8DE6D0126}"); SPWorkflowAssociation associationTemplate= oList.WorkflowAssociations.GetAssociationByBaseID(wfBaseId); foreach (SPListItem oItem in items) { //oSPSite.WorkflowManager.StartWorkflow(oItem, associationTemplate, ""); } Here is the error i got from log file 0x1DA8 Windows SharePoint Services Workflow Infrastructure 72fs Unexpected RunWorkflow: System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary. at System.ThrowHelper.ThrowKeyNotFoundException() at System.Collections.Generic.Dictionary`2.get_Item(TKey key) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.<>c__DisplayClassd.b__b() at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.DoCompileNewAppDomain(WorkflowCompilerParameters parameters, String xomlSource, String assemblyName, SPWeb web, CompilationPacket& packet, DirectoryInfo& tempDir) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.CompileBytes(Byte[] xomlBytes, Byte[] rulesBytes, Boolean doTestCompilation, String as... 08/08/2010 23:59:36.98* OWSTIMER.EXE (0x15DC) 0x1DA8 Windows SharePoint Services Workflow Infrastructure 72fs Unexpected ...semblyName, SPWeb web) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.LoadXomlAssembly(String assmNameIn, SPWeb web) at Microsoft.SharePoint.Workflow.SPWinOeHostServices.CreateInstance(Guid trackingId, SPWorkflow workflow) at Microsoft.SharePoint.Workflow.SPWinOeEngine.RunWorkflow(Guid trackingId, SPWorkflowHostService host, SPWorkflow workflow, Collection`1 events, TimeSpan timeOut) at Microsoft.SharePoint.Workflow.SPWorkflowManager.RunWorkflowElev(SPWorkflow originalWorkflow, SPWorkflow workflow, Collection`1 events, SPRunWorkflowOptions runOptions) 08/08/2010 23:59:36.98 OWSTIMER.EXE (0x15DC) 0x1DA8 Windows SharePoint Services Workflow Infrastructure 98d7 Unexpected System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary. at System.ThrowHelper.ThrowKeyNotFoundException() at System.Collections.Generic.Dictionary`2.get_Item(TKey key) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.<>c__DisplayClassd.b__b() at Microsoft.SharePoint.Utilities.SecurityContext.RunAsProcess(CodeToRunElevated secureCode) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.DoCompileNewAppDomain(WorkflowCompilerParameters parameters, String xomlSource, String assemblyName, SPWeb web, CompilationPacket& packet, DirectoryInfo& tempDir) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.CompileBytes(Byte[] xomlBytes, Byte[] rulesBytes, Boolean doTestCompilation, String assemblyName, S... 08/08/2010 23:59:36.98* OWSTIMER.EXE (0x15DC) 0x1DA8 Windows SharePoint Services Workflow Infrastructure 98d7 Unexpected ...PWeb web) at Microsoft.SharePoint.Workflow.SPNoCodeXomlCompiler.LoadXomlAssembly(String assmNameIn, SPWeb web) at Microsoft.SharePoint.Workflow.SPWinOeHostServices.CreateInstance(Guid trackingId, SPWorkflow workflow) at Microsoft.SharePoint.Workflow.SPWinOeEngine.RunWorkflow(Guid trackingId, SPWorkflowHostService host, SPWorkflow workflow, Collection`1 events, TimeSpan timeOut) at Microsoft.SharePoint.Workflow.SPWorkflowManager.RunWorkflowElev(SPWorkflow originalWorkflow, SPWorkflow workflow, Collection`1 events, SPRunWorkflowOptions runOptions)

Thursday, 12 Aug 2010 10:12 by Steven Van de Craen
John, hard to say when it's working on one of two environments. Try setting the diagnostic log level for "Windows SharePoint Services Workflow Infrastructure" to verbose and see if you can narrow it down. Try starting it elevated to see if that works.

Monday, 4 Oct 2010 06:50 by Steve O
"If you don't have initiation data don't pass null or an empty string to the StartWorkflow method or the workflow will fail ! Instead use a single empty XML node (see sample code above)." This was, for me, the most important line in the entire post. Well done Steven, and thank you for your post!

Tuesday, 27 Dec 2011 10:52 by
Thanks!

Monday, 17 Jun 2013 04:24 by Thiago
Hello Steven. I've got some failing while trying to start my workflow. It's a workflow with some approval tasks on it. That's what happens whenever I try to start it programmatically. I get no errors. Everything goes fine. However, just when the first approval process walks in, SharePoint starts the approval task as it was told to do. Then, right after this task gets cancelled, the workflow crashes. I don't know why. On the workflow history page, I got this information "Error-The workflow could not update the item, possibly because one or more columns for the item require a different type of information.-Unknown error". PS: Whenever I start this same workflow manually (through the workflow's start page) with same account, same list item, same everything, it gives me no trouble. I tried digging through the log to find something that would help me to solve this but no success. Do you have any guess why I can't start it programmatically without facing this?

CAPTCHA Image Validation