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.
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.
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.
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 cannot 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 11, Advisory Events for more information about advisory events.
When configuring the invokeProcess() function in a rule or rule function, specify the parameters as follows:
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:
|
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.
|
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.
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.
|
When configuring the startProcess() function in a rule or rule function, specify the following in the parameters:
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 cannot pass an event or concept.)
|
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 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.
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.
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: