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 : How to Add Workflow Associations to a List using Workflow Subscription Service

Welcome to the third article of the series on JSOM Support for SharePoint 2013 Workflows.

Previous Articles in this Series can be reached at the following URLs:

  1. SharePoint 2013 : Introduction to Workflow Services API
  2. SharePoint 2013 : How to Copy Reusable Workflows from one site to another using Deployment Service

In this article we will look into a more obvious issue with SharePoint Designer Workflows, i.e. moving SPD workflows from one list to another within same or a different site.

This article will explain the steps on how to automate the Workflow movements from one location to another.

In order to showcase the scenario, we need to set up the prerequisites and in the next few steps we will work on the same.

We are having a list by the name “Orders” in the Parent Site as shown below:

1

We will create a workflow in Parent Site [that will be copied to the child site later on], let’s call it “Workflow on Orders in Parent Site” and get it associated with “Orders” List as shown in the steps below:

2

This is quite a simple Workflow with one step performing Logging Operation.

Once this Workflow Definition is Created and Published, we can get the Workflow ID as shown in the Article 1 of this series.

3

Here we are all done with configuration on Parent Site.

Now lets move on to the child site, where we have got another List by the name “Workflow Testing” as shown below:

4

Browse the child site in SharePoint Designer and look for the List ID for “Workflow Testing” List as shown below:

5

Now look for “Workflow History” and “Workflow Tasks” Lists and verify if they are present and if not we need to create them beforehand.

6

With this we are all done with setting up the prerequisites for this demo.

Now let take a deep dive in the code base to understand its composition-

1.Specify the Workflow ID which needs to be copied from Parent to Child Site

2.Specify the List ID to which this Workflow needs to be associated in the Child Site.

7

3.Instantiate Object of Workflow Service Manager Object using Context of Child Site

4.Instantiate Object of Workflow History List in Child Site

5.Instantiate Object of Workflow Tasks List in Child Site

8

6.Set Workflow Details before copying it to Child Site

  • Set Workflow Name
  • Specify if the workflow is enabled
  • Specify the Workflow Definition ID
  • Specify the Workflow Status Column Name
  • Specify the Target List ID
  • Specify supported Event Types

9

7.Setting Workflow Properties

  • Setting Workflow List IDs
    • Task List
    • History List
  • We need to Set “FormData” property to blank if we don’t want to set any specific value, but must set this property.

10

8.Finally call “publishSubscriptionForList” function of Workflow Subscription Service to get the workflow published on to the target list.

11

Once this code gets execute without error, sure enough we will get the workflow created in the child site and associated with the specified list.

Following are the steps that we can take to verify if the Workflow is copied and associated as expected on the Child Site:

1.Browse the Child Site and navigate to the Workflows section and see if we get “Workflow on Orders in Parent Site” workflow created

12

2.Browse the Child Site in Browser and navigate to the “Workflow Testing”, see if Workflow Status Column with the Name “Demo Subscription Added” is created.

13

3.Start the workflow on any Item in the list and see if it is working as expected.

14

15

16

Hope this article provides you a brief idea on how can we make use of Workflow Subscription Services to add the Workflow Association to a specific list.

See you in the next article of this series.

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

In this article we will be exploring a solution to the one of the most obvious problems with SharePoint Designer Workflows i.e. copying the SharePoint Designer Workflow from one site to another.

In order to set the demo environment, I have got one site created called “Development” as shown below:

1

Since this demo needs to have another site also, so we got one more site created called “Child Site 0001”, which is a child site to “Development” Site as shown below:

2

Next thing is to launch SharePoint 2013 Designer, and connect to “Development” Site and browse Workflow section as shown below:

3

Now in order to showcase how to copy a Workflow from one site to another, we need to create a workflow (SharePoint 2013 Platform) no matter if it is Reusable or List Workflow.

In this demo we would be creating a Reusable Workflow as shown below:

4

Keeping this workflow functionality as simple as possible, we will add only one activity “Log to History List” and set the message to be displayed in the History Log, Check for Errors, Save Workflow Definition and lastly Publish Workflow Definition as shown below:

5

As soon as we are done with the steps above we can see a new Workflow added to the Reusable Workflow Section as shown below:

6

Now let’s add this workflow to a list and see it in action.

Visit any list and from the Ribbon choose Workflow Settings => Add a workflow as shown below:

7

Select a workflow that we have just published.

8

Configure the workflow association as shown below:

9

Now Start the workflow on any list item as shown below:

10

11

12

13

And that’s it. We are all done with our preparations on Parent Site.

Now it is time to move on to Child Site and see what it is up to.

So if we investigate the Child Site through SharePoint Designer we found currently no workflow is listed under Reusable Workflow Section.

14

Also if we verify the list of available Associations on any list, we won’t find any such Workflow listed under as shown below:

15

In order to trigger workflow copy action we got a super simple User Interface ready with a single button “Copy Workflow to Child Site” which is hooked up with an event handler that will execute the code to Copy the Workflow from Parent to Child Site.

16

Now as I promised in one of my earlier Blogs on Workflow services, we would need the Key information on workflow in Parent Site to get it copied to Child Site.

In case you like to know exactly how can we get this key information about a workflow please visit my blog SharePoint 2013 : Introduction to Workflow Services API.

17

Now let’s do the code dissection to know the complete driving logic as referred in the code below:

18

1.Specify the Workflow GUID which you want to Copy from one site to another

2.Get the Current Web and Collection of Webs inside it as we need to copy Workflow to a child site of the current site.

3.Create an Instance of WorkflowServiceManager to start the interaction with Workflow Manager Component with reference to the Parent Site

4.Get the Workflow Definition based on the Workflow GUID specified in step 1

19

20

5.Set the Workflow Display Name in the Child Site, this is a mandatory step which should not be ignored. The Key take away here is that we need to set the Display Name of this workflow same as it was in Parent Site, else it would not get saved.

6.Get the reference of the Child Site

7.Call the SaveWorkflowDefinition custom function by passing reference to the Child Site.

8.In SaveWorkflowDefinition custom function create an instance of WorkflowServiceManager to start the interaction with Workflow Manager Component but this time using the reference of Child Web

9.Save Workflow Definition

10.Publish Workflow Definition to Child Site

Once we are done with all the steps we can surely see a new Workflow that has been added to the Reusable Workflow section on the Child Site.

21

If we launch the child site in browser and visit any list to see the available Workflow Associations which are available to the List, we will get the new workflow (which is just copied from Parent Site) listed as shown below:

22

23

24

Now in order to test this workflow, add it to the list and configure the association as needed.

25

Now Start the workflow on any list item in the list.

26

27

And if we can see the same output as Parent Site then this will prove that the Workflow Definition is copied correctly from the Parent Site.

28

Though this is quite a simple approach but can be leveraged to implement & automate more complex business solutions.

Hope you find it helpful.

See you in the next article in this series. Stay tuned!!

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

SharePoint 2013: How to call OData Web Service End Point Using SharePoint Designer 2013 Workflows

In this article we are going to explore “Call HTTP Web Service” Workflow Action which is newly introduced in SharePoint 2013. In order to test this action will make use of OData Web Service End Point and target the following scenario where Customer Data needs to be auto populated based on the Customer ID using SharePoint Designer Workflow and OData Web Services.

Prerequisites:

  1. As this is going to be a List Workflow, make sure you must have a Custom List containing three columns “Customer ID”, “Full Name” and “Employer” already created on the site which you are going to select in Step 2 down the line. For the sake of this demo I have created a List with the name “Fill Customer Using Web Service” containing all the required columns.
  2. OData Web Service End Point http://services.odata.org/V2/Northwind/Northwind.svc should be accessible from the system which is running SharePoint Designer.
  3. Fiddler Web Proxy should be installed. You can get Fiddler from http://www.telerik.com/download/fiddler

Following are the steps involved in the development of Workflow Calling OData Web Service End Point:

Step-1 : Start SharePoint Designer 2013

Step-2 : Select the site in which you want to create the workflow

1

Step-3 : Go to left navigation pane and select Workflows

2

Step-4 : Select List Workflow [From Ribbon] > Select List [In our case it would be “Fill Customer Using Web Service”]

3

Step-5 : On the Workflow Designer select “Call HTTP Web Service” Action from the Action Ribbon Menu

4

Step-6 : Create the Workflow variables as shown below

5

Step-7 : Specify the Web Service End Point, and HTTP Method as shown below

6

Step-8 : Specify the variable of type Dictionary as placeholder for the incoming response data from the Web Service End Point

7

Step-9 : Now before proceeding any further lets’ analyze the response from the Web Service End Point. Please note that this step is of high importance and must not be neglected. Fiddler Web Proxy is your best friend when it comes to deal with Web Services. Analysis using Fiddler will provide us with the following Vital Information out of the response

  1. Structure of Data returned as a part of the response
  2. Properties Exposed by the Web Service End Point
  3. Data Types of the Properties
  4. Additional information on Error & Exceptions (If any)

8

Step-10 : After analyzing the data we come across the fact that we have got the required data in form of Key Value Pairs and the result set can be accessed by using the path “d/PropertyName”. So based on this knowledge we can now set the values for variable “CustomerName” & “CompanyName” using “Get an Item from a Dictionary” Action as shown below.

9

Step-11 :  As we have got the data from the Web Service End Point and stored in a set of variables, now it is time to update our list using “Set Field in Current Item” Action. We should use two instances of the same Action in order to set the value for both the fields using the variables as shown below

10

Step-12 : With this we are good to go. Now lets’ Save the Workflow Definition, Check for the Errors and if everything is fine Publish the Workflow.

13

14

15

16

17

Step-13 : In order to test the Workflow lets visit our List “Fill Customer Using Web Service” and quickly add a new item. We need to add the Customer ID only and rest of field will be populated by the Workflow

18

Step-14 : Specify the Customer ID and Save the item.

19

Step-15 : Start the Workflow on the newly added item.

20

21

Step-16 : And sure enough you will get the desired output with “FullName” and “Employer” Columns populated by our workflow using OData Web Service Call.

22

Though the scenario I mentioned here is quite simple, but this new add-on to SharePoint Designer 2013 is very powerful and could be utilized to cater complex business requirements without using any need of writing modules.

Hope this will help someone in need…