Chapter 12 In-Process ActiveMatrix BusinessWorks Integration : Working With the BusinessWorks Functions

Working With the BusinessWorks Functions
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.
Configuring and Using invokeProcess()
Purpose
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.
Runtime Behavior
If the ActiveMatrix BusinessWorks engine is not already started, BusinessEvents will start it before invokeProcess() executes. See Configuring and Using init() for another way to start the engine.
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.
Error Handling and Advisory Events
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.
See Understanding and Working With Advisory Events for more information about advisory events.
Do not use invokeProcess() more than once in the same thread of execution. See Avoiding Threading Issues.
Configuring the Function
When configuring the invokeProcess() function in a rule or rule function, specify the parameters as follows:
The ActiveMatrix BusinessWorks process that the function invokes. The specified process must not contain a process starter.
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:
Events/Discountlevel Discount;
Discount = ActiveMatrix BusinessWorks.invokeProcess("/Processes/CustInfo", neworder, 0);
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.
Configuring the Process
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.
Configure the rest of the activities in the process to carry out whatever processing is desired using the data passed into it by invokeProcess().
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.
The returned event is then used as needed by the logic of the rule or rule function.
Configuring and Using startProcess()
Purpose
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.
Runtime Behavior
If the ActiveMatrix BusinessWorks engine is not already started, BusinessEvents will start it before startProcess() executes. See Configuring and Using init() for another way to start the engine.
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.
Configuring the Function
When configuring the startProcess() function in a rule or rule function, specify the following in the parameters:
The ActiveMatrix BusinessWorks process that the function invokes. The specified process must not contain a process starter.
The BusinessEvents rule function that the process calls on completion (known as a callback rule function). The required signature for the rule function that is called when the process completes is shown below.
Configuring the ruleFnURI Rule Function
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.
Configuring the Process
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.
Configure the rest of the activities in the process to carry out whatever processing is desired using the data passed into it by startProcess().
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.
Configuring and Using cancelProcess()
Purpose
Use the cancelProcess() function to cancel a long running process, specified by jobID.
Cancellation may fail if the process has already completed before receiving the cancellation command. In this case, the following exception is thrown:
java.lang.Exception: Job JobId not found
Configuration
The job ID for the process you want to cancel is provided in the return value of startProcess().
Configuring and Using init()
Purpose
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.
Configuration
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:
BusinessWorks.init();
Configuring and Using shutdown()
Purpose
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
Configuration
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:
BusinessWorks.shutdown();