Developing Workflows in VS: Part 1 - Workflow Objects and A Crash Course on Mechanics
The Workflow Objects
Workflow Template vs. Association vs. Instance
There are a few important terms in workflow that often get confused: template, association, and instance. If you don’t read anything else from this series, make sure you understand this section. Keeping these terms straight is critical to understanding other documentation and the pieces of a SharePoint workflow.
First we have a template. The template is the SharePoint workflow "Feature" that is deployed to a site collection (a Feature is a custom SharePoint part, such as web parts or content types). The template basically says, "Hey, this workflow feature uses these forms and this assembly." It’s just a skeleton stored in the central repository for a site collection that any list or content type can look at.
But it’s just for looking; a list can’t use the template directly. Should the workflow be started automatically? Where should tasks be stored? We need an extra layer to customize a template with this information. Enter the association. To connect the list to the template, we create an association. An association stores customizations for the template and binds it to a list or content type. Such customizations can include a title for the association, when to start running the template (e.g. manual or automatic start), and custom workflow settings like default approvers. The important thing to understand here is that a list or content type can have multiple associations of the same template. For example, you can have associations Expense Approval and Publish Approval that that bind to the Approval workflow template, each customized with their own settings and default values; they should just be named differently.
When we actually start a workflow, we create a workflow instance of an association (not a template). Each item can run one instance of a particular association at a time. So there can only be one ExpenseApproval instance running on each list item, and one Publish Approval instance. But both are based on the Approval template.
So the workflow that you develop in Visual Studio is a workflow template that defines the general feature. The Association form that it specifies collects customized association data to create the association. The Initiation form collects data to create a new instance from an association, and uses the association data to pre-populate initial values.
Tasks, History Items, and Modifications
The other important workflow-specific SharePoint objects are the workflow task, workflow history item, workflow modification.
Once a workflow is running, it can call any SharePoint object model code. Because SharePoint workflow focuses on human-based process rather than automating purely programmatic steps, an important action for workflows is creating tasks on a SharePoint task list specified in the association. Workflow tasks are like normal SharePoint task items, but they also link to the workflow that created them and can notify their "parent" workflow when they change or get deleted so that the workflow can take appropriate action. Users can edit a workflow task by using a task form (also specified in the template), and the workflow can process these edits and mark the task as complete. Since part of the benefit of having workflows is to gain visibility into a process, the workflow can log events to a workflow history list. History items are just list items that have special columns for workflow-specific data, such as instance id, association id, etc. These items appear on the workflow status page, which filters according to instance id.
But as with any process, sometimes a workflow needs to be adjusted while it in progress, for example, if a new person needs to be added, if a due date needs to be changed, or if a parameter, such as a "max limit" for an expense report that determines whether the report requires manager approval, should be reduced in-flight. To allow users to talk to or change workflows in progress, SharePoint has workflow modifications. The modification object represents a channel of communication with a workflow, and once registered with a workflow, can "wake" a workflow up when the modification is called. A modification form collects data required for the modification, and once the workflow is awake, it can perform whatever modification the developer programs. In general, use modifications if you need to talk to a running workflow and don’t want to do it through tasks.
Understanding these fundamental concepts in SharePoint workflow will help you understand how all the pieces fit together when you create your workflows. To summarize, here is an application of these terms in the workflow life cycle:
- Developer develops a workflow template.
- Server box administrator deploys the template to a site collection.
- List administrator associates a workflow template with a list or content type on that site collection to create a new association.
- User starts an instance of a workflow association on an item (or workflow instance starts automatically on event).
- Workflow executes, perhaps creating some tasks and history items on the Tasks and Workflow History lists specified in the association.
- Workflow owner (the person who started the workflow) or list administrator can talk to a running workflow at any time by modifying it with a modification.
David Chappell has a great whitepaper on MSDN that describes the structure in more detail, so if you’re interested, I’d highly recommend it:).
Crash Course on Workflow Mechanics
It’s not critical understand the low level details of how workflows operate internally to develop workflows, but there are a few the important high level concepts that will help:
- When running workflows reach a point in the code, a.k.a. schedule, where they need to wait for something to happen (such as a task edit), they are serialized (i.e. turned into binary) and dehydrated to the SharePoint database. This means that the workflow object is turned into a string and stored to the database. We can say that the workflow is asleep.
- Dehydrated workflows are no longer in memory.
- When the event the workflow is waiting for happens, the workflow is deserialized and wakes up, or rehydrates, then continues where it left off in the schedule.
A typical SharePoint workflow is a series of "execute custom code, dehydrate, and rehydrate" cycles. Dehydration and rehydration requires the use of workflow services.
A local service is a channel of communication between SharePoint and the workflow. The important thing to know about them is that they can manipulate workflow items and register workflows with SharePoint events, put workflows to sleep to wait for the events, and wake up workflows when those events fire.
The SharePoint workflow service APIs provides both methods and event handlers. Methods will perform actions, and handlers will put the workflow to sleep and wake up on events. For example, using the CreateTask service method will create a task and register the workflow for events on that task. Using the OnTaskChanged service event handler mapped to that task will dehydrate the workflow while it’s waiting and rehydrate the workflow when the task is changed.
To map these functions to the same task, the services use correlators, unique identifiers that the workflow engine can use to map events and actions to objects. These are specified in a workflow by using correlation tokens and GUIDs. (Both correlation token and GUID are required.)
Ok, so that was really dry. But basically, the key thing to know is that you must use the service methods to get the workflow to respond to events on items. The other thing to know about service methods is that they’re transacted actions, batched actions that are not committed until the workflow is dehydrated. This means that if you use CreateTask, the task will not actually be created until the workflow is successfully dehydrated.
Pitfall: Operating on uncommitted items
Do not use SharePoint object model (OM) calls on tasks or items that have not been committed. Remember to dehydrate first, using an event handler or delay, before trying to fetch objects. For example, if you use CreateTask, the SPListItem for the task will not exist until you use an event handler like OnTaskCreated or Delay to put the workflow to sleep. Using other workflow service methods is ok, but don’t use direct OM on the SPListItem object before putting the workflow to sleep.
-Eilene Hao, Program Manager, SharePoint Workflow
