This topic refers to legacy products, components or features. Therefore, this topic is offered "as is" and will no longer be updated. This topic does not infer that the product, component or feature is supported, or that the product, component or feature will continue to function as described herein.

Introduction

A 3rd party server (such as SAP or Salesforce) can be added to the Notification Event structure. This allows the execution of events on these 3rd party servers to be recorded and the appropriate notification generated from the Event database.

Note:
  • This document assumes some programming knowledge and familiarity with Visual Studio.
  • With the release of K2 4.6.9 the SourceCode.EventBus.ClientRecorder.dll.config, SourceCode.EventBus.Mapping.dll.config and the SourceCode.EventBus.Server.config have been consildated into the K2HostServer.exe.Config file which is in the \K2 blackpearl\Host Server\Bin folder on the K2 Server. The connection strings previously stored in these files are now retrieved from the K2HostServer.exe.Config file.

Event Bus Architecture and Details

The figure below shows the Event Bus architecture:

[Figure 1. The Notification Event architecture, including a 3rd party server]

To add a 3rd party server, the following steps are required:
  • Develop a Custom Event Recorder with an interface between the server and recorder
  • Develop the Object Browser to surface your objects, events and properties and register it in the web.config file
  • Develop a Resolver to resolve your properties or data fields from the context of your event

Server Recorder

The server will require a Server Recorder and an interface between the server and the recorder. The Server 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 Event.RaiseEvent method.


Object Browser

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



[Figure 2. Object Browser in Workspace displaying the K2 Workflow and SmartObject data]

In order for your custom object browser to display in the Notification Event object browser, add the new server and interface details to the section, located in the Workspace web.config file.
Note: The Workspace web.config file is located at: C:\Program Files\K2 blackpearl\WorkSpace\Site\web.config
 
<eventbusobjectbrowsers>
 <objectbrowser id="61012dd2-ebfd-4dde-8639-340befc0f974"
  displayname="SmartObject Browser"
  assemblytypeprovider="SourceCode.EventBus.ObjectBrowsers.SmartObjectBrowser"
  imageclosed="images/OB/folder_closed.gif"
  imageopen="images/OB/folder-open.gif"
  assemblyfullname="C:\Program Files\K2 blackpearl\Bin\SourceCode.EventBus.ObjectBrowsers.dll”
  connectionstring="BLACKPEARL,5555" />
 <objectbrowser id="bc76ec99-6acd-4e9a-8dd8-db05b6be30ee"
  displayname="Workflow Object Browser”
  assemblytypeprovider="SourceCode.EventBus.ObjectBrowsers.K2ObjectBrowser"
  imageclosed="images/OB/folder_closed.gif"
  imageopen="images/OB/folder-open.gif"
  assemblyfullname="C:\Program Files\K2 blackpearl\Bin\SourceCode.EventBus.ObjectBrowsers.dll”
  connectionstring="BLACKPEARL,5555" />
</eventbusobjectbrowsers> 
Resolver and Data Provider
In order to resolve data from the 3rd party server, you must create a data provider and a data resolver:
  • The data provider is used to generate runtime data. The data provider must implement the SourceCode.Framework.Data.RuntimeDataProviderBase interface.
  • The data resolver is used resolve the data value at runtime. The data resolver must implement the SourceCode.Framework.Data.RuntimeDataResolverBase interface. It can be one of two types: Value Type or XML resolver.
The Resolver interface must be added to the SourceCode.EventBus.mapping.config file under the <resolvers> section as shown below:
<resolvers>
 <resolver id=”4756240D-45B8-4acO-B47F-CO67OBFF28BB"
  assembly="SourceCode.EventBus.Mapping, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d"
  assemblytype="SourceCode.EventBus.Mapping.SOXMLDataResolver"></resolver>
 <resolver id="4756240D-45B8-4acO-B47F-CO67OBFF28CC"
  assembly="SourceCode.EventBus.Mapping, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d”
  assemblytype="SourceCode.EventBus.Mapping.valueTypeDataResolver"></resolver>
 <resolver id="3688D90C-4BEE-4639-9549-A472491BE5F3"
  assembly="SourceCode.EventBus.Mapping, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2cSaaaa1b130d”
  assemblytype="SourceCode.EventBus.Mapping.WorkFlowlItemContextDataResolver”></resolver>
 <resolver id="A6A4C4F4-18OF-4c11-8D9E-D9CE81EFEFC2”
  assembly="[INSTALLDIR]Host Server\Bin\ZourceCode.Workflow.Data.Resolvers.dll"
  assemblytype="SourceCode.Workflow.Data.Resolvers.DataFieldPartResolver"></resolver>
 <resolver id="2EF2EECE-C347-48Da-BAC4-81ADF8872B26”
  assembly="[INsTALLDIR]Host Server\Bin\SourceCode.Workflow.Data.Resolvers.dll"
  assemblytype="SourceCode.Workflow.Data.Resolvers.WorkflowContextFieldPartResolver"></resolver>
 <resolver id="502B68FF-1C66-45F8-9E45-5537A9521FF2"
  assembly="SourceCode.EventBus.FileSystemXmlResolver, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d"
  assemblytype="SourceCode.EventBus.FileSystemXmlResolver.ExpenseClaimResolver"></resolver>
 <resolver id="F07C0651-5ADE-4364-B54A-9FB0AB59ED2D"
  assembly="SourceCode.EventBus.FileSystemXmlResolver, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d"
  assemblytype="SourceCode.EventBus.FileSystemXmlResolver.OrderResolver"></resolver>
