At minimum, a business service class contains the following operation methods: OnInit, OnTearDown,
OnProductionStart, OnProductionStop, and OnProcessInput. A business service class also provides
methods to send messages to business processes or business operations, as follows: SendRequestSync sends a message synchronously (waits for a response), SendRequestAsync sends a message asyn- chronously (does not wait for a response), and SendDeferredResponse sends a response that was previously deferred by a business operation. Finally, for custom business services that determine their message targets at runtime rather than at configuration time, the OnGetConnections method is available to tell the Ensemble internal framework which configuration items are the targets of this business service.
5.2.1 The OnInit Method
A business service class may override the OnInit method. This method is called after the business service object has been created and its configurable property values have been set. The OnInit method provides a way for a business service to perform any special setup actions.
Method OnInit() As %Status {
Quit $$$OK }
5.2.2 The OnTearDown Method
A business service class may override the OnTearDown method. This method is called during shutdown before the business service object is destroyed. The OnTearDown method provides a way for a business service to perform any special cleanup actions.
Method OnTearDown() As %Status {
Quit $$$OK }
5.2.3 The OnProductionStart Method
A business service class may override the OnProductionStart method. This class method is called once for each configured business service when a production is started. The OnProductionStart method provides a way for a business service to perform any special business service-wide setup actions.
ClassMethod OnProductionStart() As %Status {
Quit $$$OK }
5.2.4 The OnProductionStop Method
A business service class may override the OnProductionStop method. This class method is called once for each configured business service when a production is stopped. The OnProductionStop method provides a way for a business service to perform any special business service-wide cleanup actions.
ClassMethod OnProductionStart() As %Status {
Quit $$$OK }
5.2.5 The OnProcessInput Method
The OnProcessInput method is where the actual work of the business service takes place. When an inbound adapter receives an event, it calls the business service ProcessInput method. This, in turn, calls the OnProcessInput method. The OnProcessInput method is passed, as an input argument, an object representing the incoming event. The business service author defines the type of this event. The OnProcessInput method is intended to do the following things:
1. Validate, if necessary, the incoming event object.
2. Transform the incoming event object into a specific Ensemble request object (a subclass of
Ens.Request).
3. Send the request on to a business process or business operation for processing.
The following is a simple example of an OnProcessInput method:
Method OnProcessInput(pInput As %RegisteredObject, pOutput As %RegisteredObject) As %Status
{
// construct a request object using values from input object Set tRequest = ##class(MyRequest).%New()
Set tRequest.Value = pInput.Value
// send request to MyProduction.Operation
Set tSC = ..SendRequestAsync("MyProduction.Operation", tRequest) Quit tSC
}
The OnProcessInput method can send a request using SendRequestSync or SendRequestAsync.
5.2.6 The SendRequestSync Method
A request is synchronous when the business service invokes its SendRequestSync method to make the request. A call to SendRequestSync requires the business service to wait, and do nothing else, until it receives a response from the call. To send a synchronous request from a business service, use the SendRequestSync method as follows:
Set tSC = ..SendRequestSync(pTargetDispatchName, tRequest, .tResponse)
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.
5.2.7 The SendRequestAsync Method
A request is asynchronous when the business service invokes its SendRequestAsync method to make the request. A call to SendRequestAsync requires the business service to “fire and forget” — that is,
the request is sent and the business service continues its next activity without waiting for a response from the call.
To send an asynchronous request from a business service, use the SendRequestAsync method as fol- lows:
Set tSC = ..SendRequestAsync(pTargetDispatchName, tRequest)
This method takes the following arguments:
• pTargetDispatchName — The configuration name of the business process or business operation
to which the request is sent.
• tRequest — Any persistent object, but typically a subclass of Ens.Request. This object contains the data to send with the request.
5.2.8 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 service 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 service. This business service then calls SendDeferredResponse to construct a response 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 service 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 service 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.
5.2.9 The OnGetConnections Method
In ordinary circumstances, it is a simple matter for the Ensemble internal framework to determine which configuration items are the targets of messages from a business service. It simply reads the configuration settings for the business service. It does this when needed to accurately render the con- figuration diagram of your production, which shows the logical connections between configuration items in the business service, business process, and business operation columns. To view examples of this diagram, see the “onfiguration” chapter in Managing Ensemble Productions.
For custom business services that determine their message targets dynamically, at runtime, rather than at configuration time, the OnGetConnections method is available to tell the Ensemble internal framework which configuration items are the targets of this business service.
Normally it is not necessary for you to write an OnGetConnections method for a business service. Most business services simply inherit this method from the base class for business hosts, Ens.Host. However, if your business service does determine its message targets dynamically, you can override
OnGetConnections in your business service class. The Ensemble framework will call your version
of the method automatically whenever it needs to render the configuration diagram of your production. An OnGetConnections method must have the following signature:
ClassMethod OnGetConnections(Output pArray As %String,
item As Ens.Config.Item) [ CodeMode = generator ]
Where the arguments are as follows:
• pArray — A string that this method constructs. When the method returns, this string must contain
a comma-separated list of the configured names of items to which this business service sends messages. Alternatively, if there are no targets at the present time, this string may be blank (""). • item — The Ens.Config.Item object that represents this business service.
For examples of overridden OnGetConnections methods, use Studio to view the class code for the built-in business services provided for use with electronic data interchange protocols such as HL7 and X12. These are described in detail in books such as the Ensemble HL7 Version 2 Development Guide
and the Ensemble X12 Development Guide.