Event-Driven Business Process Management (EDBPM) combines Business Process Management (BPM) with Complex Event Processing (CEP) to bring greater business flexibility, agility, and real-time information to distributed systems.^[21] The Event Bus is a key piece of the K2 platform that enables the integration of CEP with BPM. Event-driven scenarios made possible by the Event Bus allow process-driven applications to react to events from line-of-business (LOB) systems and other sources relevant to the business, increasing process flexibility and business agility in response to a changing business environment.

The Event Bus provides rich features for business users and developers alike. The following sections provide a quick overview of the key features of the Event Bus.

Built-In Event Handlers

The Event Bus is preconfigured with event handlers for K2 Workflow and K2 SmartObjects. The events for the K2 SmartObjects on the K2 server, as well as K2 Workflow events, are made available for users to subscribe to. All the events are available throughout the K2 blackpearl platform, such as reports and forms via the ADO.NET provider and the Notification Events wizards, as shown in Figure 21-1. For more information on how data and events are exposed for K2 Workflow processes, see the "Exposing Process Information through SmartObjects" section in this chapter.

Figure 21.1. Figure 21-1

The Event Bus component of the K2 platform consists of three hosted servers — the Event Bus Management Server, the Event Bus server, and the Event Bus Scheduler, which are shown in Figure 21-2. The flow of data is shown in the Figure 21-7, but it is important to note here that the Event Bus Scheduler utilizes the SourceCode.EventBus.ClientRecorder assembly to schedule events on single or recurring schedules, such as the Last Friday of every Month (see The Event Bus Scheduler section later in this chapter for more details). The scheduler events, along with the recorders for workflow, SmartObjects, and custom events, are processed using Microsoft Messaging Queuing (MSMQ) to either send notifications or call static methods in custom assemblies.

Figure 21.2. Figure 21-2

Event Bus Data Flow

The Event Bus has been architected from the ground up with generic components and interfaces throughout the entire platform. All built-in and custom events that are registered with the Event Bus are done so through the Generic Client Event Recorder. This ensures that the tooling provided for managing events and notifications is consistent regardless of the source of the event. To ensure reliable processing of all events without locking or contention issues, the architecture implements the use of a message queue to allow events to be raised independent of their processing. The Generic Client Event Recorder will raise all events that have been registered with the context data that was configured for that event. This happens independent of any processing of the event. The event action and the context data is simply put on the message queue for processing by the Event Bus server.

Figure 21-3 shows how data flows from workflow, SmartObject, and custom Event Recorders through to the message queue (MSMQ) to then be processed by the Event Bus. The processing of events will likely involve a notification or execution of a policy/action or SmartObject method. Typically, these events are configured to send notifications or execute custom code via K2 Workspace, but they can also be programmatically configured.

Since there is no current tooling in K2 blackpearl, schedules can only be programmatically configured.

Figure 21.3. Figure 21-3

The policy aspect of the Event Bus shown in Figure 21-3 is provided by the SmartFunction hosted server. Currently, this server is used only by the Event Bus. It cannot be extended, and it will be superseded by a different policy engine in the future.

The sample code listed later in this chapter will walk through the various pieces of configuration.

Event Bus Server

The Event Bus Server (see Figure 21-4) is composed of multiple components and makes up the heart of the event features of the K2 platform. Each component is described in this section.

Figure 21.4. Figure 21-4

Event Recorder

The Event Recorder is responsible for actually registering the events that the Event Bus will be listening for. There are several events available through workflow and SmartObject events as well as custom events that implement the Generic Client Recorder interfaces. The registered events will be sent to the configured queue by the Event Recorder.

Event Bus Engine

The Event Bus Engine is the execution engine for the entire event management system. It receives events from the queue, evaluates policies and executes the registered actions. In the case of any exceptions, the Event Bus Engine is also responsible for logging the exceptions.

Event Bus Store

The Event Bus utilizes ADO.NET 2.0 for much of the interaction between the Event Bus server and the Event Bus Store. The Event Bus Store holds the details for all registered events (Workflow, SmartObjects, and Custom) as well as the policies (Conditional and Action). The Event Bus store consists of two main databases: Event Bus and Event Bus Scheduler. Please see the Developer Reference for more information on the databases, tables, and stored procedures that make up the Event Bus Store.

Event Recorder

As Figure 21-5 shows, the Event Recorder serves as the gateway between the Event Bus and source system for the actual events that are being managed. Although the source system is actually where the events happen, it is through the Event Recorder that the events become part of the Event Bus.

