Home > Class Reference > ENSLIB namespace > Ens.BusinessOperation
Private  Storage   


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


Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 14 11


This is a Business Operation class.

%AlertStartTime %ConfigName %ConfigQueueName %LastActionTime
%LastHandledTime %LastReportedError %QuitTask %RequestHeader
%SessionId %SuperSession %WarnedLatest %isShadow
Adapter AlertGroups AlertOnError AlertRetryGracePeriod
ArchiveIO BusinessPartner DeferResponse FailureTimeout
IOLogEntry InactivityTimeout NoFailWhileDisconnected QueueCountAlert
QueueWaitAlert ReplyCodeActions Retry RetryCount
RetryInterval SendSuperSession SuspendMessage ThrottleDelay

%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IsA %IsModified %New
%NormalizeObject %ObjectModified %OnClose %OnNew
%OriginalNamespace %PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %SuperSessionSet %ValidateObject AdapterName
AssignOneSetting CloseIOLogEntry DeferResponse EnumerateSettingsClose
EnumerateSettingsExecute EnumerateSettingsFetch GenerateSuperSession GetDeferredResponseToken
GetMessageList GetProductionSettingValue GetProductionSettings GetPropertyConnections
GetSettings GetShadowInstance IncludeSuperSession NewIOLogEntry
OnError OnFailureTimeout OnGenerateSuperSession OnGetConnections
OnGetReplyAction OnInit OnKeepalive OnMessage
OnMonitor OnProductionStart OnProductionStop OnTearDown
QueueName SaveIOLogEntry SendAlert SendDeferredResponse
SendRequestAsync SendRequestSync

Ens.Activity.Operation.Base Ens.Alerting.NotificationOperation Ens.BusinessDuplex
Ens.Enterprise.OperationBase EnsLib.Background.Workflow.Operation EnsLib.DotNetGateway.AbstractOperation
EnsLib.EDI.EDIFACT.Operation.Standard EnsLib.EDI.X12.Operation.Standard EnsLib.EDI.XML.Operation.Standard
EnsLib.FTP.PassthroughOperation EnsLib.File.PassthroughOperation EnsLib.HTTP.GenericOperation
EnsLib.JavaGateway.AbstractOperation EnsLib.LDAP.Operation.Standard EnsLib.MFT.Operation.Passthrough
EnsLib.MQSeries.PassthroughOperation EnsLib.MQTT.Operation.Passthrough EnsLib.PEX.BusinessOperation
EnsLib.Printing.AbstractPrintJobRenderer EnsLib.Printing.AbstractPrinter EnsLib.PubSub.RoutingOperation
EnsLib.PushNotifications.APNS.Operation EnsLib.PushNotifications.GCM.Operation EnsLib.REST.Operation
EnsLib.RecordMap.Batcher EnsLib.RecordMap.Operation.ComplexBatchStandard EnsLib.RecordMap.Operation.Standard
EnsLib.SAP.Operation EnsLib.SOAP.GenericOperation EnsLib.TCP.Framed.PassthroughOperation
EnsLib.TCP.PassthroughOperation EnsLib.Workflow.Operation EnsLib.XML.Object.Operation.Standard
EnsLib.XSLT.Transformer EnsLib.ebXML.Operation.MessageTracker EnsLib.ebXML.Operation.SOAPOperation


• parameter SETTINGS = "ReplyCodeActions,RetryInterval,AlertRetryGracePeriod:Alerting,FailureTimeout,QueueCountAlert:Alerting,QueueWaitAlert:Alerting,SendSuperSession";
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 %RequestHeader as Ens.MessageHeader;
• 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 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 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 NoFailWhileDisconnected as %Boolean;
Suspend counting seconds toward FailureTimeout while disconnected.
Does not apply if FailureTimeout=-1 or StayConnected=0.
• 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 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 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.
  • 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.
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.

The default behavior is 'E=F'. Thus any error status will result in the error being logged and returned to the caller, no retries will be attempted, and the Operation will move on to try the next message from its queue.

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 Retry as %Boolean [ InitialExpression = 0 ];
Set this property to 1 if you want to retry the current message again
• property RetryCount as %Boolean [ InitialExpression = 0 ];
how many times have we retried?
• property RetryInterval as %Numeric(MINVAL=0) [ InitialExpression = 5 ];
How frequently to retry access to the output system
• 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 SuspendMessage as %Boolean [ InitialExpression = 0 ];
Set this property to 1 if you want to mark the current message as "Suspended"


• 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