Skip to main content

EnsLib.HL7.Service.Standard

abstract class EnsLib.HL7.Service.Standard extends Ens.BusinessService, EnsLib.HL7.Util.IOFraming, EnsLib.EDI.ServiceInterface

Property Inventory

Method Inventory

Parameters

parameter DOCCLASS = EnsLib.HL7.Message;
parameter IndexACKs = 0;
[Deprecated] The SaveReplies property/setting should be used instead. Index OK ACKs if IndexReplies is also true and SearchTable class is given.
parameter IndexReplies = 0;
[Deprecated] The SaveReplies property/setting should be used instead. If SearchTableClass is set, use it to index any replies (including OK ACKs unless IndexACKs=false).
parameter SETTINGS = TargetConfigNames:Basic:selector?multiSelect=1&context={Ens.ContextSearch/ProductionItems?targets=1&productionName=@productionId},SearchTableClass::selector?context={Ens.ContextSearch/SearchTableClasses?host=EnsLib.HL7.Service.Standard},LocalFacilityApplication,Framing:Connection:selector?context={Ens.ContextSearch/getDisplayList?host=@currHostId&prop=Framing},AckMode,UseAckCommitCodes,IgnoreInboundAck,AddNackERR,NackErrorCode,BatchHandling,MessageSchemaCategory:Basic:selector?context={Ens.ContextSearch/SchemaCategories?host=EnsLib.HL7.Service.Standard},DefCharEncoding::selector?context={Ens.ContextSearch/CharacterSets},DocTypeResolution,SaveReplies;
Inherited description: List of properties can be set as settings in the configuration file format is a comma separated list of property names
parameter UseOriginalControlId = 1;
In Reply/ACK messages, use the ControlId of the message we are replying to, rather than constructing a new unique one

Properties

property AckMode as %String (DISPLAYLIST = ",Never,Immediate,Application,MSH-determined,Byte", VALUELIST = ",Never,Immed,App,Msh,Byte") [ InitialExpression = "Immed" , Required ];
Control of ACK handling. The options are:
  • Never: Do not send back any ACK.
  • Immediate: Send back (commit) ACK reply message immediately upon receipt of the inbound message.
  • Application: If message passes validation, wait for ACK from target config item and forward it back when it arrives.
  • MSH-determined: Send back ACK reply messages as requested in the MSH header of the incoming message.
  • Byte: Send back an immediate single ACK-code byte instead of an ACK message. Byte ASCII code 6 = 'OK', ASCII code 21 = 'Error'
Property methods: AckModeDisplayToLogical(), AckModeGet(), AckModeIsValid(), AckModeLogicalToDisplay(), AckModeLogicalToOdbc(), AckModeNormalize(), AckModeSet()
property AddNackERR as %Boolean;
Add ERR error code segment when generating NACK messages; otherwise do not embed internal error state information in NACK messages
Property methods: AddNackERRDisplayToLogical(), AddNackERRGet(), AddNackERRIsValid(), AddNackERRLogicalToDisplay(), AddNackERRNormalize(), AddNackERRSet()
property BatchHandling as %String (DISPLAYLIST = ",Whole Batch,Single-Session Batch,Multi-Session Batch,Individual", VALUELIST = ",Whole,1Session,Batch,Indiv") [ InitialExpression = "1Session" , Required ];
How to treat received batch documents:
  • Whole Batch: Don't process child documents individually; accumulate and send the whole batch as one composite document.
  • Single-Session Batch: Forward all documents in the batch as part of a single session, including final parent document objects containing batch header and trailer segments.
  • Multi-Session Batch: Forward each document in the batch in its own session, followed by final parent document objects containing the batch header and trailer segments.
  • Individual: Forward each child document in the batch in its own session; do not forward parent batch document objects.
