StartWorkflow
Starts an instance of a reusable or list workflow on the specified file in a SharePoint document library, optionally providing association data.
Syntax
public Guid StartWorkflow( string fileUrl, string workflowName, string associationData )
Parameters
- fileUrl
- Type: System.String
Optional. The absolute or relative URL of the file on which to start the reusable or list workflow. If a relative URL is specified, the URL must be relative to the current SharePoint website.
- workflowName
- Type: System.String
Optional. The name of the reusable or list workflow.
- associationData
- Type: System.String
Optional. The association data to use for the reusable or list workflow. If association data is not specified, default values specified for workflow variables in the workflow are used.
Type: Guid
The identifier of the started workflow instance.
Remarks
The method first attempts to retrieve the list item for the file URL specified in fileUrl, and then attempts to retrieve an existing workflow association between the list for the retrieved list item and the list workflow specified in workflowName. If a workflow association between the list and the specified workflow does not exist, the method then iterates through each content type for the list, attempting to retrieve a workflow association between a content type for the list and the reusable workflow specified in workflowName. If a workflow association between any of the content types for the list and the specified workflow does not exist, an error occurs.
If a workflow association can be retrieved, the method attempts to start the reusable or list workflow immediately. If the workflow cannot be started immediately, an error occurs; otherwise, the method returns the identifier of the resulting started workflow instance.
Setting Association Data
The associationData element contains an XML-encoded string, representing an XML fragment. The XML fragment is a single element, named Data, that can contain values for workflow variables defined in the site workflow. For more information about using association data, see Using association data for starting workflows.
Note: You cannot include the Data element within the associationData element without first converting it to an XML-encoded string; otherwise, an error occurs. For an example, see StartWorkflowOnListItem.
Example
The following example demonstrates how to use this operation to start a list workflow for a file in a document library.
Request
The following SOAP request attempts to start the TestDocWorkflow list workflow on a text file named TestDocument.txt.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:nin="http://nintex.com">
<soap:Header/>
<soap:Body>
<nin:StartWorkflow>
<nin:fileUrl>/Shared%20Documents/TestDocument.txt</nin:fileUrl>
<nin:workflowName>TestDocWorkflow</nin:workflowName>
<nin:associationData />
</nin:StartWorkflow>
</soap:Body>
</soap:Envelope>
Response
The following SOAP response returns the identifier of the started workflow instance.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<StartWorkflowResponse xmlns="http://nintex.com">
<StartWorkflowResult>02e77c89-e778-42e6-9ba6-a9d73995feac</StartWorkflowResult>
</StartWorkflowResponse>
</soap:Body>
</soap:Envelope>