At minimum, a business process class contains the operation methods OnRequest and OnResponse. A business process class also provides the SendDeferredResponse method to support a deferred response from a business operation.
Additionally, the Ens.BusinessProcess class defines a set of methods that you can use within a custom- coded business process. BPL-generated code uses these methods automatically. They include the
SendRequestSync, SendRequestAsync, and SetTimer methods documented in this section, as well
as assorted others. You can view the complete Ens.BusinessProcess class using Ensemble Studio.
6.2.1 The OnRequest Method
The business process’s OnRequest method is called whenever an initial request for a specific business process arrives on the appropriate queue and is assigned a job in which to execute. 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.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 }
This method takes the following arguments: • pRequest — The incoming request object.
• pResponse — The response returned by this business process.
6.2.2 The OnResponse Method
The business process’s OnResponse method is called 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. 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 }
This method takes the following arguments:
• pRequest — The initial request object sent to this business process.
• pResponse — The response object that will eventually be returned by this business process.
• pCallRequest — The request object associated with the incoming response.
• pCallResponse — The incoming response object.
• pCompletionKey — The completion key value associated with the incoming response. This is set
by the call to the SendRequestAsync method that made the request.
6.2.3 The SendRequestSync Method
This method makes a synchronous request to a business operation or business process: this method does not return until a response is received. This method takes the following arguments:
• pTargetDispatchName — The configuration name of the business process or business operation
to which the request is sent.
• pRequest — Any persistent object, but typically a subclass of Ens.Request. This object contains the data to send with the request.
• pResponse — (By reference) Any persistent object, but typically a subclass of Ens.Response. This object receives the data returned by the response.
• pTimeout — (Optional) The number of seconds to wait for a response. The default is –1 (wait
forever).
If no response is expected, you can use SendRequestAsync instead of SendRequestSync.
6.2.4 The SendRequestAsync Method
This method makes an asynchronous request to a business operation or business process: this method does not wait for a response before returning control to the caller.
This method takes the following arguments:
• pTargetDispatchName — The configuration name of the business operation or business process
that is the target for this request.
• pRequest — Any persistent object, but typically a subclass of Ens.Request. This object contains the data to send with the request.
• pResponseRequired — A Boolean flag indicating whether or not a response is needed for this
request. An integer value of 1 (true) indicates that this message requires a response. A value of 0 (false) means the message does not require a response.
• pCompletionKey — An optional string value that lets you associate a name with this request. This
value is passed to the OnResponse method when the response returns and allows you to determine which request a specific response is associated with.
6.2.5 The SendDeferredResponse Method
All business hosts support the SendDeferredResponse method. This method permits a business host to participate in the Ensemble deferred response convention by identifying a previously deferred request, constructing the actual response message, and directing this response to the business host that originated the request. For an overview, see the Deferred Response section in the “Ensemble Messages” chapter.
This topic describes the role of a business process in this convention. Suppose an incoming event arrives in Ensemble along with a deferred response token, and suppose the arrival point for this event is a business process. A business service is the more common case, but it is also possible for a business process to send deferred responses. When it receives the data required to complete a deferred response, the business process calls SendDeferredResponse to construct a response message and direct it to the caller that originated the request. The SendDeferredResponse call looks like this:
Set sc = ..SendDeferredResponse(token, pResponseBody)
SendDeferredResponse takes the following arguments:
• token — A string that identifies the deferred response so that the caller can match it to the original
request. The business process obtains the token string through some mechanism unique to the production.
For example, if the external destination is email, when sending a request for which it is willing to receive a deferred response, a business operation can include the token string in the subject line of the outgoing email. The entity receiving this email can extract this token from the request subject line and use it in the response subject line. This preserves the token so that the business process receiving the response email can use it in a subsequent call to SendDeferredResponse. • pResponseBody — Any persistent object, but typically a subclass of Ens.Response. This object
contains the actual response message.
6.2.6 The SetTimer Method
This method sets up a timer indicating how long to wait for pending asynchronous responses. Any responses received after this time are discarded and not processed. This method takes the following arguments:
• pDuration — An XML duration value. This is a string of one or more characters; for example “P60S” for 60 seconds or “P1Y2M3DT10H30M” for 1 year, 2 months, 3 days, 10 hours, and 30 minutes.
For the syntax of an XML duration string, see the “Primitive Datatypes” section of the W3C Recommendation XML Schema Part 2: Datatypes Second Edition, which you can view at
http://www.w3.org/TR/xmlschema-2/#duration.
6.2.7 The IsComponent Method
Ens.BusinessProcessBPL, the base class for all BPL business processes, offers a class method
IsComponent which returns 1 (true) if the BPL business process has been designated a reusable component, 0 (false) if not.