▼

Saturday 31 May 2014

Managing SharePoint 2013 Workflows with CSOM

As you might have heard many times, the Workflow Architecture in SharePoint 2013 was entirely changed from what it was in SharePoint 2010. Instead of the Workflows running on the SharePoint server, they now have to run on a separate Workflow Manager.

On top of that, only declarative custom Workflow's are allowed to be deployed to the Workflow Manager. If there has to be any custom code, it has to be hosted in an external service and then consumed from the declarative workflow.

The Workflow Manager has certain activities and types which come predefined with it. This is called the Trusted Surface. Workflow Authors can consume these activities in their declarative workflows. A whole list of types and activities available under the trusted surface is here: http://msdn.microsoft.com/en-us/library/jj193509(v=azure.10).aspx and here: http://msdn.microsoft.com/en-us/library/jj193474(v=azure.10).aspx

This architecture is very much inline with Microsoft's strategy to move code execution away from the SharePoint server.

SharePoint 2013 supports two methods of workflow authoring. Authoring Workflows in the SharePoint 2013 engine and also authoring them in the SharePoint 2010 engine. Workflows which are authored in the SharePoint 2010 engine run on the SharePoint server and are allowed to execute code there. That architecture has not been changed and is available for backwards compatibility.

In the SharePoint 2013 Workflow platform, a Workflow definition is a Service Bus Topic and a Workflow Association is a Subscription to the topic. Topics and Subscriptions are used by the Service Bus to decouple message publishers from message subscribers. More about the Workflow Manager and Service Bus Pub/Sub architecture here: http://msdn.microsoft.com/en-us/library/office/jj163181(v=office.15).aspx#bkm_Subscriptions

Microsoft has also very recently added Workflow Management services to the Client Side Object Model (CSOM). The entire range of Workflow services available in the CSOM is published here: http://msdn.microsoft.com/en-us/library/office/dn481315(v=office.15).aspx. In this post, and the following posts, I will show you how to manage workflows with CSOM.

This is code works with SharePoint 2013 On-Premises as well as with SharePoint Online. I have created my sample code against SharePoint Online. Also, this code only works with Workflows which are authored on the SharePoint 2013 Workflow Engine. I will be writing another post on the CSOM Interop Service in which I will show how to start SharePoint 2010 Workflow Engine authored Workflows.

Before you run this code, you will need to create a Workflow (Definition) either via SharePoint Designer 2013 or through Visual Studio 2012/2013 and deploy it to your target site. You can then use this code to dynamically create associations of the Workflow, and also to start those associations.

You will need to reference the following Assemblies:
Microsoft.SharePoint.Client.dll
Microsoft.SharePoint.Client.Runtime.dll
Microsoft.SharePoint.Client.WorkflowServices.dll


1) Create a new Subscription (Association) from a Workflow Definition with CSOM:



2) Start a SharePoint 2013 Site Workflow with CSOM:



3) Start a SharePoint 2013 List Workflow with CSOM:


at

