We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

How to add a 3rd-party event recorder to the K2 Server

This content applies to legacy components (such as K2 Studio and K2 for Visual Studio), legacy assemblies, legacy services or legacy functionality. If you have upgraded from K2 blackpearl 4.7 to K2 Five, these items may still be available in your environment. These legacy items may not be available in new installations of K2 Five. These legacy items may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

The Event Bus is an extendible piece of the K2 platform that allows third-party events to be raised on a K2 server.

If you want to consume events raised in the K2 environment so that you can perform an action based on an event (for example, write to a text file if a SmartObject is executed), you will need to create a custom Notification Provider as described in the Custom Notification Providers topic.
The difference is that a Notification Provider responds to events and performs an action, while an Event Bus Server raises custom events which a notification provider can then respond to.

The Event Bus Architecture

The following diagram illustrates the architecture of the Event Bus and shows how 3rd-Party event recorders function in the context of built-in K2 event recorders. All events are funneled into the Generic Client Recorder and queued (using MSMQ or another queuing system) to be processed by the Event Bus.

Components and Interfaces

There are three main components that need to be developed in order to surface events from a 3rd-party server to the Event Bus and to use those events in custom notifications.

A Custom Event Recorder with an interface between the 3rd-party server and the recorder.
A Resolver to resolve properties or data fields from the context of the 3rd-party event.
The Object Browser to surface objects, events and properties in the Notification Event Designer in K2 Workspace.

Custom Event Recorder

Implements: IEventRecorder

Sample code

ClientRecorderEvent newEvent = new ClientRecorderEvent();
newEvent.RaiseEvent((object) context, ProviderID, eventName, eventData);

The Custom Event Recorder provides an interface between the server and the custom recorder. The recorder and interface components are developed separately as custom components. The recorder needs to implement the 3rd-party system interfaces to ensure that the events from that system can be consumed. The recorder also needs to reference the SourceCode.Eventbus.ClientRecorder assembly in order to raise the event via the RaiseEvent method.

Resolver

Inherits: RuntimeDataResolverBase

The Resolver allows data fields, along with their types and values, to be passed from the custom recorder through to the K2 server. These values can then be used in the custom notification designer as illustrated in the sample below.

Object Browser

Implements: IObjectBrowser

To display the server’s data structure in the K2 Notification Event object browser as shown below, another component needs to be developed. This component will display the objects, events and properties of the 3rd-party server, and needs to implement the IObjectBrowser interface, which is in the SourceCode.Eventbus.Interfaces assembly.

Example

In the solution provided here, a custom recorder is used to capture events from a watched folder on the local server. By default, only new files that have a particular filename cause the recorder to process the event.

The solution is made up of three projects:

SourceCode.EventBus.Samples.FileSystemEventRecorder: Provides the event recorder for capturing file system events and passing them along to the Event Bus.
SourceCode.EventBus.Samples.FileSystemObjectBrowser: Provides the object browser for browsing the event types provided by the event recorder.
SourceCode.EventBus.Samples.FileSystemXmlResolver: Provides the logic to expose XML data fields from files created in the watched folder which can then be used in the notification designer.

The resulting assemblies created when the project is compiled do not ship with K2. These are assemblies that are to be used as samples when creating your own event recorder.

Steps

Download, extract and open the sample project: K2Documentation.Samples.Extensions.Eventbus.FileSystem.zip
The sample project is provided for demonstration purposes only. It is not supported by K2 product support and is not intended to be used as-is in production environments.
This example assumes Visual Studio is installed on the same machine as the K2 Server.
Update the references in the SourceCode.EventBus.Samples.FileSystemEventRecorder and the SourceCode.EventBus.Samples.FileSystemObjectBrowser projects by browsing to "%PROGRAMFILES%\K2\Host Server\Bin" to locate these assemblies.
Build the solution
Copy assemblies from their to the correct places as noted below. Remember to also copy the SourceCode.EventBus.Samples.FileSystemEventRecorder.dll.config file to the same location as its associated assembly.
- For SourceCode.EventBus.Samples.FileSystemEventRecorder
  Copy To: "%PROGRAMFILES%\K2\Bin"
- For SourceCode.EventBus.Samples.FileSystemObjectBrowser
  Copy To: "%PROGRAMFILES%\K2\Bin"
- For SourceCode.EventBus.Samples.FileSystemXmlResolver
  Copy To: "%PROGRAMFILES%\K2\Bin"
