Custom Notification Providers

K2 provides two standard notification providers:

• E-mail Notification Provider that can send SMTP email messages when an event is raised
• K2 Process initiation provider that can start K2 workflows in response to some event

In certain scenarios, it may be necessary to create custom notification providers that will execute some code in response to an event in a SmartObject, Workflow, or when an event is raised by a custom Event Bus Server. The most common reasons why custom notification providers are implemented include:

• Auditing requirements that will write audit entries whenever events are raised on the K2 platform
• To allow the K2 platform to participate in an Enterprise Message Bus architecture, by raising messages to the Bus in response to events on the K2 platform
• A scheduled task implementation, where the K2 scheduling capability will be used to execute a particular event at some predefined interval

You can use Notification Events > Custom Event Designer in K2 workspace to register events for your custom notification provider. The user interface uses Reflection to determine which actions are available in your Notification Provider and what the input properties for the actions are. You can then drag and drop contextual information from the event into your notification provider action.

Implementing a custom notification provider requires knowledge of the K2 platform’s Event Bus technology, the K2 platform, and the systems and technologies to which the custom notification provider will send notifications of events.

You must clearly understand that building a custom notification provider is typically an integration project, and as such, there may be considerations about network communication, authentication and authorization when the custom notification provider needs to interact with an external system or API.

You must take care that the code in a custom notification provider is optimized and stable, since the code will execute on the K2 server. Code that performs poorly or is unstable will affect the performance and stability of the K2 environment, so sufficient testing and code review of any custom notification provider is recommended before the assembly is published in production environments.

Implementation

You implement a custom notification provider by creating a standard .NET assembly and defining one or more public static methods. Each public static method represents a notification provider. It is not necessary to reference any SourceCode assemblies or namespaces, or implement specific interfaces.

A custom notification provider must perform the following operations:

• Gather data related to an event that is raised within the K2 platform
• Send notification of events to an underlying system or technology

Deployment and Registration

In order for the K2 platform to make use of a notification provider, it must be deployed to and registered with the platform. Notification providers are deployed by copying the notification provider assembly to the Host Server\Bin folder in the K2 blackpearl Server’s installation folder. Notification providers are registered by adding a key to the SourceCode.EventBus.Assemblies.config configuration file that specifies that path to the assembly and a display name for the notification provider.

Deploying and registering a custom Notification Provider is a 2-step process.

Step 1: Deploy the dll to the K2 application servers

This step should be performed every time you make an update to the custom notification provider .dll

1. Stop the K2 service.
2. Copy the notification provider .dll file to the K2 host server's Bin directory. By default, this directory is located at [Program Files]\K2 blackpearl\Host Server\Bin (you could copy the assembly to a different directory: the important part is to set the path to the assembly correctly when you edit the configuration file in Step 2. We recommend that you put the assembly in the Bin folder to keep things consistent.)
3. Copy any dependencies that are not already on the K2 server to the host server Bin directory, or install the dependencies in the GAC.
4. Start the K2 service.

Step 2: Register the notification provider with the K2 application servers

This step only needs to be done once on each K2 application server.

1. Stop the K2 Service.
2. Add your assembly to the <assemblies> section of the K2HostServer.exe.config configuration file. You need to provide the Display Name and full path to the assembly:
   
   <!--
   Make a backup of the K2HostServer.exe.config file. This file is by default located in [Program Files]\K2 blackpearl\Host Server\Bin on the K2 application server.
   Add your assembly to the <assemblies> section of the K2HostServer.exe.config file. You need to provide the Display Name and full path to the assembly:
   -->
   <assemblies>
     <assembly displayname="[DisplayName]" fullname="[Full path to the assembly]" />
   </assemblies>
   
3. Start the K2 service.

Debugging

You can debug custom notification providers through remote debugging and attaching to the K2 server process. If you are debugging a remote K2 server, you will need to enable remote debugging. See http://msdn.microsoft.com/en-us/library/vstudio/y7f5zaaa.aspx for more information. If you are running a multi-K2 server environment (for example, when using NLB) we recommend that you shut down all but once of the K2 servers so that only one K2 server will handle the notification provider event.

1. Add breakpoints to your code
2. Copy the assembly and .pdb file to the K2 host server as described in the Deploying and Registration section
3. Start the K2 service and then use Visual Studio's Debug > Attach to process option to attach to the K2HostServer.exe process. You may need to check the options Show Processes from all users and Show Processes in all sessions before the K2HostServer.exe process will show up.
4. Use K2 workspace to create an event which uses your custom Notification provider.
5. Raise the event by executing the SmartObject, starting the workflow or performing whatever event you used in step d)
6. K2 Studio should launch and you can step through and debug your code.