Variables Available in BPL (Execution Context)

Introduction

The life cycle of a business process requires it to have certain state information saved to disk and restored from disk, whenever the business process suspends or resumes execution. This feature is especially important for long-running business processes, which may take days or weeks to complete.

A BPL business process supports the business process life cycle with a group of variables known as the execution context. InterSystems IRIS automatically save the variables in the execution context and restores them each time the BPL business process suspends and resumes execution. These variables are available to every BPL business process; that is, to every business process class that inherits from Ens.BusinessProcessBPLOpens in a new tab.

Some of the execution context variables are available to every activity within a BPL business process. Others are generally available, but go in and out of scope, depending on the type of activity that the business process is executing at the time.

The context Object

The context object is available to a BPL business process anywhere inside the <process> element. context is a general-purpose container for any data that needs to be persisted during the life cycle of the business process. You define each data item as a property on the context object when creating the BPL business process. See Defining the context Object for the recommended procedure.

Once you have defined properties on the context object, you can refer to them anywhere in BPL using ordinary dot syntax and the property name, as in: context.MyData

The request Object

The request object contains the properties that were in the original request message object — the incoming message that first caused this business process to be instantiated. This is known as the primary request.

The request object is available to a BPL business process anywhere inside the <process> element. You can refer to the properties of the request object using dot syntax and the property name, as in: request.OriginalThought

The response Object

The response object contains the properties that are required to build the final response message object to be returned by this business process instance. The business process returns this final response either when it reaches the end of its life cycle, or when it encounters a <reply> activity.

The response object is available to a BPL business process anywhere inside the <process> element. You can refer to the properties of the response object using dot syntax and the parameter name, as in: response.BottomLine

The callrequest Object

The callrequest object contains any properties that are required to build the request message object to be sent by a <call>.

A <call> activity sends a request message and, optionally, receives a response. A BPL <call> element must include a <request> activity to put values into the properties on the request message object. In order to accomplish this, the <request> provides a sequence of <assign> activities that place values into properties on the callrequest object. Typically, some of these values are derived from properties on the original request object, but you are free to assign any value.

As soon as the <assign> activities inside the <request> are completed, the message is sent, and the associated callrequest object goes out of scope. callrequest has no meaning outside its associated <request> activity; it is already out of scope when the associated <call> begins processing its next activity, the optional <response>.

Within the scope of the relevant <request> element, you can refer to the properties on callrequest using dot syntax, as in: callrequest.UserData

The callresponse Object

Upon completion of a <call> activity, the callresponse object contains the properties of the response message object that was returned to the <call>. If the <call> was designed with no response, there is no callresponse. Similarly, if you use <sync> to wait for a response, but the response does not return within the timeout period specified by the <sync> element, there is no callresponse.

Every <call> that expects a response must provide a <response> activity within the <call>. The purpose of the <response> activity is to retrieve the response values and make them available to the business process as a whole. The callresponse object is available anywhere inside the <response> activity. However, as soon as the <response> activity completes, the associated callresponse object goes out of scope. Therefore, if you want to use the values in callresponse elsewhere in the business process, you must <assign> these values to properties on the context or response objects, and you must do so before the end of the <response> activity in which they were received.

You can refer to the properties on callresponse using dot syntax, as in: callresponse.UserAnswer

The syncresponses Collection

syncresponses is a collection, keyed by the names of the <call> activities being synchronized by a <sync>.

When a <sync> activity begins, syncresponses is cleared in preparation for new responses. As the <call> activities return, responses go into the collection. When the <sync> activity completes, syncresponses may contain all, some, or none of the desired responses (see synctimedout). syncresponses is available anywhere inside the <sequence> that contains the relevant <call> and <sync> activities, but goes out of scope outside that <sequence>.

To refer to the response value from one of the synchronized calls, use the syntax: syncresponses.GetAt("name")

Where the relevant <call> was defined as: <call name="name">

The synctimedout Value

synctimedout is an integer value that may be 0, 1, or 2. synctimedout indicates the outcome of a <sync> activity after several calls. You can test the value of synctimedout after the <sync> and before the end of the <sequence> that contains the calls and <sync>. synctimedout has one of three values:

• If 0, no call timed out. All the calls had time to complete. This is also the value if the <sync> activity had no timeout set.

• If 1, at least one call timed out. This means not all <call> activities completed before the timeout.

• If 2, at least one call was interrupted before it could complete.

synctimedout is available to a BPL business process anywhere inside the <sequence> that contains the relevant <call> and <sync> activities, but goes out of scope outside that <sequence>. Generally you will test synctimedout for status and then retrieve the responses from completed calls out of the syncresponses collection. You can refer to synctimedout with the same syntax as for any integer variable name, that is: synctimedout

The status Value

status is a value of type %StatusOpens in a new tab that indicates success or failure.

When a BPL business process starts up, status is automatically assigned a value indicating success. To test that status has a success value, you can use the macro $$$ISOK(status) in ObjectScript. If the test returns a True value, status has a success value.

As the BPL business process runs, if at any time status acquires a failure value, InterSystems IRIS immediately terminates the business process and writes the corresponding text message to the Event Log. This happens regardless of how status acquired the failure value. Thus, the best way to cause a BPL business process to exit suddenly, but gracefully is to set status to a failure value.

status can acquire a failure value in any of the following ways:

• status automatically receives the returned %StatusOpens in a new tab value from any <call> that the business process makes to another business host. If the value of this %StatusOpens in a new tab indicates failure, status automatically receives the failure value. This is the most common way in which status is set, and it happens automatically, without any special statements in the BPL code.

• An <assign> activity can set status to a failure value. The usual convention for doing this is to use an <if> element to test the result of some prior activity, and then within the <true> or <false> element use <assign> to set status to a failure value when failure conditions exist.

• Statements within a <code> activity can set status to a failure value. The BPL business process does not perceive the change in the value of status until the <code> activity has fully completed. Therefore, if you want a failure status to cause an immediate exit from a <code> activity, you must place a quit command in the <code> activity immediately after setting a failure value for status.

To test that status has a failure value, use the macro $$$ISERR(status) in ObjectScript. If the test returns a True value, status has a failure value. You will be able to perform this test only within the body of a <code> activity before it returns to the main BPL business process, since the business process will automatically quit with an error as soon as it detects that status has acquired a failure value following any <call>, <assign>, or <code> activity.

status is available to a BPL business process anywhere inside the <process>. You can refer to status with the same syntax as for any variable of the %StatusOpens in a new tab type, that is: status

The process Object

The process object represents the current instance of the BPL business process object. The process object is provided so that you can invoke any business process method, such as SendRequestSync() or SendRequestAsync(), from any context within the flow of the BPL business process, for example from within the text block of a <code> activity.

The process object is available to a BPL business process anywhere inside the <process> element, but is typically needed only within the <code> activity. You can refer to methods of the process object using dot syntax and the method name, as in: process.SendRequestSync() or process.ClearAllPendingResponses