Figure 21.5. Figure 21-5

System Event Recorder

The events of the source system are exposed to the Event Bus through a custom Event Recorder. All Event Recorders, including the built-in workflow and SmartObject Event Recorders, implement the interfaces of the Generic Client Event Recorder. The system-specific Event Recorders contain the logic for subscribing to events from source system through Event Bus event handlers. These event handlers utilize the Generic Client Event Recorder to raise the events to the Event Bus.

Generic Client Event Recorder

The Generic Client Event Recorder will retrieve context data belonging to the executing event and provide the ability to store that data. The context data from the events is serialized and deserialized throughout the processing of the event. When the source system raises the event, it will be responsible for storing any context data necessary for processing of the event. This context data is usually configured as part of registering a source system event. To ensure consistent processing of all Event Bus events, the context data is serialized through interfaces in the Generic Client Event Recorder. When the Event Bus processes the source system event, it will utilize these same interfaces to deserialize the context data. The Generic Client Event Recorder is also responsible for the actual queuing of the source system event.

Event Bus Engine

The Event Bus Engine (see Figure 21-6) provides the gateway between the message queue system, the policy engine, and the user interfaces for configuring the Event Bus.

Figure 21.6. Figure 21-6

Event Queue

The Event Queue is where all the source system events and their context data are stored. The Event Bus engine utilizes the Event Queue to process events independently of the actual event firing. This allows the source systems to reliably raise all events without waiting for the Event Bus to process those events. The Event Queue will store all the events, and their context data, until it has the cycles to process those events. Ideally, this is within milliseconds of the original event, but under load it may take longer.

The important thing to note is that all events will be processed and the source system will not be affected by this processing.

Event Store

The Event Store consists of two main databases:

• EventBus: Stores information about the Event Bus and configured notifications.

• EventBusScheduler: Stores information about the Event Bus Scheduler, which provides a mechanism to raise events to the Event Bus using single or recurring schedules.

These databases store the list of events that are to be managed by the Event Bus as well as the mappings of their context data. It is important to note that nothing specific to the actual event is stored in the Event Bus store. The specific events and the context data for that event are stored on the Event Queue for processing. Once processed, that event and context data is disposed and no longer accessible.

Policy Engine

When the Event Bus engine processes events from the queue it will likely execute policies in the form of .NET methods and utilize the context data from the source system. The policies are stored and executed via the SmartFunction hosted server. Failed policy executions are logged and retried. The retry count is configurable and, if exceeded, the Event Bus Engine will log an exception.

At the time of this writing, the policy engine that currently ships with K2 blackpearl does not support policies other than action policies. Conditional policies are dependent upon future releases.

Some common failures to watch for include unexpected or missing context data fields and lost connections. Remember that the source system will raise an event and must put the event and the context data on the queue. It is later that the Event Bus engine will process that event with the context data through the execution of policies. Managing for this disconnected processing is key to building custom events.

Event Administration

The Event Bus engine can be fully managed in code via the APIs. The Event Bus architecture was built from the ground up to ensure flexibility and extensibility. The transparency of the administrative features is a great example of this. The Event Bus currently has business user tooling for creating e-mail notifications for any event managed by the Event Bus. Additionally, there is tooling for executing custom policies in the form of static .NET methods for registered events. This business user tooling is just scratching the surface of the Event Bus administration APIs, and more business user tooling will be available in the future, including registration for schedule-based events.

Business processes in organizations typically have two main elements of information that are part of the design-time and run-time process information — the process instance data (what actions were taken for an instance of the process) and the data that is associated with the process instance.

Every business process that is designed in an organization will have certain actions that can be performed on it. These actions are determined when the process is designed. Some of the actions are standard actions, such as Start Process. Others are more specific to the type of process such as Begin Order Approval. A process also generates and contains data during execution. This data is also defined during design time and can be set, but only after an instance of the process is created. So when a user performs an action, such as Start Process for instance, you can first set some data on the instance. This concept of setting data and performing actions is similar to setting properties and executing methods on SmartObjects. This means that exposing processes and data as SmartObjects fits nicely into the SmartObject model. For more information about SmartObjects, see Chapter 7.

Let's walk through the following scenario.

An organization builds an Order Approval process that presents an approver with a form to review the order and determine if it should be Approved or Declined. An e-mail indicating the results is then sent to the Originator of the process.

Most processes consist of a number of activities and events. Some events may require input from a user and are called client events. Other events can be executed without any user interface (UI) and are called server events. The example process has three activities: Order Approval, Order Approved, and Order Declined.