Property methods: BatchHandlingDisplayToLogical(), BatchHandlingGet(), BatchHandlingIsValid(), BatchHandlingLogicalToDisplay(), BatchHandlingLogicalToOdbc(), BatchHandlingNormalize(), BatchHandlingSet()
property DocTypeResolution as %String (DISPLAYLIST = ",Standard,Ignore 9.3,Use 9.3,Literal", VALUELIST = ",Std,Ign,Use,Lit") [ InitialExpression = "Std" , Required ];
How to resolve a DocType based on the message type from MSH:9. The options are:
  • Standard: Combine the effective MessageSchemaCategory value with a message structure name looked up for the MSH:9 message type value in the corresponding schema category. This is the default.
  • Ignore 9.3: Like 'Standard' but if MSH:9 has 3 or more pieces, ignore the additional ones. The standard behavior is to use piece 3 as part of the type name if it has no sub-pieces because some schemas contain 3-part type names.
  • Use 9.3: Like 'Standard' but if MSH:9 has 3 or more pieces, use the additional piece as the literal name of the document structure within the applicable schema category. Use with caution because messages may arrive with MSH:9.3 values for which no structure is present in the chosen schema category.
  • Literal: Combine the effective MessageSchemaCategory value with the literal MSH:9 message type value interpreted as the name of a message structure. Use only with custom schemas where every message type has a corresponding structure definition.
Property methods: DocTypeResolutionDisplayToLogical(), DocTypeResolutionGet(), DocTypeResolutionIsValid(), DocTypeResolutionLogicalToDisplay(), DocTypeResolutionLogicalToOdbc(), DocTypeResolutionNormalize(), DocTypeResolutionSet()
property Framing as %String (DISPLAYLIST = ",Flexible,Flexible!,None,MLLP,MLLP11/28,AsciiLF,AsciiCR,Ascii11,Ascii11/28,LLP") [ InitialExpression = "Flexible" ];
HL7 inbound message framing protocol. The options are:
  • Flexible: Determine framing style from the content of received data of each message received.
  • Flexible!: Determine framing style from the content of received data of the first message and require subsequent messages to have that same framing style.
  • None: No framing - Each line that begins with 'MSH' is the start of a new message.
  • MLLP: Minimal Lower Level Protocol - Frame each HL7 message with ASCII code 11 prefix and ASCII code 28,13 suffix.
  • MLLPN/M: Minimal Lower Level Protocol - Frame each HL7 message with ASCII code N prefix, and ASCII code M suffix followed by an additional ASCII code 13.
  • AsciiLF: Frame messages with ASCII code 10 (Line Feed) separating each message from the subsequent one.
  • AsciiCR: Frame messages with an extra ASCII code 13 (Carriage Return) separating each message from the subsequent one.
  • AsciiM: Frame messages with ASCII code M suffix character(s) separating each message from the subsequent one.
  • AsciiN/M: Frame messages with ASCII code N prefix character(s) before each message and ASCII code M suffix character(s), but no trailing ASCII code 13 as in MLLPN/M.
  • LLP: Lower Level Protocol - (Obsolete) Frame each HL7 message in a redundant checksum block.

Notes:
- ASCII code N is a sequence of one or more characters represented by their ASCII code, separated by comma in case of more than one character.
- All ASCII codes should be given in decimal.
- ASCII code 120 (character 'x') is not allowed as a framing character.

