Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [Ens] >  [BusinessOperation]
Private  Storage   

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

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 15 17


Summary

This is a Business Operation class.

Properties
%ActionHint %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

Methods
%%OIDGet %AddToSaveSet %BindExport %BuildObjectGraph
%ClassIsLatestVersion %ClassName %Close %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IncrementCount %IsA %IsModified
%New %NormalizeObject %ObjectModified %OnClose
%OnNew %OriginalNamespace %PackageName %RemoveFromSaveSet
%SerializeObject %SetModified %SuperSessionSet %ValidateObject
AdapterName AssignOneSetting CloseIOLogEntry DeferResponse
EnumerateSettingsClose EnumerateSettingsExecute EnumerateSettingsFetch EvalInitialExpression
GenerateSuperSession GetDeferredResponseToken GetMessageList GetProductionSettingValue
GetProductionSettings GetPropertyConnections GetRequestClassList GetResponseClassList
GetSettings GetShadowInstance IncludeSuperSession MessageHandler
MessageHeaderHandler NewIOLogEntry OnError OnFailureTimeout
OnGenerateSuperSession OnGetConnections OnGetReplyAction OnInit
OnKeepalive OnMessage OnMonitor OnProductionStart
OnProductionStop OnTask OnTearDown QueueName
SaveIOLogEntry SendAlert SendDeferredResponse SendRequestAsync
SendRequestSync SendRequestSyncMultiple acceptRequestAsync acceptRequestSync
doReplyAction finalReplyAction findCachedObject initConfig
inprocRequest makeConnections queueRequestAsync queueRequestSync

Subclasses
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.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

Parameters

• 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

Properties

• property %ActionHint  [ MultiDimensional ];
Subclasses can store hint values here for use in determining what ReplyCodeAction to apply
• 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:
<code>=<actions>,(<code>,<code>)=<actions>,...
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"

Methods

• 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
• classmethod GetRequestClassList() as %String
Return a collection in $List format of all Request classes found in OnMessage and in the Message Map method signatures
• classmethod GetResponseClassList(pRequest As %String = "") as %String
Return a collection in $List format of all Response classes found in OnMessage and in the Message Map method signatures
• 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 MessageHandler(pRequest As %Library.Persistent, Output pResponse As %Library.Persistent) as %Status
This method dispatches requests to the methods according to the message map
• method MessageHeaderHandler(pRequestHeader As Ens.MessageHeader, Output pResponseHeader As Ens.MessageHeader) as %Status
• 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
• method doReplyAction(pAction As %String, pRequest As %Library.Persistent, pResponse As %Library.Persistent, ByRef pSC As %Status) as %Status
Do the specified action for taking care of the message currently being processed
• method finalReplyAction(pAction As %String, pSC As %Status, pFixError As %Boolean) as %String
Do the action specified for when all configured retries have been exhausted


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.