Howto Start a Sharepoint Workflow Programmatically

Starting a Sharepoint workflow programmatically turned out to be not as easy as it should have been (but that was due to an improper Sharepoint configuration).  It is actually pretty easy to do once you stumble through the Sharepoint API''s with a little trial and error.

To start a workflow programmatically you'll have to do the following:

• Determine the GUID, or index value, of the workflow you want to start.
• Determine the AssociationData that the workflow requires to start.

Easy enough!

Ok Mr. Smarty-Pants, how do I determine the GUID of the workflow I want to start?

There are a few ways you can do this.

You could iterate in code through all the associated workflows of a document library and use the debugger to find out the GUID of the workflow you want.

Or an easier way is to right click on an item in your doc library and select "Workflows" from the dropdown menu.

You'll then see a list of all the workflows associated to your document library.  Go ahead and click on one of them.

In the address bar you'll see a query string variable called "TemplateID" and the data after that is your GUID.  In this case, its "a5d937a-4d61-4a2a-ab2e-5956d77f62d2".  Alright so now we have our Workflow GUID we have to create a SPWorkflowAssociation object with that GUID.

Once we have an SPWorkflowAssociation object, we can then begin to work with a specific workflow and set it to start on specific list item.

The way to tell a workflow to start is to go through the WorkflowManager of our SPSite object.  We call the StartWorkflow method of the WorkflowManager and pass in our list item to act on(SPListItem object), the workflow to use (SPWorkflowAssociation object), any workflow start data (string object), and whether or not the workflow is an autostart workflow (optional boolean).

The SPListItem object is pretty easy to understand.  In the code above I was using a file that I was uploading to document library.

The SPWorkflowAssociation is the object we created on the line above it and is the workflow that we want to act on our SPListItem object.

The string of start data is a little less easy to understand at first glance.  Every workflow expects a string of well formed XML data as its start or "Association" data.  This XML data will be different for each workflow.  The screenshot below is the AssociationData that an Approval workflow expects to be passed in.

In some cases, you may have to modify this XML and pass in certain values to the workflow that are required for it to start properly, but you'll need to determine that on your own for your specific case.  One thing to note is that I don't believe passing in Null or an Empty string will suffice for this variable.  If anything, just pass the AssociationData property of the workflow association and that should work most of the time.

The final variable is optional and it specifies whether or not the workflow is an AutoStart workflow or not.  I was able to get all my code working by specifying this variable...Some people have gotten it to work without this variable, so play around and find out what works for your specific case.

Here is a quick chunk of code to loop over all the items in a document library and kickoff a workflow for each one.

foreach (SPListItem itm in docLib.Items)
{
    //get the workflow associated with this doc lib and kick if off manually
    SPWorkflowAssociation wrkFl = docLib.WorkflowAssociations[0];
    site.WorkflowManager.StartWorkflow(itm, wrkFl, wrkFl.AssociationData, true);
}

I did manage to run into an error with the code above that was due to an improper Sharepoint Configuration.  Check out my post about Workflow stuck in "Starting" state to see how I solved that problem.

Also as specified above, the AssociationData string cannot have Null or an Empty string passed into it, it needs at least something to start.