SharePoint 2013: How to Start Workflow on a List Item Using Workflow Instance Service

We are here in the fourth and final post in the series of four articles on Workflow Services in SharePoint.

The last three posts in this series can be reached out at the below links:

SharePoint 2013 : Introduction to Workflow Services API
SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service
SharePoint 2013 : How to Add Workflow Associations to a List using Workflow Subscription Service

This article will take you through to the automation steps of another more common requirement i.e. “Starting a Workflow on any List Item Programmatically”.

In order to automate this task we can leverage Work Instance Service.

Assuming that you are following me all along the previous three articles of this series, and you are already aware of that we have a List with the name “Workflow Testing” in the Child Site which we had created in one of the earlier posts of this series.

We also got a Workflow Definition “Workflow on Orders in Parent Site” Copied to this Child Site and published in context of “Workflow Testing” List.

Now let's see how we can start the workflow on any desired list item programmatically using “Workflow Instance Services”.

For this demo le's consider a target item “Test Item 3” in “Workflow Testing” List on which we need to start the workflow, as shown below:

testing
In order to trigger the Workflow Start process, we have got a super simple UI with one HTML button “Start Workflow” as shown below:

services

Now next thing is to get into the code line by line to understand the logic behind this implementation:

Specify the Workflow Definition ID which needs to be started on the list item,
Specify the List ID to which this workflow is associated,
Instantiate the List Object by calling “getById” method.
Instantiate the List Item Object by calling “getItemById” method.
Instantiate Service Manager Object as earlier.
Query all the available Subscriptions for the Workflow Definition based on Definition ID specified in Step 1 using Workflow Subscription Service,
For a specific Subscription call “startWorkflowOnListItem” function of Workflow Subscription Service by passing following parameters to it:

a.Workflow Subscription Object
b.List Item ID
c.Initiation Parameters:

This is applicable only when the Workflow is expecting any Initializing Parameters in the Workflow Definition, else we can pass an empty object to the function as shown below.

With this we are done with code development.

Now click on the HTML Button to test the code and if the code execution succeed you will get an Alert saying “Workflow Started” as shown below:

workflow

In order to test the implementation from UI, we need to browse the “Workflow Testing” list and look for the target item which is “Test Item 3” in our case.

Look for the Workflow Status column for this item to see if the Workflow status has been updated as shown below:

testing

Click on the workflow status to see full history of workflow execution to ensure that all operations are executed as expected.

status

Hope you enjoy this series on Workflow Services.

Please share your feedback if you find it helpful.