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:


26 comments:

Unknown said...

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

Vardhaman Deshpande said...

@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

Vardhaman Deshpande said...

@Anil,

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

Karl said...

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



Vardhaman Deshpande said...

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

Karl said...

Thanks Vardhaman

I look forward to hearing back from you.

Karl

Ruben Pillen said...

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

Ruben Pillen said...

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

yaswanth said...

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

Vardhaman Deshpande said...

Hi yaswanth,

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

Divyesh Lappawala said...

Good post on SharePoint Workflow. Thanks

Mahesh Ronda said...

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?

Vardhaman Deshpande said...

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!

Vans said...

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

Vardhaman Deshpande said...

Hi Vans,

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

Unknown said...

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

Unknown said...

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.

Unknown said...

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.

Daniel said...

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.

Sarang said...

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

Vardhaman Deshpande said...

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

Subbu said...

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

Vardhaman Deshpande said...

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!

Unknown said...

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

Vardhaman Deshpande said...

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

Neeraj said...

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.