Workflow Association and Initiation Forms (Windows SharePoint Services)
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Association and initiation forms are displayed for users to complete before any workflow actually starts. You can use these forms to enable users to set parameters and other information for the workflow in advance. Association forms address how the workflow applies to a specific list, library, or content type; initiation forms address how the workflow applies to a specific SharePoint item.
Association forms are displayed to administrators when they first decide to add—or associate—a workflow with a particular list, document library, or content type. You can use association forms to let an administrator specify parameters, default values, and other information for the workflow as it applies to items on the list, library, or content type with which the administrator is associating it.
Initiation forms are displayed to users when they start a workflow on a specific SharePoint item. You can use initiation forms to let users override or append the association parameters set by administrators, or specify additional parameters or information about the workflow as it applies to the specific SharePoint item. Not all workflows need initiation forms.
The initiation form can be the same form as the association form. For example, using the same form for each workflow form enables you to let administrators set certain default parameters during workflow association, and then let the user who actually starts the workflow instance on a particular item review and overwrite those default parameters.
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 to the custom form page you want to use for workflow association. For example:
AssociationURL="MyWkflAssociationPage.aspx"
Note
Windows SharePoint Services 3.0 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". Windows SharePoint Services does not support link fix-up in workflow template definitions.
For more information about workflow definitions, see Workflow Definition Schema.
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 and initiation conditions, and whether the workflow runs on items, folders, or both.
When the administrator clicks the Next button on this page, Windows SharePoint Services examines the AssociationURL attribute of the Workflow element, in the workflow template definition, to determine the proper form to load.
To provide custom data to the association form, you can store this information in the AssocationData element. For example, you could use this element to store default values you want to pass to the association form when it is displayed. The AssocationData element can contain any valid XML. Your form can then load that association data from the workflow template.
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 must program 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 UpdateWorkflowAssociation 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.
Specifying Initiation Forms
If you want your workflow to have an initiation form, you must set the InstantiationURL attribute of the Workflow 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.
InstantiationURL="MyWkflInitiationPage.aspx"
Note
Windows SharePoint Services 3.0 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 set an absolute path, such as "http://site/library/page.aspx", or a server-relative path, such as "/layouts/page.aspx". Windows SharePoint Services does not support link fix-up in workflow template definitions.
For more information about workflow definitions, see Workflow Definition Schema.
Initiation Form Processing
When a user starts a workflow on a specific item, Windows SharePoint Services examines the InstantiationURL attribute of the Workflow element, in the workflow template definition, to determine the proper form to load.
Windows SharePoint Services loads the specified form, passing to it the following query parameters in the URL:
List The GUID of the list to which the item belongs.
ID The ID of the list item on which the workflow is started.
Source The page from which the user started the workflow.
TemplateID The GUID of the workflow association.
In addition, you can program your form to load the association form data for this workflow association. This information is contained in the AssociationData property of the SPWorkflowAssociation object that represents the workflow association.
The workflow developer must program 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.
Use the SPWorkflowManager object to invoke the StartWorkflow method, passing the appropriate SPListItem and SPWorkflowAssociation objects. Use the eventData parameter to pass the initiation form data in string format.
Return the user to the source page from which he or she 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 OnWorkflowActivated event of the workflow itself.
Any Windows SharePoint Services workflow must start with an OnWorkflowActivated activity. The OnWorkflowActivated activity contains a property, WorkflowProperties, that returns an SPWorkflowActivationProperties object. This object 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 AssociationData property returns a System.Collections.Hashtable object that represents the custom data provided by the workflow initiation form.