The integration model provides a BusinessWorks category of functions. This category is located in the General Functions library. Use and configuration of the functions in the BusinessWorks category are described in this section. See
Feature Summary for a brief introduction to the integration features.
Use this function to take advantage of ActiveMatrix BusinessWorks features. For example, you could use
invokeProcess() to send customer information to an ActiveMatrix BusinessWorks process which gets the discount information from a database and returns it to BusinessEvents.
When a rule containing or calling invokeProcess() is triggered,
invokeProcess() calls the specified ActiveMatrix BusinessWorks process and passes it an event. The
invokeProcess() function executes synchronously, so the BusinessEvents rule engine waits. The ActiveMatrix BusinessWorks process performs its work and returns an event or null at completion of the process, or it times out if you set a timeout that is exceeded. It generates an advisory event if it times out. Events received by the rule are not automatically asserted.
BusinessEvents asserts an advisory event and returns null if the ActiveMatrix BusinessWorks process fails, or if the invocation times out. The advisory event category is
Engine, and the type is
INVOKE BW PROCESS. The message contains the error message from the failed ActiveMatrix BusinessWorks process, or the timeout message. The advisory event is also created if the process is cancelled using
cancelProcess(), because the system can’t differentiate between different causes for the process stopping before completion.
Because the invokeProcess() function returns null when an error occurs, you must handle the possibility of a
null return in rules that use any property or attribute of the returned event.
When configuring the invokeProcess() function in a rule or rule function, specify the parameters as follows:
For example, you might send customer information from an event (alias neworder) to an ActiveMatrix BusinessWorks process, which returns an event with the discount level to offer:
|
Timeouts If you set a timeout period and a timeout occurs, the rule or rule function containing InvokeProcess() continues without waiting for the ActiveMatrix BusinessWorks process to complete. If you use a timeout, set it to a period long enough for the ActiveMatrix BusinessWorks process to complete. Include logic to handle the case that the invokeProcess() function does time out.
|
Configure the Start activity of the specified ActiveMatrix BusinessWorks process to accept the event passed by the
invokeProcess() function, if an event is passed. In the Input Editor, specify the event type. Then in the Input tab, map the event properties to the process properties. If you specify null, of course, this step is not required.
Similarly, In the Output Editor of the End activity, specify the event type to return to the
invokeProcess() process. In the Output tab, map the process data to the event properties.
You would use the startProcess() function when you want to invoke an ActiveMatrix BusinessWorks process that performs work that can be completed asynchronously. The
startProcess() function invokes an ActiveMatrix BusinessWorks process in asynchronous mode and immediately returns the job ID of the process. Rule processing continues. When the ActiveMatrix BusinessWorks process completes, it passes an event to a callback rule function that is specified in a
startProcess() argument. For example, you send order information to an ActiveMatrix BusinessWorks order fulfillment process. When the order ships, notification is returned to BusinessEvents, which updates a customer concept instance.
When a rule containing or calling startProcess() is triggered,
startProcess() calls the specified ActiveMatrix BusinessWorks process and passes it an event.
startProcess() returns the
jobID of the ActiveMatrix BusinessWorks process. (You can use the returned job ID, for example, in the
cancelProcess() rule function.) The function executes asynchronously, so the BusinessEvents rule engine continues while at the same time the ActiveMatrix BusinessWorks process executes. The ActiveMatrix BusinessWorks process performs its work and passes an event to the callback (
ruleFnURI) rule function specified in the
startProcess() function arguments. The
ruleFnURI rule function performs its work, for example, creating and asserting the event into the rule engine.
|
The ruleFnURI rule function must not modify concept instances or scorecards.
|
When configuring the startProcess() function in a rule or rule function, specify the following in the parameters:
The rule function specified in the startProcess() ruleFnURI argument is called when the ActiveMatrix BusinessWorks process completes.
For short, this rule function is referred to as the ruleFnURI rule function in this guide. The
ruleFnURI rule function must have the following signature, and the Validity field (in the Configuration tab) must be set to Action:
void ruleFn(long jobID, int status, Event outputEvent, Object closure)
●
|
jobID The job id can be used to correlate the information passed to ruleFnURI with related information in BusinessEvents.
|
●
|
status Returns 0 (zero) if the process completed successfuly, and -1 if the process did not complete successfully (for example because cancelProcess() was called).
|
●
|
outputEvent An event passed to it by the ActiveMatrix BusinessWorks process. It can be created by the process, or it can be an existing event.
|
●
|
closure A closure object could be, for example, a value from the original context that has to be passed back to the BusinessEvents engine, for example, a loan rate that has been promised. (Note that type is Object, so you can’t pass an event or concept.)
|
Add the ruleFnURI rule function to the BusinessEvents project.
Configure the Start activity of the specified ActiveMatrix BusinessWorks process to accept the event passed by the
startProcess() function, if an event is passed. In the Input Editor, specify the event type. Then in the Input tab, map the event properties to the process properties. If you specify null, of course, this step is not required.
In the Input Editor of the End activity, specify the event type that is to be passed to the specified ruleFnURI rule function. In the Input tab, map the process data to the event properties.
The returned event is then used as needed by the logic of the rule or rule function. Note that if you want to assert the event that is returned, you must explicitly assert it.
Use the cancelProcess() function to cancel a long running process, specified by
jobID.
The init() function initializes the ActiveMatrix BusinessWorks engine if it is not already running. Use of
init() when the engine is already running is harmless.
Use of init() is optional. It is provided as a convenience. For example you can use it in a BusinessEvents startup rule function to initialize the ActiveMatrix BusinessWorks engine at startup, so as to save valuable time later.
If invokeProcess() or
startProcess() are executed when the ActiveMatrix BusinessWorks engine is not already started, they will start the engine at that time.
When ActiveMatrix BusinessWorks is the container, init() is not required. However its use is harmless.
A general good practice is to call init() to start the ActiveMatrix BusinessWorks engine in a startup rule function (specified in the Startup/Shutdown tab of the BAR). The
init() function takes no parameters. The rule function might simply contain this code:
The shutdown () function shuts down the ActiveMatrix BusinessWorks engine if it is running. Use of shutdown
() when the engine is already shut down is harmless.
When ActiveMatrix BusinessWorks is the container, shutdown() is ignored. Its presence is harmless.
Use of shutdown() is optional. It is recommended that you use it only when you have finished using the ActiveMatrix BusinessWorks engine, and won’t need to start it again. Stopping and restarting the engine is not necessary and can affect performance
Simply place the shutdown command so that it is executed when needed. The shutdown() function takes no parameters. The rule function might simply contain this code: