8-Week Microsoft Teams AppDev Accelerator Program
Limited seats available! - Start date: Wednesday, April 16, 2025
Join Today & Save $1,000
articles

Publishing Custom Events to SharePoint 2013 Workflows

Publishing Custom Events to SharePoint 2013 Workflows
by Andrew Connell

Last updated July 7, 2014
3 minutes read

Share this

Focus Mode

  • Using Custom Events to Manipulate the Workflow
  • Using Custom Events for Long Running External Processes
  • Feedback & questions

With the new workflow engine in SharePoint 2013 / Office 365, Microsoft introduced some extensions to the client side object model (CSOM) that allow you to interact with the workflow system from off the SharePoint server. One of the capabilities they introduced is the ability to publish a custom event into a running workflow instance. This is done using the WorkflowInstanceService.PublishCustomEvent method which is documented here in MSDN. Using this method you can name a specific event you create and include a payload message with the publication. Then within your workflow you can listen for this using the activity WaitForCustomEvent, documented here in MSDN.

Learn More!

If you want to learn more about this, check out my SharePoint 2013 workflow course on Pluralsight, specifically module 3, where I talk about the new CSOM improvements.

So you are now wondering “why would I use this?”

Using Custom Events to Manipulate the Workflow

One reason would would use this is to force some action within your workflow from an external source. I showed how you can use this technique to manually force the workflow to move from one state to another. In that scenario, you have a list that contains a fleet of vehicles for a company. The workflow starts automatically and enters the “in service” state. There’s a trigger that kicks in after 3 months (ok, 30 seconds for the demo) that takes the vehicle to the “out of service” state for scheduled maintenance. However I wanted to give people a way to force this trigger so I created a custom form that will publish the custom event which the workflow listens for when there is unscheduled maintenance. Neat huh?

Using Custom Events for Long Running External Processes

This is also going to come in very handy when you have a long running process. Another thing that SharePoint 2013’s workflow engine introduced is the ability to call external web services, technically provided by Workflow Manager. This works great, unless the web service is a long running process. Workflow Manager won’t leave the web service request open waiting for a response indefinitely… it will timeout after 60 seconds or so. In that case your workflow will throw an error.

So how you handle this? Instead, what you could do is have the workflow call a web service that starts a process, but the web service immediately responds before the process is complete saying “I got the request and I’m working on it… I’ll let you know when I’m done.” Your workflow can then either continue, or stop, using the WaitForCustomEvent activity. Then the external process, when complete, can call back into your workflow instance using the custom event to let it know that the process completed, potentially sending in any extra information that is needed.

Andrew Connell, Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.
author
Andrew Connell

Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.

Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 20+ year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.

Feedback & Questions

newsletter

Join 10,000+ developers for news & insights

No clickbait · 100% free · Unsubscribe anytime.

Subscribe to Andrew's newsletter for insights & stay on top of the latest news in the Microsoft 365 Space!
blurry dot in brand primary color
found this article helpful?

You'll love these!

Resolving SharePoint 2013 workflow development issue

Resolving SharePoint 2013 workflow development issue

June 21, 2014

Read now

Fixing HTTP 400 Bad Request Errors in SharePoint REST API

Fixing HTTP 400 Bad Request Errors in SharePoint REST API

June 30, 2014

Read now

Fixing HTTP 400 Bad Request Errors in SharePoint REST API

Fixing HTTP 400 Bad Request Errors in SharePoint REST API

June 30, 2014

Read now

bi-weekly newsletter

Join 10,000+ Microsoft 365 full-stack web developers for news, insights & resources. 100% free.

Subscribe to Andrew's newsletter for insights & stay on top of the latest news in the Microsoft 365 ecosystem!

No clickbait · 100% free · Unsubscribe anytime.

Subscribe to Andrew's newsletter for insights & stay on top of the latest news in the Microsoft 365 Space!