The Order Approval activity has one client event called Approve Order. The Order Approved activity has a server event called Send Approved Email. The Order Declined activity has a server event called Send Declined Email. The full process is shown in Figure 21-7.

Figure 21.7. Figure 21-7

As with processes, client events can also have actions. In this case the Approve Order client event has actions Approved and Declined. Also like with processes, activities can also have data that are only in the scope for that activity. In the example there is only an Order ID that is defined as data on the process level.

When a process is deployed, SmartObjects are optionally created for the process itself and for each client event in the process. These are the only entities of a process that can have actions performed on them. So in the example there will be a SmartObject created for the Order Approval Process and for the Approve Order client event.

As for the data, because Order ID is defined at the process level, Order ID becomes a property on all entities (process and client events). If Order ID were only defined for the Order Approval activity, it would have been a property of the Approve Order client event SmartObject and not on the Order Approval Process SmartObject (see Figure 21-8).

Figure 21.8. Figure 21-8

Now that you understand where the data for a process sits, let's look at how it flows (see Figure 21-9).

Figure 21.9. Figure 21-9

When the process is deployed, you have a choice to generate the SmartObjects during the deploy task of the process. If you choose not to generate the SmartObjects and later need them, you can always do so manually afterwards. This option is configured on the process properties dialog.

You have the option to choose which objects are created (see Figure 21-10). By default, if you check only Create Workflow SmartObjects and don't specify any other options, this will create only the Process SmartObject and no client SmartObjects. You specifically have to check those you want enabled. Having some of these turned off by default enhances performance and will not put extra load on the server for objects that are never used. Figure 21-10 shows two checkboxes that affect the SmartObjects generated for the process. The same is true concerning the reporting SmartObjects created with Create Workflow Reporting SmartObjects; the only difference is that by default it is checked to be created and you can specify activity objects as well (see the product documentation for more details).

Figure 21.10. Figure 21-10

So how does this apply to the K2 Event Bus?

The ability to represent all business process information — activity instance data, process instance data, data associated with the process that can be both internal and external in a LOB system as business entities — is unique to K2. Once the traditional workflow information is exposed as a SmartObject, all the power of the SmartObject system K2 offers is now available, from dynamic forms and application building to reporting, including intelligent access to all the process information and their related entities without needing to write code or SQL syntax queries to create the relationships, custom applications, other process designs, and the Event Bus to name a few.

The Event Bus Scheduler is used to schedule time-based events. These could be events that occur on a particular day and time or that recur on a regular basis. Scheduled events are not raised by another system but are created and executed entirely within the Event Bus. LOB systems that raise recurring events can and should probably be used for recurring events that need some interaction with the Event Bus, but if you don't have a system for these events and you would like to give your business users access to a scheduling engine, use the Event Bus Scheduler. Keep in mind that the scheduler will not execute custom code nor will it execute policies for use by the Event Bus.

Events are raised in the same way as in the Event Bus by the use of Event Recorders, and there are two ways of consuming your events as set up by your business users:

The authoring of a schedule uses standard scheduling patterns. The patterns supported by the Event Bus Scheduler are:

These occurrence patterns can be used together with an occurrence range to specify the parameters of your schedule. The occurrence range can be specified in one of the following two methods:

By using the predeveloped Event Bus Scheduler Event Recorder, you can create a schedule and link it to an Event Bus policy to be executed. Using the Scheduling API, you can create a schedule with the following code sample:

private void SpecificDateSchedule (object sender, EventArgs e)
    {
      SchedClient.ScheduleAuthoring scheduleClient;
      SchedAuth.Schedule schedule;
      int scheduleID = 0;

      try

    {
        //***** SPECIFIC DATE *****
        schedule = new SchedAuth.Schedule((int)SchedAuth.RecurrenceType.Yearly);
        //Setup Schedule
        schedule.Name = "Specific Date Schedule1";
        schedule.Description = "This schedule executes on 18th of January yearly at
15:39";
        //Setup Range
        schedule.RecurrenceRange.Occurrences = 1; //Could also use the
RecurrenceRange.StartDate and EndDate to specify a range
        //Setup Pattern
        schedule.RecurrencePatternYearly.DayX = 18;
        schedule.RecurrencePatternYearly.EveryXMonth = 01;
        schedule.RecurrencePatternYearly.StartTime = new SchedAuth.Time(15, 39);

        //Open Connection and save schedule
        scheduleClient = new SchedClient.ScheduleAuthoring();
        scheduleClient.CreateConnection();
        scheduleClient.Connection.Open(GetConnectionString());
        scheduleID = scheduleClient.UpdateSchedule(schedule);
        AddSolutionPolicy(scheduleID); //This is where the schedule is linked to the
executing policy
        MessageBox.Show("Done");
      }
      catch (Exception ex)
      {
        MessageBox.Show(ex.ToString());
      }
      finally
      {
        schedule = null;
        scheduleClient = null;
      }
    }

