AddWorkflowScheduleOnListItem
Adds or updates a workflow schedule for a reusable or list workflow on a list item in a SharePoint list.
Syntax
public int AddWorkflowScheduleOnListItem( int itemId, string listName, string workflowName, string startDataXml, Schedule schedule, bool updateIfExists )
Parameters
- itemId
- Type: System.Int32
Required. The identifier of the list item on which to schedule the reusable or list workflow.
- listName
- Type: System.String
Optional. The name of the list on which to schedule the reusable or list workflow.
- workflowName
- Type: System.String
Optional. The name or GUID of the reusable or list workflow.
Note: Although the parameter is optional, an error occurs if a value is not specified.
- startDataXml
- 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..
- schedule
- Type: Schedule
Optional. The details of the workflow schedule.
Note: Although the parameter is optional, an error occurs if a value is not specified.
- updateIfExists
- Type: System.Boolean
Required. Indicates whether existing workflow schedules can be updated. The behavior of the method changes depending on the value of this parameter, as described in the following table.
Value Description true If the specified list item has existing workflow schedules for the specified workflow, then each existing workflow schedule is updated to use the association data and schedule details specified in, respectively, startDataXml and schedule, and the method returns the identifier of the existing workflow schedule that was last updated.
Otherwise, a new workflow schedule is created, and the method returns the identifier of the new workflow schedule.
false If the specified list item has existing workflow schedules for the specified workflow, then the method returns -1.
Otherwise, a new workflow schedule is created, and the method returns the identifier of the new workflow schedule.
Returns
Type: Int32
The identifier of the new or last updated workflow schedule; otherwise, -1 is returned if updateIfExists is set to false and workflow schedules for the specified workflow already exist for the specified list item.
Remarks
The method runs within the context of the current SharePoint site, determined by the endpoint URL used to invoke the operation. For more information about invoking SOAP methods for Nintex Workflow 2013, see Service operations.
If the list item specified in itemId, the list specified in listName, or the workflow specified in workflowName cannot be found, an error occurs.
The time zone for the current SharePoint site is used when specifying date and time values for the properties of the Schedule object.
Setting Association Data
The startDataXml 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 workflow. For more information about using association data, see Using association data for starting workflows.
Note: You cannot include the Data element within the startDataXml 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 add a workflow schedule for a list workflow on a file in a SharePoint document library.
Request
The following SOAP request adds a workflow schedule, which runs once a day on each workday that occurs between February 8, 2015 and March 1, 2015, for the list workflow named Test Workflow on the list item with an identifier of 2 in the list named TestContacts1.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:nin="http://nintex.com">
<soap:Header/>
<soap:Body>
<nin:AddWorkflowScheduleOnListItem>
<nin:itemId>2</nin:itemId>
<nin:listName>TestContacts1</nin:listName>
<nin:workflowName>Test Workflow</nin:workflowName>
<nin:startDataXml></nin:startDataXml>
<nin:schedule>
<nin:MaximumRepeats>0</nin:MaximumRepeats>
<nin:WorkdaysOnly>true</nin:WorkdaysOnly>
<nin:RepeatInterval>
<nin:Type>Daily</nin:Type>
<nin:CountBetweenIntervals>1</nin:CountBetweenIntervals>
</nin:RepeatInterval>
<nin:EndOn>EndDate</nin:EndOn>
<nin:StartTime>2015-02-08</nin:StartTime>
<nin:EndTime>2015-03-01</nin:EndTime>
</nin:schedule>
<nin:updateIfExists>false</nin:updateIfExists>
</nin:AddWorkflowScheduleOnListItem>
</soap:Body>
</soap:Envelope>
Response
The following SOAP response indicates that a new workflow schedule, with an identifier of 3, was successfully added.
<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>
<AddWorkflowScheduleOnListItemResponse xmlns="http://nintex.com">
<AddWorkflowScheduleOnListItemResult>3</AddWorkflowScheduleOnListItemResult>
</AddWorkflowScheduleOnListItemResponse>
</soap:Body>
</soap:Envelope>