26 comments:

  1. UnknownJune 02, 2014 12:09 pm

    Hello,

    Very good post.
    Question.
    Visual studio workflow is deployed as Sandbox solution or workflow in App?
    Can we use same code to associate workflow in SharePoint App web to list in host web?

    Thanks

    ReplyDelete
  2. Vardhaman DeshpandeJune 02, 2014 1:09 pm

    @Anil,

    Thanks!

    1) Visual Studio Workflow is deployed as a Sandbox Solution. But only the declarative Workflow. No Sandbox code.

    2) Right now, this approach does not work for associating App Web Workflows to Host Web. For that, something called the Integrated Workflow Apps is in the pipeline. It should be available in the coming months. Watch this video to know more about Integrated Workflow Apps: http://channel9.msdn.com/Events/SharePoint-Conference/2014/SPC3994

    ReplyDelete
  3. Vardhaman DeshpandeDecember 09, 2014 11:32 pm

    @Anil,

    See this post for Workflow Integrated Apps:
    http://www.vrdmn.com/2014/09/integrated-workflow-apps-deploy.html

    ReplyDelete
  4. KarlJanuary 14, 2015 6:42 am

    Hello

    Thanks for this post very helpful.

    I have followed your other here to deploy a workflow using the integrated app workflow. I deployed this app to the site and can manually associate the workflow to a list. However, I need to be able to do this programmatically so I followed this post to associate the workflow but when I try to get the definitions I get an empty collection



    ReplyDelete
  5. Vardhaman DeshpandeJanuary 15, 2015 11:37 pm

    Hi Karl,

    That is a very interesting scenario you have. I am afraid I have not tested my code for it. I will have a look at it soon and post here if I find anything.

    -Vardhaman

    ReplyDelete
  6. KarlJanuary 20, 2015 9:52 am

    Thanks Vardhaman

    I look forward to hearing back from you.

    Karl

    ReplyDelete
  7. Ruben PillenJune 17, 2015 6:32 pm

    Hello Vardhaman,

    This is exactly what i needed for a piece of development.
    However, when i run the exact code (while pointing to the right list id's) for subscribing a workflow to a list, i get an exception:

    An unhandled exception of type 'System.AccessViolationException' occurred in CSOMWorkflow.exe

    Additional information: Attempted to read or write protected memory. This is often an indication that other memory is corrupt.

    Would you happen to have any idea on how to get around this? Is there some kind of workflow-permissions-setting i need on my tenant?

    Ruben

    ReplyDelete
  8. Ruben PillenJune 17, 2015 6:33 pm

    Hello Vardhaman,

    This is exactly what i needed for a piece of development.
    However, when i run the exact code (while pointing to the right list id's) for subscribing a workflow to a list, i get an exception:

    An unhandled exception of type 'System.AccessViolationException' occurred in CSOMWorkflow.exe

    Additional information: Attempted to read or write protected memory. This is often an indication that other memory is corrupt.

    Would you happen to have any idea on how to get around this? Is there some kind of workflow-permissions-setting i need on my tenant?

    Ruben

    ReplyDelete
  9. yaswanthJuly 03, 2015 3:43 pm

    can you please provide sample code for terminating the 2010 list workflows in 2010 sites using csom

    ReplyDelete
  10. Vardhaman DeshpandeJuly 03, 2015 4:31 pm

    Hi yaswanth,

    Managing Workflows with CSOM is only available in SharePoint 2013 (Standard or Enterprise)

    ReplyDelete
  11. Divyesh LappawalaSeptember 03, 2015 8:25 am

    Good post on SharePoint Workflow. Thanks

    ReplyDelete
  12. Mahesh RondaOctober 28, 2015 5:37 am

    Approach seems great, thanks for the details. But is this is a right approach of passing credentials in CSOM, anyone can get to view the credentials and can tamper with the site?

    ReplyDelete
  13. Vardhaman DeshpandeOctober 28, 2015 7:16 am

    Hi Mahesh

    The goal of this post is to explore the workflow capabilities of CSOM so I have tried to keep it as simple as possible.
    There are other ways of authenticating CSOM such as using an App Only token. You can find many posts on that.

    Thanks!

    ReplyDelete
  14. VansNovember 19, 2015 12:05 pm

    Greate article.
    I would like to know if it is possible now to associate integrated app workflow using CSOM. I am creatin an app with integrated workflow and I would like to associate it to a list programmatically using CSOM.
    Thanks for the help

    ReplyDelete
  15. Vardhaman DeshpandeNovember 19, 2015 12:08 pm

    Hi Vans,

    As far as I know, I don't think that is possible at the moment.

    ReplyDelete
  16. UnknownJune 30, 2016 1:51 pm

    Thank you for the post. i had a working code but that worked for 2010 workflow and had issue with 2013 workflow. The one you have shared helped me. Thanks

    ReplyDelete
  17. UnknownJune 30, 2016 1:52 pm

    Thank you for the post. It helped me with the issues i faced with 2013 workflow. I had working code but that worked for 2012 workflow only.

    ReplyDelete
  18. UnknownJuly 01, 2016 9:06 am

    Hi,
    Thank you for the post. It has helped to associate the 2013 workflow.
    Can you please suggest how do i associate the workflow to a content type using csom.
    i have found some posts to associate 2010 workflow to content type but nothing for 2013 workflow.

    ReplyDelete
  19. DanielAugust 23, 2016 5:48 pm

    Hi Mayur,
    2013 list workflows can only be associated to the list or library but not to a content type. You can check the content type and add some logic dependent on the content type in the workflow.

    ReplyDelete
  20. SarangDecember 02, 2016 10:24 am

    Hi Vardhman,

    This is Sarang Kulkarni from Rapid Circle, actually i am working on the some project in which i ought to save the list workflow xaml file to the client machine through CSOM can you please provide me some help

    ReplyDelete
  21. Vardhaman DeshpandeDecember 02, 2016 12:05 pm

    Sarang Kulkarni 2.0 from Rapid Circle!

    Did you try this property? https://msdn.microsoft.com/en-gb/library/microsoft.sharepoint.client.workflowservices.workflowdefinition.xaml.aspx

    ReplyDelete
  22. SubbuJanuary 27, 2017 3:53 am

    Thanks for this post.

    Can i use only JSOM(strictly no CSOM) here to accomplish this requirement?Also, i want to run this on 14 to 16 lists and almost 20 items in a list.
    Can i achieve this, if yes can you please help me with some code snippets.

    Thanks again.

    Subbu

    ReplyDelete
    Replies
    1. Vardhaman DeshpandeJanuary 27, 2017 9:02 am

      Hi Subbu yes this is also possible using JSOM but I am afraid do not have any code snippets. Check my other post on strarting workflows using JSOM and you should get an idea. Thanks!

      Delete
  23. UnknownJanuary 31, 2017 1:36 am

    hi Vardhman,
    if we have to create a Standard approval workflow for Sharepoint online and have to deploy it as part of a custom list workflow and basically deploy this workflow to multiple site collections how can we do it?
    Basically a custom aproval workflow on a list, and if this has to be deployed to 100+ site collections on SPO how can we do it? As manually deploying the workflow to 100 site collections may not be feasible, any CSOM based approach you are aware of?

    Thanks

    ReplyDelete
  24. Vardhaman DeshpandeJanuary 31, 2017 8:35 pm

    Hi Ketki,

    Yes you can use CSOM/Powershell to deploy a workflow to multiple site collection. Basically, if you have the XAML file of the workflow, you should be able to publish it to a site.

    This particular example is of Powershell but you can use CSOM and .NET code to do the same thing: http://www.piasys.com/blog/how-to-publish-a-workflow-definition-in-sharepoint-using-powershell

    ReplyDelete
  25. NeerajJanuary 15, 2019 2:34 pm

    Hi Vardhaman

    I am trying to programmatically attach the workflow to list and start the workflow on the item.

    I am trying to create API to do that.

    Thanks for your post.

    Instead of having the credentials in the code, Can I have a APP Only Permission. I can registered the app with AAD and grant permission there.

    Is it possible ?

    Can you please direct me to appropriate documentation with APP Only Permission in CSOM.

    Appreciate your help.

    Thanks,
    Neeraj P.

    ReplyDelete

Comments moderation is turned ON. Your comment might not appear immediately after posting.