Workflow Modification Forms (SharePoint Foundation)
Applies to: SharePoint Foundation 2010
You may want to enable your users to alter the workflow at certain points while it is running on an item. For example, you might want to enable a user to assign his or her task to another person or even add a specific task to the workflow. The options you present to users to change the workflow as it is running on an item are called modifications.
You can create modification forms that enable users to specify the parameters of modifications.
As you design your workflow, you create a modification by adding an EnableWorkflowModification activity to the workflow. The availability of the modification is determined by the EventHandlingScope activity to which you add the EnableWorkflowModification activity. Defining a modification adds a link on the workflow status page for that particular modification. When the containing EventHandlingScope activity comes into scope as the workflow runs, Microsoft SharePoint Foundation makes the modification link available to the user. When the containing activity passes out of scope, Windows SharePoint Services removes the modification link from the workflow status page.
The modification link on the workflow status page directs the user to the workflow modification form.
Specifying Modification Forms
Each modification form you use in your workflow must have its own GUID. SharePoint Foundation uses this GUID to match the modification selected by the user with the appropriate form.
To specify a modification form, you must set three pieces of data:
Set the ModificationID property of the EnableWorkflowModification activity to the GUID you generated for your modification.
In the workflow template definition, set the ModificationURL attribute of the Workflow element to the modification form you want to use.
If your workflow includes multiple modifications, you can program the form you specify with this attribute to do the following:
Display a different view of the form, based on the modification identifier passed to this form.
Redirect to a separate form, based on the modification identifier passed to this form.
Note
SharePoint Foundation supports absolute or server-relative paths in the workflow template definition. You must express all form path URLs in one of these formats. For example, you can use an absolute path, such as "http://site/library/page.aspx", or a server-relative path, such as "/layouts/page.aspx". SharePoint Foundation does not support link fix-up in workflow template definitions.
In the workflow template definition, add a Modification_guid_Name element, where guid is the GUID you generated for your modification. Set this element to the name you want to give your modification. SharePoint Foundation displays this name as the link text for the modification link on the workflow status page. For example:
<Modification_GUID_Name>Add a New Reviewer</Modification_GUID_Name>
Modification Form Processing
When a particular EnableWorkflowModification activity comes into scope, the workflow invokes the EnableWorkflowModification method and passes SharePoint Foundation two pieces of data as parameters:
The GUID of the modification form, as stored in the ModificationId property of the activity.
The information to pass to the modification form, in string form; this information is mostly data context, as stored in the ContextData property of the activity.
Note
The workflow developer must generate the string that contains the context data to pass in the EnableWorkflowModification method. For ease of programming, we recommend that developers create an object for each modification they create. Each modification object should have an XML serialization schema that exactly matches the schema of the modification form's primary data source.
SharePoint Foundation examines the workflow template definition XML to determine the name of the modification, and uses this as the link text for the modification link it adds to the workflow status page.
In the SharePoint object model, the modifications currently available for a workflow instance are listed in the SPWorkflowModificationCollection object.
If a user clicks a given modification link, SharePoint Foundation examines the workflow template definition XML, specifically the ModificationURL of the Workflow element, which specifies the modification form to display. SharePoint Foundation loads the form and passes the context data from the EnableWorkflowModification activity.
The modification form developer must program what actions happen when the user submits the modification form. In most cases, the form calls the ModifyWorkflow method, passing the workflow instance ID, an SPWorkflowModification object, and, optionally, the updated context information. This action modifies the running workflow instance accordingly.
To handle the workflow modification event, add an OnWorkflowModified event activity to the workflow. SharePoint Foundation raises this event activity when the ModifyWorkflow method is invoked. This activity is most beneficial when used within the event handler of an EventHandlingScope activity. SharePoint Foundation passes the modification context data to the event activity.
Again, the workflow developer must parse the context data that is passed as a string to the OnWorkflowModified event activity.
See Also
Concepts
Workflow Association and Initiation Forms (Sharepoint Foundation)