User-defined events

IBM® BPM features a new event framework for coach views. Using the new event framework and tools, you can develop user-defined events that leverage the programming extensions of the framework for custom coach views. And you can run your business logic from any of the event handlers. This methodology enables event handlers to react to numerous types of events, regardless of whether the events are triggered programmatically or by devices or user actions.

In IBM BPM, coach views communicate with other coach views by using data bindings. However, you can also use events to interact with other coach views. To illustrate the concepts in this topic, three related coach views named Revenue, Expenses, and Profit have been added to a client-side human service. These coach views all use events to interact with each other and they are all of the Decimal coach view type. The remainder of this topic describes some of the key features in the IBM BPM event framework for coach views.

A Control ID is an identifier that you can specify in JavaScript code to refer to a coach view. Control IDs can be referenced by other coach views to enable them to interact with each other using events. On the General tab of the Properties page, you can specify a control ID for a coach view in the Control ID field, as shown in the following image:

On the Properties page, the Events tab displays all user-defined event handlers for a coach view. Each event handler has an expandable JavaScript editor for adding the business logic and has content assist that you can invoke by pressing Ctrl-Space. The On Load and On change event handlers are shown in the following image:

To define user-defined events, use the Event built-in type that has been added to supplement the Object and Service build-in types. In the Variable Declarations pane, add one or more configuration options. And then in the Data pane, change one or more configuration options to events by selecting the Event radio button and specifying a name and label. In the following figure, the eventON_LOAD user-defined event is selected in the Variable Declarations pane and the corresponding name, label and documentation for this user-defined event are shown in the Data pane:

The eventON_LOAD user-defined event is a special event handler. If you define an event configuration option with the name eventON_LOAD, it will be automatically run in the load event handler.

To register a user-defined event after it has been defined, select an event handler in the Behavior pane and then use the JavaScript editor in the Code pane to optionally add registration logic. If you have additional variables that you would like to pass to the event handler, you can call the function registerEventHandlingFunction. However, if you do not call explicitly call the registration function, the event handler will be registered with no additional variables.

To designate when a user-defined event should fire, select an event handler in the Behavior pane and then use the JavaScript editor in the Code pane to add the required logic. In the logic, you need to call the function executeEventHandlingFunction to execute the event logic. In the following figure, the valueChange event is executed in the change event handler. The content assist was invoked on the this. statement by selecting Ctrl-Space to find and select the function executeEventHandlingFunction:

If you add the ${VIEW_ID} variable to the JavaScript editor of a user-defined event handler, you need to replace the token VIEW_ID with the control ID of another coach view, which provides your user-defined event handler with complete access to that coach view. For example, you could replace the ${VIEW_ID} variable with ${Revenue} (which is the control ID for the Revenue coach view). You could then call a function like ${Revenue}.getData() to obtain the current bound value for the Revenue coach view.