Developing Ensemble Productions
Defining Business Services
This chapter describes how to define business service classes. It contains the following sections:
A business service is responsible for accepting requests from external applications into Ensemble. The following figure shows how it works:
Note that this figure shows only the input flow of data, not the optional response.
A business service is responsible for the following activities:
Waiting for a specific external event (such as notification from an application, receipt of a TCP message, etc.).
Reading, parsing, and validating the data accompanying such an event,
Returning, if required, an acknowledgment to the external application indicating that the event was received.
Creating an instance of an Ensemble request message and forwarding it on to the appropriate business process or business operation for processing.
The purpose of a business service is usually to receive data input. In most cases, a business service has an inbound adapter associated with it. However, in some cases an adapter is not required, either because an application is capable of sending Ensemble request messages into the service or because the business service has been written to handle external calls of a particular kind, for example from a composite application. A business service of this type is called an adapterless
When a business service has an inbound adapter, it is in the data pulling
(as opposed to pushing
) mode. In this mode, the business service polls the adapter at regular intervals to see if it has data. Meanwhile, if the adapter encounters input data at any time, it calls the business service to process the input.
When a business service does not have an adapter, it does not pull
data. Instead, client applications call the business service and tell it to process input (this is a data pushing
Within a business service, you can access properties and methods of the associated adapter, which is available as the Adapter
property of the business service. This means that you can alter the default behavior of the adapter; it may or may not be appropriate to do so. It is useful to remember the principle of encapsulation. The idea of encapsulation is that the adapter class should be responsible for the technology-specific logic, while the business service class should be responsible for the production-specific logic.
If you find that it is necessary to greatly or frequently alter the behavior of an adapter class from within a business service class, it might be more appropriate to create a customized subclass of the adapter class. See Less Common Tasks.
This principle also applies to business operations.
Defining a Business Service Class
To create a business service class, define a class as follows:
Implementing the OnProcessInput() Method
Within your business service class, your OnProcessInput()
method can have the following generic signature:
Method OnProcessInput(pInput As %RegisteredObject, pOutput As %RegisteredObject) As %Status
is the input object that the adapter will send to this business service, and pOutput
is the output object.
First look at the adapter class that you have selected. InterSystems recommends that you edit the OnProcessInput()
method signature to use the specific input argument needed with the adapter.
Optionally set properties of the business service class (at any appropriate time). The business service property of greatest interest is %WaitForNextCallInterval
. Its value controls how frequently Ensemble invokes the OnTask()
method of the adapter.
Validate, if necessary, the input object.
Examine the input object and decide how to use it.
Create an instance of a request message class, which will be the message that your business service sends.
For the request message, set its properties as appropriate, using values in the input object.
Determine where you want to send the request message. When you send the message, you will need to use the configuration name of a business host within the production.
Send the request message to a destination within the production (a business process or business operation). See the next section
Make sure that you set the output argument (pOutput
). Typically you set this equal to the response message that you have received. This step is required.
Return an appropriate status. This step is required.
In your business service class, your implementation of OnProcessInput()
should send a request message to some destination within the production. To so, call one of the following instance methods of the business service class, as appropriate for your needs:
Using the SendRequestSync() Method
Set tSC = ..SendRequestSync(pTargetDispatchName, pRequest, .pResponse, pTimeout)
Using the SendRequestAsync() Method
Set tSC = ..SendRequestAsync(pTargetDispatchName, pRequest)
Using the SendDeferredResponse() Method
This topic describes the role of a business service in this mechanism. 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 create a response and direct it to the caller that originated the request. The SendDeferredResponse()
call looks like this:
Set sc = ..SendDeferredResponse(token, pResponseBody)
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()
Processing Only One Event Per Call Interval
This restricts the business service to processing only one input event per CallInterval
, even when multiple input events exist.
This information applies to business services that use an adapter that have a property named CallInterval
and that use that property as a polling interval.