Make the necessary changes to the SourceCode.Eventbus.Mapping.dll.config file, the SourceCode.Eventbus.Server.config and the Workspace Web.config as noted below. These steps are similar to the steps included in the KB article KB000185 - How to add a 3rd party server to the Event Bus (requires portal login).
In K2 version 4.6.9, a number of configuration files were consolidated into a single configuration file to simplify the management of configuration settings. The SourceCode.EventBus.Assemblies.config file has been consolidated into the K2HostServer.exe.Config file, which is located in the "%PROGRAMFILES%\K2\HostServer\Bin" folder on the K2 Server. The connection strings previously stored in this file are now retrieved from the K2HostServer.exe.Config file.


<resolver id="502B68FF-1C66-45F8-9E45-5537A9521FF2" assembly ="SourceCode.EventBus.Samples.FileSystemXmlResolver, Version=1.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d" assemblytype="SourceCode.EventBus.Samples.FileSystemXmlResolver.ExpenseClaimResolver" />
<resolver id="F07C0651-5ADE-4364-B54A-9FB0AB59ED2D" assembly ="SourceCode.EventBus.Samples.FileSystemXmlResolver, Version=1.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d" assemblytype ="SourceCode.EventBus.Samples.FileSystemXmlResolver.OrderResolver" />


<mappingguid="502B68FF-1C66-45F8-9E45-5537A9521FF2"assemblyfullname="SourceCode.EventBus.Samples.FileSystemXmlResolver, Version=1.0.0.0, Culture=neutral,PublicKeyToken=16a2c5aaaa1b130d" asssemblytyperesolver ="SourceCode.EventBus.Samples.FileSystemXmlResolver.ExpenseClaimResolver" assemblytypeprovider="SourceCode.EventBus.Samples.FileSystemXmlResolver.ExpenseClaimProvider"/>
<mappingguid="F07C0651-5ADE-4364-B54A-9FB0AB59ED2D"assemblyfullname="SourceCode.EventBus.Samples.FileSystemXmlResolver, Version=1.0.0.0, Culture=neutral,PublicKeyToken=16a2c5aaaa1b130d" assemblytyperesolver ="SourceCode.EventBus.Samples.FileSystemXmlResolver.OrderResolver" assemblytypeprovider ="SourceCode.EventBus.Samples.FileSystemXmlResolver.OrderProvider"/>


<eventrecorders>
<recordername="FileSystemEventRecorder"assembly="SourceCode.EventBus.Samples.FileSystemEventRecorder" type ="SourceCode.EventBus.Samples.FileSystemEventRecorder.Recorder"/>
</eventrecorders>


<objectbrowserid="09C19823-5A81-4AC0-BD1A-BFE1243BB6B5"displayname="File System Object Browser"assemblyfullname="C:\Program Files\K2\Bin\SourceCode.EventBus.Samples.FileSystemObjectBrowser.dll" assemblytypeprovider="SourceCode.EventBus.Samples.FileSystemObjectBrowser.ObjectBrowser" imageclosed="images/OB/folder_closed.gif" imageopen ="images/OB/folder_open.gif" connectionstring ="C:\Program Files\K2\Host Server\Bin\SourceCode.EventBus.Samples.FileSystemEventRecorder.dll.config"/>

When copying code from these examples please make sure that the full XML node is located on the same line. Carriage returns may be inserted by html rendering and will need to be removed.

After the changes have been made to the .config files, either restart the K2 Server service or console application. Note: The target folder (in the case of the example, C:\FSW\) must exist before the K2 Server is started. If not, create the target folder and then restart the K2 Server.

Verifying the New Recorder

When the new event recorder is deployed to the server and the necessary .config file changes are made, run the K2 Server in console mode from the Start menu to verify it is working. When the example project is built and deployed, the server window will display the following entries when it is finished loading:

If you do not see this message, it could mean that the information messages are not displayed in the console window. To check, browse to C:\Program Files\K2\Host Server\Bin and open the HostServerLogging.config file. In the <ApplicationLevelLogSetting> section of the <ApplicationLevelSettings> section, modify the FileExension LogLocation Active Setting to be True, and the LogLevel Setting to All, as in the following line:

<LogLocationName="FileExtension"Active="True" LogLevel ="All"/>

Save the changes to this file and restart the K2 Server from the Start menu.

Then, once you see the message in the server console that the event recorder is loaded, copy the ORD123.txt example file to the C:\FSW\ folder. This will fire an event that will register in the server console.

To further test the example event recorder, browse to K2 Workspace and create a new notification using the data fields from the File System Object Browser. You can test multiple events by creating copies of the example file and changing some of the fields inside the file. The fields can be dragged over to the notification event designer in order to send customized e-mail notifications based on the XML content of the file dropped into the C:\FSW\ folder.