About BPL Processes
The Ensemble Business Process Language (BPL) is a language used to describe executable business processes within a standard XML document. BPL syntax is based on several of the proposed XML standards for defining business process logic. A BPL business process class is derived from Ens.BusinessProcessBPLOpens in a new tab. It is identical in every way to a class derived from Ens.BusinessProcessOpens in a new tab, except that it supports BPL.
To create BPL classes in the Management Portal, navigate to Ensemble > Build > Business Processes. Ensemble then displays the Business Process Designer page. (When you open a BPL class in Studio, you also invoke the Business Process Designer; see “Notes on Creating BPL in Studio.”)
When you navigate to the Business Process Designer page in the Management Portal, it opens with the last business process you worked on in this namespace. The tab at the left of the title bar contains the name of the BPL class. You can also choose to work on a different business process in one of the following ways:
-
Click New to create a BPL business process using the Business Process Wizard.
-
Click Open to edit an existing BPL business process using the Business Process Designer.
Note that there is overlap among the options available in business processes, data transformations, and business rules. For a comparison, see “Comparison of Business Logic Tools” in Developing Ensemble Productions.
Using the Business Process Wizard
The Business Process Wizard enables you to quickly create a BPL business process class inherited from Ens.BusinessProcessBPLOpens in a new tab. It provides the following dialog where you can define the preliminary characteristics of your BPL business process.
Enter values for the following fields:
Enter a package name to contain the business process class or select from a list of packages in the namespace.
Enter a name for your BPL business process class.
(Optional) Enter a description for the data transformation; this becomes the class description.
When you complete the wizard by clicking OK, the start and end points of the BPL diagram display in the Business Process Designer, ready for you to add activities to your BPL business process.
Business Process List
The Business Process List page displays a list of business process classes defined in the active Ensemble namespace. To navigate to this page in the Management Portal, select Ensemble > List > Business Processes.
BPL business processes are displayed in blue; you can double-click one to open it in the Business Process Designer. Business processes displayed in black are custom classes you must edit in Studio.
You can select a business process class to be the target of one of the following commands in the ribbon bar:
-
New — Click this to launch the Business Process Wizard, discussed earlier in this chapter.
-
Open (BPL classes only) — Click this to edit the selected business process.
-
Export — Click to export the selected business process class to an XML file.
-
Import — Click to import a business process that was exported to an XML file.
-
Delete — Click to delete the selected business process class.
-
Instances — Click to list any current instances of the business process in the running production. If a business process has completed its work, there is no entry for it on this page.
See Monitoring Ensemble.
-
Rule Log — Click to view the business rule log for rules invoked by this business process.
See Monitoring Ensemble.
You can also export and import business process classes as you do any other class in Ensemble. You can use the Classes page of the Management Portal (System Explorer > Classes) or use the Export and Import commands on the Tools menu in Studio.
BPL Features
BPL is a language used to describe executable business processes within a standard XML document. BPL syntax is based on several of the proposed XML standards for defining business process logic, including the Business Process Execution Language for Web Services (BPEL4WS or BPEL) and the Business Process Management Language (BPML or BPMI).
BPL is a superset of other proposed XML-based standards, in that it provides additional elements whose purpose is to help you build integration solutions. These additional elements include support for the following:
-
Execution flow control elements such as <branch>, <if>, <switch>, <foreach>, <while>, and <until>. For information about how to use these and other BPL syntax elements, see the Ensemble Business Process Language Reference.
-
Generation of executable code from business process logic.
-
Embedding SQL and custom-written code into the business process logic.
-
The Business Process Designer, a full-featured, visual modeling tool for graphically viewing and editing business process logic. This tool includes complete round-trip engineering between the visual and BPL representations of the business process. Changes to one representation are automatically reflected in the other.
-
Automatic support for both asynchronous and synchronous messaging between business processes and other members of an integration solution. BPL streamlines this difficult and error-prone programming task.
-
Persistent state. BPL permits a long-running business process to automatically suspend execution — and efficiently save its execution state to the built-in, persistent cache embedded in Ensemble — whenever it is inactive; for example, when it is waiting for an asynchronous response. Ensemble automatically manages all state preservation and the ability to smoothly resume processing.
-
Rich and varied data transformation services, including SQL queries embedded within the business process.
You can create a BPL business process using the Management Portal or Studio. The recommended way is to use the Business Process Wizard from the Business Process Designer page of the Management Portal. See later chapters of this book for details.
Using a Business Process as a Component
A business process component or BPL component is a BPL business process that a programmer wishes to identify as a modular, reusable sequence of steps in the BPL language. A BPL component is analogous to a function, macro, or subroutine in other programming languages.
Only another BPL business process can call a BPL component. It does this using the BPL <call> element. The BPL business process component performs tasks, then returns control to the BPL business process that called it.
The Ensemble architecture already allows one BPL business process to call another BPL business process. The optional component designation simply provides convenience. It allows you to classify certain BPL business processes as simpler, lower-level components that:
-
Are not intended to run as stand-alone business processes (although nothing in the architecture prevents this)
-
May be reusable (in the sense of a function, macro, or subroutine in the BPL language)
Business processes that are not components are assumed to have more complex, special-purpose designs, and to operate at a higher conceptual level than components. It is expected that BPL non-components call BPL components to accomplish tasks.
There is no requirement that you use the component designation for any BPL business process. It is available as a convenience for any BPL programmer who prefers it.
You make a business process into a component by setting an attribute of the top-level <process> container for the BPL business process. The attribute is called component and you can set it to 1 (true) or 0 (false). For syntax details, see the Ensemble Business Process Language Reference.
To set the value of the component attribute, you can do either of the following:
-
In the General tab of the Business Process Designer, select Is component to include this process in the Component Library.
-
Edit the BPL <process> element within the XData BPL block in the class code using Studio.
To set up a <call> to a component from a BPL business process, see “Adding a Call Activity,” later in this book.
Business Process Execution Context
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. Ensemble 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.
Custom business processes that inherit from Ens.BusinessProcessOpens in a new tab do not have access to a built-in execution context and must handle similar issues using custom code.
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 following topics describe the execution context variables and when they are available to a BPL business process. The variables are:
For detailed information about BPL syntax on BPL elements such as <process>, <context>, and <call>, see the Ensemble Business Process Language Reference, which also provides reference information for the context variables.
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.
Error handling for a BPL business process happens automatically without your ever needing to test or set the status value in the BPL source code. The status value is documented here in case you need to trigger a BPL business process to exit under certain special conditions.
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 and the method $SYSTEM.Status.IsOK(status) in Basic. 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, Ensemble 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 and the method $system.Status.IsError(status) in Basic. 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
Like all other execution context variable names, status is a reserved word in BPL. Do not use it except as described in this topic.
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
BPL Business Process Example
The following sample business process is similar to a class in the sample production package Demo.Loan in the ENSDEMO namespace. In this business process, three different banks can be consulted for prime rate and credit approval information.
/// Loan Approval Business Process for Bank Soprano.
/// Bank Soprano simulates a bank with great service but
/// somewhat high interest rates.
Class Demo.Loan.BankSoprano Extends Ens.BusinessProcessBPL
{
XData BPL
{
<process request="Demo.Loan.Msg.Application"
response="Demo.Loan.Msg.Approval">
<context>
<property name="CreditRating" type="%Integer"/>
<property name="PrimeRate" type="%Numeric"/>
</context>
<sequence>
<trace value='"received application for "_request.Name'/>
<assign name='Init Response'
property="response.BankName"
value='"BankSoprano"'>
<annotation>
<![CDATA[Initialize the response object.]]>
</annotation>
</assign>
<call name="PrimeRate"
target="Demo.Loan.WebOperations"
async="1">
<annotation>
<![CDATA[Send an asynchronous request for the Prime Rate.]]>
</annotation>
<request type="Demo.Loan.Msg.PrimeRateRequest"/>
<response type="Demo.Loan.Msg.PrimeRateResponse">
<assign property="context.PrimeRate"
value="callresponse.PrimeRate"/>
</response>
</call>
<call name="CreditRating"
target="Demo.Loan.WebOperations"
async="1">
<annotation>
<![CDATA[Send an asynchronous request for the Credit Rating.]]>
</annotation>
<request type="Demo.Loan.Msg.CreditRatingRequest">
<assign property="callrequest.TaxID" value='request.TaxID'/>
</request>
<response type="Demo.Loan.Msg.CreditRatingResponse">
<assign property="context.CreditRating"
value="callresponse.CreditRating"/>
</response>
</call>
<sync name='Wait'
calls="PrimeRate,CreditRating"
type="all"
timeout="10">
<annotation>
<![CDATA[Wait for the response from the async requests.
Wait for up to 10 seconds.]]>
</annotation>
</sync>
<switch name='Approved?'>
<case name='No PrimeRate'
condition='context.PrimeRate=""'>
<assign name='Not Approved'
property="response.IsApproved"
value="0"/>
</case>
<case name='No Credit'
condition='context.CreditRating=""'>
<assign name='Not Approved'
property="response.IsApproved"
value="0"/>
</case>
<default name='Approved' >
<assign name='Approved'
property="response.IsApproved"
value="1"/>
<assign name='InterestRate'
property="response.InterestRate"
value="context.PrimeRate+10+(99*(1-(context.CreditRating/100)))">
<annotation>
<![CDATA[Copy InterestRate into response object.]]>
</annotation>
</assign>
</default>
</switch>
<delay
name='Delay'
duration="2+($zcrc(request.Name,4)#5)">
<annotation>
<![CDATA[Wait for a random duration.]]>
</annotation>
</delay>
<trace value='"application is "
_$s(response.IsApproved:"approved for "_response.InterestRate_"%",
1:"denied")'/>
</sequence>
</process>
}
}
