Using association data for starting workflows
In SharePoint 2013, workflow associations bind workflow definitions to a specific scope, such as a SharePoint site or SharePoint list, with specific default values. These values are expressed as association data. Nintex Workflow 2013 uses association data to store the default values of workflow variables for a workflow associated with either a site or a list. You can also specify different values by providing association data when invoking the StartSiteWorkflow, StartWorkflow, or StartWorkflowOnListItem methods. The format in which the association data is stored depends on whether the initiation form is an Info
Retrieving association data
You can use the Representational State Transfer (REST) service operations provided by the Web service resource in SharePoint 2013 to retrieve information about workflow associations for a SharePoint site or SharePoint list.
For example, the following GET operation retrieves all of the workflow associations, including association data, for a specified list, where <ListTitle> represents the title of the SharePoint list and <SiteUrl> represents the URL for a SharePoint site.
http://<SiteUrl>/_api/web/lists/getByTitle('<ListTitle>')/WorkflowAssociations
Each version of each published Nintex workflow has a corresponding workflow association, so iterating through the returned collection of workflow associations can take some time. If you know the identifiers of both the SharePoint site or list and the specific workflow association, you can use those identifiers to more quickly retrieve the association data for that workflow association. The following example illustrates use of those identifiers in a GET operation that returns the association data for the specified workflow association and SharePoint list.
http://<SiteUrl>/_api/Web/Lists(guid'48d1e62d-8d86-42ec-9c57-8315bc55a686')/WorkflowAssociations(guid'868570c1-16bb-4958-a075-beaffb5b8693')/AssociationData
For more information about using the Web resource and its REST service operations in SharePoint 2013, see Webs REST API Reference on Microsoft Developer Network.
Association data for Nintex Forms
If the workflow association uses a Nintex Forms form as the initiation form, the custom association data is stored as an XML element named Data, which contains a child element for each workflow variable defined in a workflow. The following example illustrates the association data for a workflow with one defined workflow variable, where WorkflowVariableName represents the encoded internal name of the workflow variable and Value represents the value for the workflow variable:
<Data> <WorkflowVariableName>Value</WorkflowVariableName> </Data>
Each workflow variable is represented by a corresponding child XML element in the <Data> element, even if the workflow variable does not have a default value or is not displayed on a start form. If a workflow variable does not have a value, an empty XML element, as shown in the following example, is specified:
<Data>
<WorkflowVariableName />
</Data>
Workflow variable names in association data
Nintex generates an internal name, to ensure XML compliance, for each variable defined in a workflow. The name of the workflow variable is encoded to ensure XML compliance, so the name presented in the Workflow designer may not match the corresponding XML element name. After XML encoding, Nintex Workflow 2013 also replaces dash characters (-) with the corresponding character value, _x002d_.
For example, if a workflow variable named Variable-1 is defined in a Nintex workflow, the corresponding child XML element in the association data is named <Variable_x005F_x002d_1>.
Workflow variable values in association data
If a workflow variable does not have a specified value, an empty child XML element, with no value, is included in the association data. If a workflow variable has a specified value, a child XML element is included in the association data, in which the value is represented as an XML-encoded string value.
However, the content of that string varies, depending on the data type of the workflow variable. The following list provides more information on the expected value format for each workflow variable data type.
| Data type | Description |
|---|---|
| Single line of text |
An XML-encoded string, representing the value of the variable. <Variable>A single line of text.</Variable> |
| Multiple lines of text |
An XML-encoded string, representing the value of the variable. <Variable>Multiple lines of text\nincluding encoded new line and carriage return characters.</Variable> |
| Choice |
An XML-encoded string, representing the selected items for the variable. The string representation depends on the display format of the Choice workflow variable.
|
| Number |
An XML-encoded culture-invariant string, representing a double-precision floating point number. <Variable>2.65</Variable> |
| Date and Time |
An XML-encoded ISO 8601 string, representing the Coordinated Universal Time (UTC) equivalent of the value of the variable. The string representation depends on the display format of the Date and Time workflow variable.
Also, the Date and Time workflow variable supports a special value, [today], which represents the current date and time. If this value is specified, the value is replaced at run time with the current date and time for the local time zone. The following example illustrates the use of this value. <Variable>[today]</Variable> |
|
Yes/No |
TRUE if the value of this variable is set to Yes; otherwise, FALSE. <Variable>FALSE</Variable> |
|
Person or Group |
An XML-encoded string, representing an array of encoded claims, delimited by semi-colon (;) characters. For more information about claims encoding in SharePoint 2013, see SharePoint 2013: Claims Encoding - Also Valuable for SharePoint 2010 on Microsoft TechNet. <Variable>i:0#.w|domain\\user1;i:0#.w|domain\\user2</Variable> |
| Integer |
An XML-encoded culture-invariant string, representing a 32-bit signed integer. <Variable>25</Variable> |
|
List Item ID |
You cannot specify a value in association data for a workflow variable using this data type. Any value specified in association data is overwritten by the identifier of the current list item when the workflow starts, and is automatically updated by the workflow if the current list item changes during execution. |
| Action ID |
You cannot specify a value in association data for a workflow variable using this data type. Any value specified in association data is overwritten by the identifier of the current action when the workflow starts, and is automatically updated by the workflow if the current action changes during execution. |
|
Collection |
You cannot specify a value in association data for a workflow variable using this data type. Any value specified in association data is overwritten by an empty ArrayList, created when the workflow starts, and is automatically updated by the workflow if the contents of the created ArrayList changes during execution. Collection variables can be manipulated by using the Collection operation action. For more information about using the Collection variable, see Tutorial: How to use the Collection variable. |
Note: Workflow variables using the List Item ID, Action ID, or Collection data types cannot have a default value, and are represented in association data by an empty XML element.