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.

ValueDescription
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>

See Also

Concepts

Workflows

Operations

Managing workflow schedules

Reference

AddWorkflowSchedule

Web Service Reference