The setState activity is a SharePoint Workflow activity that modifies the status of a running workflow. Normally, when you initiate a custom SharePoint workflow, its status changes to in progress. It will stay in this state until the worfklow completes, at which point the status will change to completed. The problem is that the status will always change to completed, whether your workflow tasks are approved, rejected or reassigned. So, what if you want to update the workflow’s status as it progresses? What if you want to display a more meaningful status like Approved, Rejected or Reassigned? Enter the setState activity.
Microsoft uses custom states for the workflow that come with SharePoint (Approval, Feedback, etc.). When all the tasks in an Approval workflow have been approved, the status actually changed to Approved; when one of the tasks is rejected, the status changes to Rejected. This is much more informative than just reporting Completed.
There’s two parts to using custom workflow statuses (not stati):
- Adding a new Status to workflow.xml
- Setting the status using the setState activity.
Add a New Status
A list of custom statuses is added via the <ExtendedStatusColumnValues> element of workflow.xml. Now, if you’re using the VSeWSS templates for creating your workflows (and you should be) this element won’t be included. It must site somewhere within the <MetaData> tag. For consistency across my projects, I always place it directly beneath the <StatusPageUrl> element. Here’s the format of a typical <ExtendedStatusColumnValues> element from one of my projects. I’ve included the surrounding tags, to provide some context within the workflow.xml file:
<MetaData>
<!– Tags to specify InfoPath forms for the workflow; delete tags for forms that you do not have –>
<!–<Association_FormURN>[URN FOR ASSOCIATION FORM]</Association_FormURN>
<Instantiation_FormURN>[URN FOR INSTANTIATION FORM]</Instantiation_FormURN>
<Task0_FormURN></Task0_FormURN>
<Task1_FormURN></Task1_FormURN>–>
<!– Modification forms: create a unique guid for each modification form –>
<!–<Modification_[UNIQUE GUID]_FormURN>[URN FOR MODIFICATION FORM]</Modification_[UNIQUE GUID]_FormURN>
<Modification_[UNIQUE GUID]_Name>[NAME OF MODIFICATION TO BE DISPLAYED AS A LINK ON WORKFLOW STATUS PAGE</Modification_[UNIQUE GUID]_Name>
–>
<StatusPageUrl>_layouts/WrkStat.aspx</StatusPageUrl>
<ExtendedStatusColumnValues>
<StatusColumnValue>Approved</StatusColumnValue>
<StatusColumnValue>Rejected</StatusColumnValue>
</ExtendedStatusColumnValues>
</MetaData>
Notice that each individual Status is added via its own, individual, <StatusColumnValue> attribute. It’s important to stick to this format. You can add as many <StatusColumnValue> attributes as your project requires. So what’s actually happening here? Well project statuses are stored as an enumeration. By adding these new status types, you’re actually adding these new strings to the enumeration. Note: Status Column Values will be added to the enumeration in the order that they’re added to workflow.xml!
It’s not important to understand enumerated types to use custom statuses, but it does explain how we address them in the next section.
At this point it might be useful (though not necessary) to glance over the following links for a more complete understanding:
- ExtendedStatusColumnValues Element at MSDN: http://msdn.microsoft.com/en-us/library/aa543169.aspx
- SPWorkflowStatus Enumeration at MSDN: http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.workflow.spworkflowstatus.aspx
Setting the Status
To change the status during our workflow, we must use the setState activity. After adding the activity,we use just one line of code the set the state. From start to finish:
- Drag a setState activity to the Workflow Designer canvas. The first one will be called setState1
- In the setState field’s properties, set the correlation token. Since the setState activity doesn’t correlate directly to a workflow task, just use the workflow’s default token (usually called workflowToken).
- Double-click on the setState1 activity to create an Invoking method. This will also bring up the code view.
- Write the code to set the status of your workflow.
Here’s an example setState invoking method from a recent project:
Explaining the code:
- Line 31: firstApprovalResult is a class variable which stores the current state of my workflow. I use this throughout the workflow for various purposes. -1 means that we’re still waiting for the approval task to be completed.
- Line 34: If the firstApprovalResult changes to 1, it means that the task was approved. I get this variable from my task form (for help with using InfoPath task forms, see: https://sharepointgear.wordpress.com/2009/03/22/simple-sharepoint-workflow-with-infopath-task-form/)
- Line 37: This is where we actually set the approval status to Approved. Remember we said that our new <StatusColumnValue>s get added to the status enumeration. Well, the first one in the list takes on the Max enumeration. i.e. you always know which is your first custom status by addressing (Int32)SPWorkflowStatus.Max. Since our first custom status is Approved (see workflow.xml above), the workflow status is now set to Approved. Currently, Max carries the value of 15, so you could theoretically just set the state to 15, but this is bad practise as Microsoft may wish to add more default statuses in future, which could ruin your code’s integrity.
- Line 39: This is where we actually set the approval status to Rejected. Since we already know that our first custom status takes on the Max enumeration, then our second custom status can be addressed as Max+1. And since the second <StatusColumnValue> in our workflow.xml is Rejected, the workflow status is now set to Rejected. So, the order that you add the custom statuses to the workflow.xml is very important (in case you missed the bold text above 🙂
References
I always try to credit the article that I learnt a technique from. Unfortunately, in this case, I can’t find the bookmark for the article that taught me to setState.
A software engineer by trade, with a Masters degree in eCommerce, I focus on delivering end-to-end business solutions. ...and SharePoint's my platform.
SharePoint Gear 
Good post. In most post not say about add ExtendedStatusColumnValues to workflow.xml. Thanks you.