1. Specifying Association Forms
You specify a workflow's association form in the workflow template definition XML. To do this, set the value of the AssociationURL attribute of the Workflow Element (Elements) element to the custom form page you want to use for workflow association. For example:
AssociationURL="MyWkflAssociationPage.aspx"
2. Association Form Processing
When an administrator selects a workflow to associate with a given list, library, or content type, Windows SharePoint Services displays the Add a New Workflow page. The administrator can use this page to specify settings common to all workflows, such as the workflow definition, initiation conditions, and whether the workflow runs on items, folders, or both.
Because the workflow association is not created until the custom association form is submitted, Windows SharePoint Services also passes the following query parameters to the custom association form:
<input type="hidden" name="WorkflowDefinition" value=<% _STSWriteHTML(Request.Form["WorkflowDefinition"]); %>>
<input type="hidden" name="WorkflowName" value=<% _STSWriteHTML(Request.Form["WorkflowName"]); %>>
<input type="hidden" name="AddToStatusMenu" value=<% _STSWriteHTML(Request.Form["AddToStatusMenu"]); %>>
<input type="hidden" name="AllowManual" value=<% _STSWriteHTML(Request.Form["AllowManual"]); %>>
<input type="hidden" name="RoleSelect" value=<% _STSWriteHTML(Request.Form["RoleSelect"]); %>>
<input type="hidden" name="AutoStartCreate" value=<% _STSWriteHTML(Request.Form["AutoStartCreate"]); %>>
<input type="hidden" name="AutoStartChange" value=<% _STSWriteHTML(Request.Form["AutoStartChange"]); %>>
<input type="hidden" name="GuidAssoc" value=<% _STSWriteHTML(Request.Form["GuidAssoc"]); %>>
The workflow developer is responsible for programming what happens when the administrator submits changes to the form. In general, the custom workflow association form must perform the following actions:
-
Examine the value of the GuidAssoc parameter to determine whether the user is adding a new workflow association or editing an existing workflow association.
-
If the user is adding a new workflow association, call the AddWorkflowAssociation method to create a new workflow association.
-
If the user is editing an existing workflow association, call the Update method to update that workflow association.
-
Create the task list for the workflow, if it does not already exist.
-
Use the data collected from the user to set properties of the SPWorkflowAssociation object, as appropriate.
-
Create the workflow history list, if necessary.
3. Specifying Initiation Forms
If you want your workflow to have an initiation form, you must set the InstantiationURL of the Workflow Element (Elements) element in the workflow template definition. Set this element to the form you want to use to collect the workflow initiation data, as shown in the following example.
<Instantiation_URL>MyWorkflowInitiationPage.aspx</Instantiation_URL>
4. Initialization Form Processing
When a user starts a workflow on a specific item, Windows SharePoint Services examines the InstantiationURL of the Workflow Element (Elements) element, in the workflow template definition, to determine the proper form to load.
Windows SharePoint Services loads the specified form, passing the form the following query parameters in the URL:
List The GUID of the list to which the item belongs.
ID An incremental ID that represents the order in which items are added to the list.
Source The page from which the user started the workflow.
TemplateID The GUID of the workflow template.
In addition, if you have stored custom data in the AssociationData Element (Workflow) element of the workflow definition, you can program your form to load this information as well. For example, you could use this element to store default values you want to pass to the association form when it is displayed. The AssociationData Element (Workflow) element can contain any valid XML.
The workflow developer is responsible for programming what happens when the user submits changes to the page. In general, the form must perform the following actions:
Locate the SPWorkflowManager object for the current site.
Create a new SPWorkflowEvent instance.
Set the EventData property of that SPWorkflowEvent object to the data collected from the user.
Start the workflow by calling the StartWorkflow method, passing the appropriate ListItem object, SPWorkflowTemplate object, and the new SPWorkflowEvent as arguments.
Return the user to the source page from which they started the workflow
When the M:Microsoft.SharePoint.Workflow.SPWorkflowManager.StartWorkflow(Microsoft.SharePoint.SPListItem,Microsoft.SharePoint.Workflow.SPWorkflowAssociation,System.String) method is called, the workflow manager creates an instance of the workflow on the SharePoint item. The workflow manager then passes the data gathered using the initiation form to the OnWorkflowActivation event of the workflow itself.
Any Windows SharePoint Services workflow must start with an OnWorkflowActivation event. The OnWorkflowActivated activity contains a property, WorkflowProperties, that returns an SPWorkflowActivationProperties object that represents the initial properties of the workflow as it starts, such as the user who added the workflow and the list and item to which the workflow was added. In addition, the SPWorkflowActivationProperties.CreationData property returns a System.Collections.Hashtable object that represents the custom data provided by the workflow initiation form.