</resolvers>
The custom Data Resolver assembly information must be added to the <mapping> section in the SourceCode.EventBus.Server.config file shown below:
<mappings>
      <config>
        <mappings>
          <mapping guid="4756240D-45B8-4ac0-B47F-C0670BFF28BB" assemblyfullname="SourceCode.EventBus.Mapping, Version=4.0.0.0, Culture=neutral, PublicKeyToken=16a2c5aaaa1b130d" assemblytyperesolver="SourceCode.EventBus.Mapping.SOXMLDataResolver" assemblytypeprovider="SourceCode.EventBus.Mapping.SOXMLDataProvider" />
          ...
        </mappings>
      </config>
    </mappings>
Note: The SourceCode.EventBus.Server.config and the SourceCode.EventBus.mapping.config files are located at C:\Program Files\K2 blackpearl\Host Server\Bin
 
 

Working with the Event Bus

 
 When working with the Event Bus, there are several steps to look for to ensure that your environment has been set up properly:
 
  1. Verify that your event is defined
    The Event Bus will check which queuing system to use to raise the events. Out of the box, K2 blackpearl uses Microsoft Message Queuing (MSMQ). In the SourceCode.EventBus.Server.config file, the MSMQ path is defined:
<msmqpath>BLACKPEARL\EventBus</msmqpath>

  • Check that messages are not getting stuck
    A combination of MSMQ configuration, K2 configuration, and Virtual hardware settings can cause messages to get stuck. See the Appendix for Troubleshooting and Prerequisites.

  • Check for errors
    The Event Bus server has a queue listener that will pick up messages from the queue and handle them. If something goes wrong and it can't handle the message, the Event Bus will dump it on the error queue, which is also defined in the SourceCode.EventBus.Server.config file:
<msmqpath>BLACKPEARL\EventBus</msmqpath>

  • Check the Custom Event table
    Once the Event Bus Server picks up the message, it will log the message in the LogCustomEventInstance table in the EventBus database. Check this table to ensure that your message made it to the Event Bus.

  • Check the Client Recorder Error table for resolving data errors
    Outside of the Event Bus Server itself, errors that occur with the resolving of data are logged to the ClientRecorderError table in the EventBus database. Check this table to see if there were any errors in resolving the data.
     
Note: Check the Host Server log file for errors. This is located at C:\Program File\K2 blackpearl\Host Server\Bin

Appendix

Troubleshooting the Event Bus

If you are encountering issues with the Event Bus not raising notifications, check the following items:

  1. Is Microsoft Message Queuing installed?
    Microsoft Message Queuing is a pre-requisite for the Event Bus. Refer to the Event Bus Prerequisite Checks section for how to check this component.
  2. Are you working in a Virtual Environment?
    Make sure that the hardware virtualization is enabled for your VPC. Sometimes events may not be raised without this option enabled.

Event Bus Prerequisite Checks

The K2 Event Bus makes use of a Microsoft Windows 2003 Component called Microsoft Message Queuing. It is installed as part of the operating system. Depending on the operating system configuration, this component may not have been included; verify that this component is installed.
 
1.       Click on Start > Control Panel > Add or Remove Programs
 
2.       From the Add / Remove Programs dialog, select Add\Remove Windows Components
 
3.       Scroll down and locate Application Server, click on the item to select it.
 
4.       Click on the Details button for Application Server. The Message Queuing feature must be enabled.
 
[Figure 6. The Message Queuing component in the Windows Components dialog]

5.       Click on the Details button for Message Queuing. The default components that are enabled are sufficient for K2.
 
 
[Figure 7. The Message Queuing subcomponents]