Developing Ensemble Productions
Defining Business Processes
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Business processes are responsible for the higher level processing within a production. This chapter introduces them and discusses how to design and develop business process classes. It contains the following sections:

Introduction
By convention, business processes contain most of the logic of the production. They can contain their own logic and they can call business rules and data transformations, each of which also contains specialized logic. The following figure illustrates this:
Note that this figure shows only the request messages.
There are many possible uses for business processes. In some cases, a business process coordinates a series of actions in one or more external applications. It contains the logic to determine the processing and it calls business operations or other business processes as needed. Business processes can also include human interaction; for details, see Developing Workflows.
Ensemble provides the following general types of business process:
A production can include any mix of these business processes.
Note that Ens.BusinessProcessBPL, EnsLib.MsgRouter.RoutingEngine, and EnsLib.MsgRouter.VDocRoutingEngine are all based on Ens.BusinessProcess.
Comparison of Business Logic Tools
You will probably develop business processes in conjunction with the data transformations and business rules that they use. Data transformations and business rules are intended to contain specific kinds of logic:
There is, however, overlap among the options available in business processes, data transformations, and business rules. To assist you in determining how to create these items, the following table compares them. It discusses BPL (the most common business process), DTL (the most common data transformations), and business rules.
Option Supported in BPL? Supported in DTL? Supported in business rules?
Retrieving information about the business process Yes (business execution context variables) No No
Assigning a value Yes (<assign>) Yes (assign action) Yes (assign action)
Calling a data transformation Yes (<transform>) Yes (subtransform action) Yes (send action)
Calling a business rule Yes (<call>) No Yes (delegate action)
Calling custom code Yes (<code>) Yes (code action) No
Invoking SQL Yes (<sql>) Yes (sql action) No
Conditional logic Yes (<if>, <switch>, <branch>) Yes (if action) No
Looping Yes (<foreach>, <while>, <until>) Yes (for each action ) No
Sending an alert Yes (<alert>) No No
Including trace elements Yes (<trace>) Yes (trace action) Yes (trace action)
Sending a request message to a business operation or process Yes (<call>) No Yes (send action)
Waiting for a response from asynchronous requests Yes (<sync>) No No
Deleting the message No No Yes (delete action)
Performing error handling Yes (<throw>, <catch>, and others) No No
Delaying execution for a specified duration or until a future time Yes (<delay>) No No
Sending a primary response before execution is complete Yes (<reply>) No No
Using XPATH and XSLT Yes (<xpath>, <xslt>) No No
Storing a message temporarily to acknowledge a milestone Yes (<milestone>) No No
For details on DTL transformations and business rules, see Developing DTL Transformations and Developing Business Rules.
Key Principles
First, be sure to read the chapter Programming in Ensemble.”
When you develop business processes, consider the following key principles:
Defining BPL Business Processes
A BPL business process is a class based on Ens.BusinessProcessBPL. In this case, you can create and edit the process visually within either the Management Portal or Studio. For information, see Developing BPL Processes.
Defining Custom Business Processes
To create a custom business process class, define a class as follows:
Implementing the OnRequest() Method
A custom business process class must implement the OnRequest() method. An Ensemble production calls this method whenever an initial request for a specific business process arrives on the appropriate queue and is assigned a job in which to execute.
This method has the following signature:
method OnRequest(request As %Library.Persistent, Output response As %Library.Persistent) as %Status
Where:
Example
The following is an example of an OnRequest() method, from the Demo.Loan.BankUS sample class in the ENSDEMO namespace:
Method OnRequest(request As Demo.Loan.Msg.Application, Output response As Demo.Loan.Msg.Approval)
       As %Status
{
  Set $ZT="Trap",tSC=$$$OK
  Do {
    $$$TRACE("received application for "_request.Name)
    #;
    If $zcrc(request.Name,2)#5=0 {
      Set response = ##class(Demo.Loan.Msg.Approval).%New()
      Set response.BankName = "BankUS"
      Set response.IsApproved = 0
      $$$TRACE("application is denied because of bank holiday")
      Quit
    }
    #;
    Set tRequest = ##class(Demo.Loan.Msg.PrimeRateRequest).%New()
    Set tSC =..SendRequestAsync("Demo.Loan.WebOperations",tRequest,1,"PrimeRate")
    #;
    Set tRequest = ##class(Demo.Loan.Msg.CreditRatingRequest).%New()
    Set tRequest.SSN = request.SSN
    Set tSC =..SendRequestAsync("Demo.Loan.WebOperations",tRequest,1,"CreditRating")
    #;
    Set tSC = ..SetTimer("PT15S")
    #;
    Quit
  } While (0)
Exit
  Quit tSC
Trap
  Set $ZT="",tSC=$$$EnsSystemError Goto Exit
}
Implementing the OnResponse() Method
A custom business process class must implement the OnResponse() method. A production calls this method whenever a response for a specific business process arrives on the appropriate queue and is assigned a job in which to execute. Typically this is a response to an asynchronous request made by the business process.
This method has the following signature:
method OnResponse(request As %Library.Persistent, 
                  ByRef response As %Library.Persistent, 
                  callrequest As %Library.Persistent, 
                  callresponse As %Library.Persistent, 
                  pCompletionKey As %String) as %Status
This method takes the following arguments:
Example
The following is an example of an OnResponse() method, from the Demo.Loan.BankUS sample class in the ENSDEMO namespace:
/// Handle a 'Response'
Method OnResponse(request As Ens.Request,
                  ByRef response As Ens.Response,
                  callrequest As Ens.Request,
                  callresponse As Ens.Response,
                  pCompletionKey As %String) As %Status
{
    Set $ZT="Trap",tSC=$$$OK
    Do {
        If pCompletionKey="PrimeRate" {
            Set ..PrimeRate = callresponse.PrimeRate
        } Elseif pCompletionKey="CreditRating" {
            Set ..CreditRating = callresponse.CreditRating
        }
        Quit
    } While (0)
Exit
    Quit tSC
Trap
    Set $ZT="",tSC=$$$EnsSystemError Goto Exit
}
Methods to Use in OnRequest() and OnResponse()
When you implement OnRequest() and OnResponse(), you can use the following methods of the Ens.BusinessProcess class:
For details on these methods, see the Class Reference for Ens.BusinessProcess.