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.
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.