Property methods: FramingDisplayToLogical(), FramingGet(), FramingIsValid(), FramingLogicalToDisplay(), FramingLogicalToOdbc(), FramingNormalize(), FramingSet()
property IgnoreInboundAck as %Boolean [ InitialExpression = 1 ];
Ignore inbound ACK messages to avoid ACK feedback loop.
Property methods: IgnoreInboundAckDisplayToLogical(), IgnoreInboundAckGet(), IgnoreInboundAckIsValid(), IgnoreInboundAckLogicalToDisplay(), IgnoreInboundAckNormalize(), IgnoreInboundAckSet()
property ImmediateByteAck as %Boolean;
In addition to forwarding a full ACK message according to the AckMode setting, return immediate 1-byte ACKs on this Service's TCP connection.
Property methods: ImmediateByteAckDisplayToLogical(), ImmediateByteAckGet(), ImmediateByteAckIsValid(), ImmediateByteAckLogicalToDisplay(), ImmediateByteAckNormalize(), ImmediateByteAckSet()
property LocalFacilityApplication as %String [ InitialExpression = "ISC:EnsembleHL7" ];
Colon-separated LocalFacility:LocalApplication codes representing this (receiving) facility and application
These are used in constructing reply ACK message headers as SendingFacility and SendApplication.
The '@' symbol represents using the corresponding field from the incoming message.
If your ID must contain a literal @ symbol, escape it with backslash: '\@'
Property methods: LocalFacilityApplicationDisplayToLogical(), LocalFacilityApplicationGet(), LocalFacilityApplicationIsValid(), LocalFacilityApplicationLogicalToDisplay(), LocalFacilityApplicationLogicalToOdbc(), LocalFacilityApplicationNormalize(), LocalFacilityApplicationSet()
property MessageSchemaCategory as %String (MAXLEN = 1000);
Category to apply to incoming message types to produce a complete DocType specification.

Combines with the document type Name (MSH:9) to produce a MessageType specification which is then used to look up a MessageStructure/DocType in the MessageTypes section of the given HL7 schema category.

This setting may also contain multiple comma-separated type Names followed by = and then a DocTypeCategory or full DocType value to apply to HL7 messages containing that type Name.

A trailing asterisk (*) at the end of a given partial type Name will match any types with that beginning part.

For example: MessageSchemaCategory='2.3.1, ADT_*=2.5, BAR_P10=2.4, ORM_O01_6=2.4:RDE_O01'
Note that a DocType assignment may be needed for Validation or SearchTableClass indexing.

Property methods: MessageSchemaCategoryDisplayToLogical(), MessageSchemaCategoryGet(), MessageSchemaCategoryIsValid(), MessageSchemaCategoryLogicalToDisplay(), MessageSchemaCategoryLogicalToOdbc(), MessageSchemaCategoryNormalize(), MessageSchemaCategorySet()
property NackErrorCode as %String (VALUELIST = ",ContentE,ContentR,AllE,AllR") [ InitialExpression = "ContentE" ];
Controls the error code in MSA:1 of the NACK message this service generates when there is an error processing the incoming message.

The default 'ContentE' behavior is to return code 'E' for errors with the message content, and code 'R' for system errors encountered within Ensemble while attempting to process the message.

This distinction is important because system errors are expected to be solved so that if the remote client tries again at a later time they may not occur, while message content & validation errors are expected to require correction at the source and not to be worth retrying in the same form.

However some client systems may expect or require a different error behavior. Therefore 3 additional behaviors are offered. The 4 behaviors are as follows:
  • ContentE = Use MSA error code 'E' to report errors in message content and code 'R' to reject due to (retryable) system errors.
  • ContentR = Return 'R' for content errors, 'E' for system errors.
  • AllE = Return 'E' for all content and system errors.
  • AllR = Return 'R' for all content and system errors.

Earlier versions of Ensemble used the behavior 'ContentR' exclusively.

