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 Integration Components for a brief introduction to these features.
Providing Paths to TIBCO BusinessEvents Project Resources Using Schemas
The BusinessWorks.invokeProcess() and BusinessWorks.startProcess() functions can send events to and receive events from ActiveMatrix BusinessWorks processes. However, the paths to TIBCO BusinessEvents project resources are not available by default in TIBCO Designer. To use these functions successfully, you must generate the event schemas in TIBCO BusinessEvents and import them into the TIBCO Designer project. See Exporting (Generating) Concept and Event Schema (XSD) Files for details on exporting the event schemas.
In the TIBCO Designer project, import these schemas and use them in the relevant processes, so that the event resource path is known to TIBCO Designer. See ActiveMatrix BusinessWorks documentation for details.
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 that gets the discount information from a database and returns it to TIBCO BusinessEvents.
Runtime Behavior
If the ActiveMatrix BusinessWorks engine is not already started, TIBCO BusinessEvents will start it before invokeProcess() executes. See 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 TIBCO 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 are not automatically asserted.
Error Handling and Advisory Events
TIBCO 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 Chapter 10, Advisory Events for more information about advisory events.
Do not use invokeProcess() more than once in the same thread of execution. See Thread Management.
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 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 = 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. 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 End activity, specify the event type to return to the invokeProcess() process.
The returned event is then used as needed by the logic of the rule or rule function.
Using startProcess()
Purpose
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 TIBCO BusinessEvents, which updates a customer concept instance.
Runtime Behavior
If the ActiveMatrix BusinessWorks engine is not already started, TIBCO BusinessEvents will start it before startProcess() executes. See 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 TIBCO 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.
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 TIBCO BusinessEvents rule function that the process calls on completion (the callback rule function). The required signature for the callback rule function is shown below.
Configuring the ruleFnURI Rule Function
The callback rule function, specified in the startProcess() ruleFnURI argument, is called when the ActiveMatrix BusinessWorks process completes. Add the ruleFnURI rule function to the TIBCO BusinessEvents project.
For convenience, this rule function is referred to as the ruleFnURI rule function in this section. 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  Type: long. The job id can be used to correlate the information passed to ruleFnURI with related information in TIBCO BusinessEvents.
status  Type: int. Returns 0 (zero) if the process completed successfuly, and -1 if the process did not complete successfully (for example because cancelProcess() was called).
outputEvent  Type: Event. An event passed to the rule function by the ActiveMatrix BusinessWorks process. It can be created by the process, or it can be an existing event. If the process fails or is cancelled (for example because cancelProcess() was called), an advisory event is returned.
closure  Type: Object. A closure object could be, for example, a value from the original context that has to be passed back to the TIBCO 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.)
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. 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 End activity, specify the event type that is to be passed to the specified ruleFnURI rule function.
See Providing Paths to TIBCO BusinessEvents Project Resources Using Schemas above for additional setup you must do.
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.
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().
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 TIBCO 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.
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();
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.
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();