To link the schedule created above to an Event Bus policy, the AddSolutionPolicy function would be similar to creating Event Bus events, but you would specify a different Event Type, as in the following example:

private void AddSolutionPolicy(int scheduleID)
    {
      EBClient.EventAuthoring eventClient;
      EBAuthor.CustomEvent customEvent;
      EBAuthor.PolicyMapping policyMapping;
      EBAuthor.SourceField sourceField;
      try
    {
        //***** Add the Event to Execute for the schedule *****
        //Create Event
        customEvent = new EBAuthor.CustomEvent(
          0,
          "Test Schedule Event",

"Description",
          scheduleID.ToString(),
          "OnScheduleExecute",
          (int)SourceCode.EventBus.Common.Enumerators.EventType.Scheduled_Event);
        //Add the action policy
        policyMapping = new EBAuthor.PolicyMapping(0, "C:\Windows\SolutionEvent.dll", "SolutionEvent.Job", "Void TestJob()");

        customEvent.ActionPolicyMappings.Add(policyMapping);
        //Save the custom event
        eventClient = new EBClient.EventAuthoring();
        eventClient.CreateConnection();
        eventClient.Connection.Open(GetConnectionString());
        eventClient.UpdateCustomEvent(customEvent);
      }
      catch (Exception ex)
      {
        MessageBox.Show(ex.ToString());
      }
      finally
      {
        sourceField = null;
        policyMapping = null;
        customEvent = null;
        eventClient = null;
      }
    }

An example scenario for creating a monthly schedule is to automatically generate a department's sales report and mail the report to all the relevant sales representatives. You could also automatically create a sales discussion meeting if the sales figures are below 10% of the budgeted estimates.

There are several configuration (.config) files that are useful in understanding settings that control how the Event Bus functions:

This section includes descriptions and important settings for each configuration file.

The following is a list of things to keep in mind when working with the Event Bus.

Let's walk through a sample of creating a new custom event based on the arrival of mail in a SMTP folder. The scenario in this example involves a process in which:

We must build several components to surface and process the event of receiving an e-mail with the Event Bus. Figure 21-11 shows how these components fit in the overall solution.

Figure 21.11. Figure 21-11

The provided solution contains three projects related to the registration, configuration, and processing of an e-mail received event and the associated context data from the e-mail. The solution also contains two projects for custom action that will be taken once the e-mail is received, namely the execution of a workflow process.

The five projects are:

The following steps will help you get the SMTP Event Bus Sample running on your system.

Once the previous steps are completed, you should execute an IISRESET and restart the K2 blackpearl server in console mode. You will see the SMTP Event Recorder load (see Figure 21-13).

Figure 21.13. Figure 21-13

The final steps in this sample involve configuring the new SMTP event to start the workflow process.

The configured custom event will now appear in the list (see Figure 21-21).

Figure 21.21. Figure 21-21

The sample is now fully configured. You can verify that everything is working by sending an e-mail with "xbox" in the subject to the SearchSharePoint e-mail address (see Figure 21-22).

Figure 21.22. Figure 21-22

This will cause an event to be raised to the Event Bus and the SearchResults workflow process to execute sending the e-mail shown in Figure 21-23.

Figure 21.23. Figure 21-23

The SMTP Event Bus Sample is a great example of the extensibility and power of the K2 blackpearl platform. The Event Bus allowed us to easily monitor an external system for events and execute a workflow process, using the contextual data of the event. The application of this concept in the enterprise is very exciting.

The Event Bus is a powerful addition to the K2 platform. It serves as a mechanism to allow external LOB system events to affect the K2 platform, to send custom notifications designed in the K2 Workspace, to launch processes based on custom events and data contained within those events, and to schedule recurring events. The Event Bus is a critical component that brings reliable, message-based event processing to the K2 platform. In the next chapter we'll look at how to take advantage of some of the advanced features of K2 blackpearl as well as some advanced process scenarios.

^[21]