Property methods: NackErrorCodeDisplayToLogical(), NackErrorCodeGet(), NackErrorCodeIsValid(), NackErrorCodeLogicalToDisplay(), NackErrorCodeLogicalToOdbc(), NackErrorCodeNormalize(), NackErrorCodeSet()
property NoBatchReply as %Boolean [ InitialExpression = 0 ];
Send individual ACK reply documents for messages in a batch, rather than constructing a batch wrapper for the replies.
Property methods: NoBatchReplyDisplayToLogical(), NoBatchReplyGet(), NoBatchReplyIsValid(), NoBatchReplyLogicalToDisplay(), NoBatchReplyNormalize(), NoBatchReplySet()
property QuitOnError as %Boolean [ InitialExpression = 0 ];
Stop processing a batch document if an error occurs. Otherwise accumulate all errors and report them as a group.
Property methods: QuitOnErrorDisplayToLogical(), QuitOnErrorGet(), QuitOnErrorIsValid(), QuitOnErrorLogicalToDisplay(), QuitOnErrorNormalize(), QuitOnErrorSet()
property SaveReplies as %String (VALUELIST = ",None,NotOKs,All,IndexNotOKs,IndexAll") [ InitialExpression = $select(..#IndexReplies: "Index"_$select(..#IndexACKs: "All", 1: "NotOKs"), 1: "None") ];
Save a copy of reply messages sent back to the remote system. Also optionally index them using the configured SearchTableClass, if any. The options for this setting are as follows:
  • None: Don't save or index any reply messages. This is the default behavior, unless IndexReplies or IndexACKs has been overridden in this class.
  • NotOKs: Save replies that are not a simple OK ACK message, e.g. error NACKS and query responses.
  • All: Save a copy of all reply messages sent back to the remote system.
  • IndexNotOKs: Save replies that are not a simple OK ACK message and index them using the configured SearchTable.
  • IndexAll: Save a copy of all reply messages and index them using the configured SearchTable.
Property methods: SaveRepliesDisplayToLogical(), SaveRepliesGet(), SaveRepliesIsValid(), SaveRepliesLogicalToDisplay(), SaveRepliesLogicalToOdbc(), SaveRepliesNormalize(), SaveRepliesSet()
property SearchTableClass as %String (MAXLEN = 128) [ InitialExpression = "EnsLib.HL7.SearchTable" ];
Store a set of searchable properties associated with each HL7 message processed.
These records will be stored in the named SearchTable class, if any.
Property methods: SearchTableClassDisplayToLogical(), SearchTableClassGet(), SearchTableClassIsValid(), SearchTableClassLogicalToDisplay(), SearchTableClassLogicalToOdbc(), SearchTableClassNormalize(), SearchTableClassSet()
property TargetConfigNames as %String (MAXLEN = 2000);
Configuration item(s) to which to send messages
Property methods: TargetConfigNamesDisplayToLogical(), TargetConfigNamesGet(), TargetConfigNamesIsValid(), TargetConfigNamesLogicalToDisplay(), TargetConfigNamesLogicalToOdbc(), TargetConfigNamesNormalize(), TargetConfigNamesSet()
property UseAckCommitCodes as %Boolean [ InitialExpression = 1 ];
If 'true' and the HL7 message VersionID is 2.3 or higher, use the 'enhanced-mode' ACK 'Commit' codes ('Cx') in MSA:1 ('AcknowledgmentCode'). (Otherwise use the legacy-mode 'Ax' codes.)
Property methods: UseAckCommitCodesDisplayToLogical(), UseAckCommitCodesGet(), UseAckCommitCodesIsValid(), UseAckCommitCodesLogicalToDisplay(), UseAckCommitCodesNormalize(), UseAckCommitCodesSet()
property Validation as %String;
Comma-separated string specifying types of validation to perform. Make it a setting in your subclass if you override OnValidate() and need to provide options.
Property methods: ValidationDisplayToLogical(), ValidationGet(), ValidationIsValid(), ValidationLogicalToDisplay(), ValidationLogicalToOdbc(), ValidationNormalize(), ValidationSet()

Methods

classmethod GetRequestClassList() as %String
classmethod GetResponseClassList(pRequest As %String = "") as %String
method GetSegmentTerminator() as %String
Return the segment terminator string that the Parser and the document.ImportFromIOStream() method will use.
method IOLogDiscard(pSC As %Status, pNote As %String, pDiscard As %GlobalCharacterStream)
Add discarded characters to IO Archive.
method OnConstructBatchReply(Output pReplyDoc As EnsLib.EDI.Document, pOriginalDoc As EnsLib.EDI.Document, ByRef pChildArray, ByRef pSC As %Status, pEarlyAck As %Boolean) as %Status
Override this method to construct a customized batch reply document. Inputs are the original document and the child reply array and the status code that the framework produced in processing the original document.
If you construct a non-HL7 object it must still have a property called 'Envelope'. Piece:2 of this value will be written verbatim.
method OnConstructReply(Output pReplyDoc As EnsLib.EDI.Document, pOriginalDoc As EnsLib.EDI.Document, ByRef pReplyCode As %String, ByRef pSC As %Status, pEarlyAck As %Boolean) as %Status
Override this method to construct a customized reply document. Inputs are the original document and the reply code and the status code that the framework produced in processing the original document. If you change the status code but do not construct a reply document, the framework will use the new value to construct a standard reply document.
If you construct a non-HL7 object it must still have a property called 'Envelope'. Piece:2 of this value will be written verbatim.
method OnDocumentEnd(pDocument As EnsLib.EDI.Document, pSource As %String, pStatus As %Status) as %Status
Callbacks from Parser: Called by the Parser at the end of a document
classmethod OnGetConnections(Output pArray As %String, pItem As Ens.Config.Item)
Return an array of connections for drawing lines on the config diagram.
method OnInboundAck(pDoc As EnsLib.EDI.Document, pMSH As EnsLib.HL7.Segment, ByRef pSC As %Status) as %Boolean
Override this method to implement your own custom method for handling an incoming ACK Message. Returning nonzero means you are handling it and the normal framework should ignore it.
method OnInit() as %Status
Inherited description: This user callback method is called via initConfig() from %OnNew() or in the case of SOAP Services from OnPreSOAP()
method OnProcessInput(pDocIn As %Library.RegisteredObject, Output pDocOut As %Library.RegisteredObject, ByRef pHint As %Library.String) as %Status
Note: pDocIn is not declared as EnsLib.HL7.Message so that subclasses can handle other types and transform them before calling ##super().
method OnResolveDocType(pDoc As EnsLib.EDI.Document, ByRef pDocType As %String) as %Boolean
Override this method to implement your own custom method for resolving the DocType of an incoming message. Returning nonzero means you are overriding the framework's standard DocType resolution.
method OnValidate(pDoc As EnsLib.EDI.Document, pValSpec As %String, Output pStatus As %Status) as %Boolean
Override this method to implement your own custom method for validating an incoming Document. Return non-zero to prevent default validation of the message (if any).
method SendEarlyReply(pReplyDocument As EnsLib.EDI.Document, pOriginalDoc As EnsLib.EDI.Document) as %Status
method SendReply(pReplyDocument As EnsLib.EDI.Document, pOriginalDoc As EnsLib.EDI.Document) as %Status
method constructBatchReply(pOriginalDoc As EnsLib.EDI.Document, ByRef pChildArray, ByRef pSC As %Status, pEarlyAck As %Boolean) as EnsLib.EDI.Document
method constructReply(pOriginalDoc As EnsLib.EDI.Document, pReplyCode As %String, ByRef pSC As %Status, pEarlyAck As %Integer) as EnsLib.EDI.Document
method getReplyCode(pMSH As EnsLib.HL7.Segment, pSC As %Status, pSCVal As %Status, pAppACK As %Boolean) as %String
pAppAck=0 means 'Immediate' reply; =-1 means 'Immediate Commit Ack'; =1 means 'Application' reply. Return empty string if no ACK needed for the specified mode, or the code for the appropriate type of reply.
method reportReply(pOriginalDoc As EnsLib.EDI.Document, pReplyCode As %String, ByRef pSC As %Status, pEarlyAck As %Integer = 0) as EnsLib.EDI.Document
pEarlyAck'=0 means early (commit/immediate) ACK; <0 means Byte ACK.
method resolveAndIndex(pDoc As EnsLib.HL7.Message, pMSH As EnsLib.HL7.Segment) as %Status
Accept only specified document names; resolve DocType and perform requested validation if any.
method resolveDocType(pDoc As EnsLib.HL7.Message, pMSH As EnsLib.HL7.Segment = $$$NULLOREF) as %String
Return the DocType that this service will assign to this document.
method standardOnProcessInput(pDocIn As EnsLib.HL7.Message, Output pDocOut As EnsLib.HL7.Message) as %Status

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab