Skip to main content


abstract class Ens.BusinessOperation extends Ens.Host, Ens.Util.IOLogger

Property Inventory

Method Inventory


parameter SETTINGS = ReplyCodeActions,RetryInterval,AlertRetryGracePeriod:Alerting,FailureTimeout,QueueCountAlert:Alerting,QueueWaitAlert:Alerting,SendSuperSession;
Inherited description: List of properties can be set as settings in the configuration file format is a comma separated list of property names


property %AlertStartTime as %String;
Time from which to start Alert retry grace period
Property methods: %AlertStartTimeDisplayToLogical(), %AlertStartTimeGet(), %AlertStartTimeIsValid(), %AlertStartTimeLogicalToDisplay(), %AlertStartTimeLogicalToOdbc(), %AlertStartTimeNormalize(), %AlertStartTimeSet()
property %RequestHeader as Ens.MessageHeader;
Property methods: %RequestHeaderGet(), %RequestHeaderGetObject(), %RequestHeaderGetObjectId(), %RequestHeaderGetSwizzled(), %RequestHeaderIsValid(), %RequestHeaderNewObject(), %RequestHeaderSet(), %RequestHeaderSetObject(), %RequestHeaderSetObjectId(), %RequestHeaderUnSwizzle()
property AlertRetryGracePeriod as %Numeric (MINVAL = 0) [ InitialExpression = 0 ];
When AlertOnError is True, and the Operation is retrying, refrain from alerting if the Operation succeeds within this number of seconds after an error
Property methods: AlertRetryGracePeriodDisplayToLogical(), AlertRetryGracePeriodGet(), AlertRetryGracePeriodIsValid(), AlertRetryGracePeriodLogicalToDisplay(), AlertRetryGracePeriodNormalize(), AlertRetryGracePeriodSet()
property DeferResponse as %Boolean [ InitialExpression = 0 ];
Set this property to 1 if you want to defer the response to the current message so that it can be completed asynchronously at a later time by a other code (usually a business service).
Property methods: DeferResponse(), DeferResponseDisplayToLogical(), DeferResponseGet(), DeferResponseIsValid(), DeferResponseLogicalToDisplay(), DeferResponseNormalize(), DeferResponseSet()
property FailureTimeout as %Numeric (MINVAL = -1) [ InitialExpression = 15 ];
Total number of seconds to keep trying to deliver the message.
After this number of seconds has elapsed, the business operation discards the message data and returns an error code.
To ensure that no message is ever skipped, enter a Failure Timeout value of -1, which means 'Never time out'.
Use a setting of -1 when complete data delivery is critical, for example in health care applications.
Property methods: FailureTimeoutDisplayToLogical(), FailureTimeoutGet(), FailureTimeoutIsValid(), FailureTimeoutLogicalToDisplay(), FailureTimeoutNormalize(), FailureTimeoutSet()
property NoFailWhileDisconnected as %Boolean;
Suspend counting seconds toward FailureTimeout while disconnected.
Does not apply if FailureTimeout=-1 or StayConnected=0.
Property methods: NoFailWhileDisconnectedDisplayToLogical(), NoFailWhileDisconnectedGet(), NoFailWhileDisconnectedIsValid(), NoFailWhileDisconnectedLogicalToDisplay(), NoFailWhileDisconnectedNormalize(), NoFailWhileDisconnectedSet()
property QueueCountAlert as %Numeric (MINVAL = 0) [ InitialExpression = 0 ];
Number of messages on this item's queue needed to trigger an Alert message to be sent. Note that no further alerts will be sent unless the number of messages on the queue drops below 80% of this number and then rises again to this number.
Note that this alert will be sent even if AlertOnError is False.
Zero means no alerts of this type will be sent.
Property methods: QueueCountAlertDisplayToLogical(), QueueCountAlertGet(), QueueCountAlertIsValid(), QueueCountAlertLogicalToDisplay(), QueueCountAlertNormalize(), QueueCountAlertSet()
property QueueWaitAlert as %Numeric (MINVAL = 0) [ InitialExpression = 0 ];
The number of seconds a message at the front of the queue may have waited since being queued before an alert is triggered.
Only one alert will be raised per host item per sequential trigger of the queue wait threshold.
Note that this alert will be sent even if AlertOnError is False.
Zero means no alerts of this type will be sent.
Property methods: QueueWaitAlertDisplayToLogical(), QueueWaitAlertGet(), QueueWaitAlertIsValid(), QueueWaitAlertLogicalToDisplay(), QueueWaitAlertNormalize(), QueueWaitAlertSet()
property ReplyCodeActions as %String (MAXLEN = 1000);

A comma-separated list of codes specifying what action this Operation will take on various reply status conditions. The format of the list is:
Types of reply status condition are identified by a specification code:

  • E - Error status returned from message handler
  • E#<statuscode> - Error status returned from message handler has status code equal to <statuscode>
  • E*<text> - Error status returned from message handler contains text string <text>
  • X - there is no reply message at all

The following values for <actions> may be used alone or in combinations:

  • C - Treat the message as Completed OK.
  • W - Log a warning. If no other non-warning <actions> are triggered, the message will be treated as Completed OK.
  • R - Retry the message according to the configured RetryInterval and FailureTimeout; finally Fail unless a different action is also specified. Note this setting is separate from the Retry property.
  • S - Suspend the message, log an error, and move on to try the next message.
  • D - Disable the Operation, log an error and restore the message to the front of the Operation's queue.
  • F - Fail with an error and move on to try the next message from the Operation's queue subject to the Retry property value set in the code. If the Retry property is set in the code then moving on to try the next message will be subject to the configured RetryInterval and FailureTimeout.
An example of a valid ReplyCodeActions specification is 'E#6301=R,E#<Ens>ErrGeneral=RD,E=F'. This specification will result in a retry when error code 6301 is encountered. When error code <Ens>ErrGeneral is encountered, the Operation first retries to send the message until FailureTimeout and then, if the error continues, it disables the Operation instead of failing. Any other errors will cause the Operation to fail processing of the current message and return the error status to the caller, without retrying first unless the property Retry has been set to true by the operation code.

The default behavior is equivalent to 'E=F'. If the Retry property has been set by the Operation code then retrying will be subject to the configured RetryInterval and FailureTimeout.

All codes where <actions> consists of only 'W' (for 'log a Warning') will be evaluated, and a warning will be generated for each matching <code>. Other <code> values will be evaluated in left-to-right order, executing the first matching <code> that has a non-warning <actions> value. As noted in the details for the 'W' flag, an error that only triggers 'W' <actions> will be treated as Completed OK.

Property methods: ReplyCodeActionsDisplayToLogical(), ReplyCodeActionsGet(), ReplyCodeActionsIsValid(), ReplyCodeActionsLogicalToDisplay(), ReplyCodeActionsLogicalToOdbc(), ReplyCodeActionsNormalize(), ReplyCodeActionsSet()
property Retry as %Boolean [ InitialExpression = 0 ];
Set this property to 1 if you want to retry the current message again
Property methods: RetryDisplayToLogical(), RetryGet(), RetryIsValid(), RetryLogicalToDisplay(), RetryNormalize(), RetrySet()
property RetryCount as %Integer [ InitialExpression = 0 ];
how many times have we retried?
Property methods: RetryCountDisplayToLogical(), RetryCountGet(), RetryCountIsValid(), RetryCountLogicalToDisplay(), RetryCountNormalize(), RetryCountSet()
property RetryInterval as %Numeric (MINVAL = 0) [ InitialExpression = 5 ];
How frequently to retry access to the output system
Property methods: RetryIntervalDisplayToLogical(), RetryIntervalGet(), RetryIntervalIsValid(), RetryIntervalLogicalToDisplay(), RetryIntervalNormalize(), RetryIntervalSet()
property SendSuperSession as %Boolean;

Flag whether the %SuperSession property ought to be included in the outbound message.

Including the Super Session in the outbound message depends on the transport mechanism.

