This article describes how to register a custom Event Bus receiver to take an action when a workflow goes into an error state at runtime. For example, you may want to send an email notification to your IT helpdesk when a workflow encounters an error so that a system administrator can investigate and repair the error.
You can still use the Errors page in K2 Management to manually track and manage errors that occur in workflows. The error event raised to the Event Bus allows you to create some type of automatic action if a workflow goes into error state.
The Event Bus is a feature of K2 Platform Classic that does not have any user interface to manage its functionality. You can only interact with the Event Bus programmatically. The result of this article is that you have a custom Event Bus receiver deployed to your K2 server that handles the new error event (OnProcessError) available from K2 Platform Classic (5.4) and onward (previous versions of K2 Five and K2 blackpearl do not include the OnProcessError event).
Before you begin, understand what is necessary to handle the OnProcessError event. This article requires:
The attached ZIP file contains an example Visual Studio solution to help you get familiar with the Event Bus receiver. The solution contains two C# projects:
The K2.OnProcessErrorEvent project is a command-line tool that you must build and run to register Event Bus functionality with the K2 server. This tool will register the assembly built by the K2.OnProcessErrorEvent.CustomAction project, which is a simple class library that the event uses. In other words, K2.OnProcessErrorEvent.CustomAction contains the code you want the K2 server to execute when a workflow goes into an error state. This specific example writes a message to the K2 server console with the event details and has a placeholder for doing something such as retrying the workflow. You need to use the K2.OnProcessErrorEvent project to register the CustomAction dll with the K2 server.
To use the example, first modify the CustomAction project to do what you need it to. This could be calling a SmartObject method, sending an email, updating a SQL table, or anything that you can do in C# code that you want to do when any workflow error occurs on the K2 server.
One item that you will probably want to change is the location of the custom Event Bus receiver dll. Find this on line 111 of the K2.OnProcessErrorEvent\Program.cs file. Note that you also must modify K2HostServer.exe.config to include this location, described in step 3 below.
Once you are ready, follow these steps:
When the workflow errors, you will see console messages logged and, depending on how you’ve modified the example code, there may be other actions that take place.
Keep in mind that the custom action code executes each time any workflow goes into error state. K2 recommends you do something lightweight in your action code, such as sending an email to a distribution list. However, you can do anything in this code that you want, taking full advantage of K2 APIs to repair and retry commonly known problems based on your experience with workflows. You may want to add some logic to your action handler to prevent infinite loops or race conditions. For example, if you automatically retry a failed workflow, implement some type of counter or throttle so that the handler does not constantly try to repair the same workflow over and over again.
If you need help with modifying the example project, please contact K2 Professional Services.