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.

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

  1. SharePoint 2013 : Introduction to Workflow Services API
  2. SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service
  3. 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 see how we can start the workflow on any desired list item programmatically using “Workflow Instance Services”.

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

1

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

2

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

1.Specify the Workflow Definition ID which needs to be started on the list item

2.Specify the List ID to which this workflow is associated

3

3.Instantiate the List Object by calling “getById” method

4.Instantiate the List Item Object by calling “getItemById” method

5.Instantiate Service Manager Object as earlier

6.Query all the available Subscriptions for the Workflow Definition based on Definition ID specified in Step 1 using Workflow Subscription Service

4

7.For a specific Subscription call “startWorkflowOnListItem” function of Workflow Subscription Service by passing following parameters to it:

  1. Workflow Subscription Object
  2. List Item ID
  3. 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.

5

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:

6

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:

7

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

8

Hope you enjoy this series on Workflow Services.

Please share your feedback if you find it helpful.

Advertisements

SharePoint 2013 : Introduction to Workflow Services API

Workflow Services API are one of the newest feature extensions that are shipped with SharePoint 2013. These API allows you to perform lot of operations on Workflows couple of them is shown in the list below:

  1. Create Workflows
  2. Edit Workflows
  3. Start Workflows
  4. Stop Workflows
  5. List Workflows
  6. Copy Workflows from one site to another
  7. Associate Workflows to lists
  8. Export Workflows to WSP …. And the list goes on

Being this API a part of SharePoint CSOM, it is accessible using both JavaScript & C# Managed Code.

Workflow Services are primary meant to work with SharePoint 2013 Workflows (or WF4 Workflows) but also shipped with limited support for SharePoint 2010 Workflows (or WF3 Workflows).

The Workflow Services API consists of 4 Services to deal with different scenarios:

  1. Workflow Instance Service
    1. Can be used to Query Workflow Instances
    2. Can be used to Create new Instances based on existing Associations
    3. Can be used to Create new Instances on List Items and Sites
    4. Can be used to Communicate existing Instances
      1. To Cancel Workflow
      2. To Terminate Workflow
      3. Publish Custom Events
  2. Workflow Subscription Service
    1. Can be used to Query Workflow Associations
    2. Can be used to Create Workflow Associations
  3. Workflow Deployment Service
    1. Can be used to Query Workflow Definitions
    2. Can be used to Validate Workflow Definitions
    3. Can be used to Create Workflow Definitions
    4. Can be used to Validate Workflow Definitions
  4. Workflow Interop Service
    1. Can be used to Interact with SharePoint 2010 Workflows in SharePoint 2013

In this first article on Workflow Service we will consider a very simple scenario where we will list down all the workflows created [only WF4 Workflows] with in a site, to see important details like Name, ID and Published Status.

In order to step up this demo I have one site “Development” which is created as shown below:

1

If we open this site in SharePoint Designer, and visit the Workflow Section on the left as shown below, we found no workflows has been created as of now.

2

So first of all let’s create a new Reusable Workflow, give it a name “Parent – Workflow”. Make sure Platform Type must be “SharePoint 2013 Workflows”.

Click Ok to save the Workflow definition.

3

Now add a simple step called “Logging” to this workflow and add a “Log to History” activity to this list.

Check for the errors

Save the workflow

Publish the workflow as shown below:

4

Once you publish the workflow it will be place on the right container in SharePoint Designer.

5

Now go to any list and add this workflow to the list

6

7

In the similar fashion create another workflow and let say called it as “Unpublished Workflow”, the only difference this time is we are not going to publish it.

Just create it and save it, that’s all.

8

OK, this will suffice to prepare our environment for this demo.

Now the next task in line is to create a UI element that can trigger the action to list workflows. For this I have created a simple page with a Button on it “List Workflows”

9

The simple HTML that bring this button up is as follows

10

This button is hooked up with an Event Handler named “ListWorkflow()”

In order to implement the logic behind this Event Handler, we need to include the necessary references in our code:

  1. JQuery.js
  2. MicrosoftAjax.js
  3. SP.Runtime.js
  4. SP.js
  5. SP.Core.js
  6. SP.WorkflowServices.js

11

Then proceed with the code as follows:

12

  1. Initialize Context Variable
  2. Initialize the Service Manager object in context of the current site
  3. Initialize Workflow Deployment Service Instance

13

  1. Get Handle on Workflow Definitions Collection
  2. Get Current Workflow Definition
  3. Retrieve Workflow Properties from Workflow Definition

You can view all the properties exposed by Workflow Definition by placing breakpoint on line 5 shown above:

14

For this demo, I have taken only four properties to display:

  1. Workflow ID
  2. Workflow Display Name
  3. Workflow Description
  4. Workflow Published Status

So we click “List Workflow” button we can be able to see the selected details for the Workflow Definitions which are stored on a specific site as show below:

15

  1. Click Button
  2. Site URL for which the Workflow Definitions are listed
  3. Workflow definition details

The information shown above is really useful to work with any Workflow Definition and we will be going to see this information in action in the series of upcoming articles on Workflow Services dealing with a bit more advanced scenario.

You can visit the next post in this series:

SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service