Handling the On Any Workflow Error Event with the Event Bus

KB003546

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

Notes and prerequisites

Before you begin, understand what is necessary to handle the OnProcessError event. This article requires:

• Familiarity with C# code and the Event Bus API
• Access to Visual Studio or comparable tool to open the example solution
• Access to the server running K2 with administrative privileges
• Deploying your assembly to each K2 server that needs this functionality

The example solution

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. 

Using the example

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

1. Build the solution and copy the CustomAction output dll to the desired location on the K2 server. 
2. Run the K2.OnProcessErrorEvent program to register the custom event.
3. Modify K2HostServer.exe.config to enable your custom receiver. Find the <assemblies> section in this config file and add the location as shown in the following example (adjust the fullname value to suit the location where your compiled custom action dll resides):
   <assembly displayname="EventBusLibrary" fullname="C:BUILDK2.OnProcessErrorEventK2.OnProcessErrorEvent.CustomActioninDebugK2.OnProcessErrorEvent.CustomAction.dll" />
4. If your custom handler writes messages to the K2 server console, stop the K2 Server service and then start the K2 server in console mode so that you can see messages.
5. Start a workflow that you know will go into an error state. The easiest way to do this is to send a task notification or email to a malformed email address (e.g. one that does not include the @ symbol).

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.