InterSystems IRIS supports automatically including the %SuperSession in the HTTP Headers for both the HTTP and SOAP Outbound Adapters based on this setting.

For other transport mechanisms custom code can call the host operation API: IncludeSuperSession()(.tSC) and then use as appropriate the host property value of %SuperSession if IncludeSuperSession API returns true.

The IncludeSuperSession() API returns true if the operation ought to send a super session based on this host setting of SendSuperSession and the %SuperSession property is not empty.

The IncludeSuperSession() API will populate the host property %SuperSession with either a generated Super Session or leave it with the Super Session passed to it with the request.

The IncludeSuperSession() API will return false if either SendSuperSession is false or there was an error generating the super session (tSC will be populated accordingly).

Example use in custom adapter Code:
#dim tSC As %Status = $$$OK
If ..BusinessHost.IncludeSuperSession(.tSC) {
	  code to include ..BusinessHost.%SuperSession in output
	  based on transport mechanism.

See also Host methods GenerateSuperSession() and OnGenerateSuperSession()

Property methods: SendSuperSessionDisplayToLogical(), SendSuperSessionGet(), SendSuperSessionIsValid(), SendSuperSessionLogicalToDisplay(), SendSuperSessionNormalize(), SendSuperSessionSet()
property SuspendMessage as %Boolean [ InitialExpression = 0 ];
Set this property to 1 if you want to mark the current message as "Suspended"
Property methods: SuspendMessageDisplayToLogical(), SuspendMessageGet(), SuspendMessageIsValid(), SuspendMessageLogicalToDisplay(), SuspendMessageNormalize(), SuspendMessageSet()


method DeferResponse(ByRef pToken As %String) as %Status
This method returns the deferred response token, and marks the current message handling to be deferred
classmethod GetMessageList() as %String
method IncludeSuperSession(Output pSC As %Status = $$$OK) as %Boolean
Returns true if have a super session that needs to be included in output.
SendSuperSession setting needs to be true.
%SuperSession will be generated if it is an empty string and SendSuperSession is true.
Returns error status as an output parameter.
Method will return false if %SuperSession is empty string or an error.
method OnError(ByRef pStatus As %Status) as %Boolean
Override this method to provide custom error handling. Return 0 means skip standard AlertOnError behavior.
method OnFailureTimeout(pRequest As %Library.Persistent, Output pResponse As %Library.Persistent, ByRef pSC As %Status) as %Boolean
Override this method to provide custom handling of retry / failure timeout.

Set ..Retry=1 to override normal error return and re-evaluate flag properties.

Return 0 to skip further (default) FailureTimeout processing, 1 to perform default processing.

method OnGetReplyAction(pRequest As %Library.Persistent, ByRef pResponse As %Library.Persistent, ByRef pSC As %Status) as %String
Construct and return an Action string consisting of supported action code letters, based on criteria in the ReplyCodeActions setting value and qualities of the current Request, Response, and Error Status.
method OnKeepalive(pAdapterStatus As %Status) as %Status
This method will be called within KeepaliveInterval of the last return from OnTask() or OnKeepalive(). It is called via the Adapter's OnKeepalive() method, which is called from the Host.OnTask() method; if there is no Adapter there is no keepalive call.
method OnMessage(pRequest As %Library.Persistent, Output pResponse As %Library.Persistent) as %Status
This is the default message handler. All request types not declared in the message map are delivered here
method SendAlert(pAlertRequest As Ens.AlertRequest) as %Status
Use this method to send an alert message
method SendRequestAsync(pTargetDispatchName As %String, pRequest As %Library.Persistent, pDescription As %String = "") as %Status
Use this method to dispatch a business invocation asynchronously
method SendRequestSync(pTargetDispatchName As %String, pRequest As %Library.Persistent, ByRef pResponse As %Library.Persistent, pTimeout As %Numeric = -1, pDescription As %String = "") as %Status
Use this method to dispatch a business invocation synchronously

Inherited Members

Inherited Properties

Inherited Methods


FeedbackOpens in a new tab