Implement Inbound Messaging Services

Healthcare enterprises typically operate a number of departmental systems such as ADT, diagnostic departments, pharmacy, and others that may be acquired from multiple vendors. Such systems require messaging services to communicate events and request actions from applications throughout the enterprise.

The two principal components of system messaging are Inbound Messaging Services, described by this section. Note that you can elect to implement inbound messaging services separately or jointly.

To route the message from the source system, an external interface engine that handles HL7 message translation and routing must be implemented for IMP (Inbound Message Processor) to function. Although a single interface engine is typically required, multiple interface engines can be implemented. An interface engine is not included with HDR. However, Oracle B2B/BPEL can be used as an Interface Engine.

In the following chart, the ADT system registers and admits patients. After updating its own database, ADT sends an HL7 message to an interface engine that in turn routes the message to HDR and to other systems within the enterprise. HDR maintains this patient data in a clinical data repository, available to HDR-based applications.

Figure 2-10 Typical Application Topology (IMP)

Messaging Schema

HDR includes messaging schemas for all supported message types. Messaging schema includes the following for each message type:

Schema (XSD Files) for the Payload of the Message Type
Composite Message Schema (XSD File) for each Interaction ID of the Message Type
Model Interchange Files (MIF files) for the Payload of the Message Type

In addition, messaging schema contains a common Vocabulary schema and data type schema for all message types.

The Composite Message Schema (CMS) has three parts: Message Wrapper, Control Act Wrapper, and Payload Reference. If there are three Interaction IDs seeded for the same Payload, there will be three composite message schemas; one for each Interaction ID and all of them will refer to the same Payload.

For samples, refer to the schemas for Lab Result available at the following locations:

Payload Schema for a Message Type (Lab Result)
<HDR_DOMAIN>/config/hdr/message/defs/rim214101/schemas/POLB_MT004000HT01.xsd
Composite Message Schema for Interaction Ids POLB_IN004003, POLB_IN004004 (Lab Result)
<HDR_DOMAIN>/config/hdr/message/defs/rim214101/schemas/POLB_IN004003.xsd

<HDR_DOMAIN>/config/hdr/message/defs/rim214101/schemas/POLB_IN004004.xsd
Common Data Type Schemas
<HDR_DOMAIN>/config/hdr/message/defs/rim214101/coreschemas/datatypes.xsd

<HDR_DOMAIN>/config/hdr/message/defs/rim214101/coreschemas/datatypes-base.xsd
Common Vocabulary Schemas
<HDR_DOMAIN>/config/hdr/message/defs/rim214101/coreschemas/datatypes.xsd

<HDR_DOMAIN>/config/hdr/message/defs/rim214101/coreschemas/datatypes-base.xsd

For more information on message types supported, refer to the Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification.

Acknowledgement Processing

Upon receipt of a message from the sending application (the source of the message), IMP synchronously processes the message into HDR, and returns an Application Acknowledgment (AA), an Application Error (AE), or an Application Reject (AR).

Application Acknowledgement (AA): An AA response indicates that the message was successfully processed and persisted in HDR.
Application Error (AE): An AE response indicates an error reported by HDR, including error information in message content or format (error type code, error detail code, free text). It is the responsibility of the interface engine to determine if the acknowledgement message is returned to the sending system or if the message should be resent to HDR or skipped (abandoning the message). IMP does not support sequence number protocol--the interface engine is responsible for assuring that messages are delivered in order.
Application Reject (AR):An AR response indicates that the message is rejected, for reasons unrelated to its content or format (system or network down, network transmission errors). For most such problems, the receiving system may be able to accept the message at a later time. The sending system or interface engine must decide on an application-specific basis whether the message should be sent again. Ultimately, the AR is resolved to either an AA (upon successful retransmission) or an AE--which thence generates a call to error processing.

The acknowledgement message contains the following XML segments:

Table 2-25 XML Segments in an Acknowledgement Message

Components	XPATH	Sample values
Acknowledgement Type	MCCI_MT002300HT01.Message/ acknowledgement/typeCode/@code	<typeCode code="AA"/> , <typeCode code="AE"/>, <typeCode code="AR"/>
Acknowledgement Detail Code	MCCI_MT002300HT01.Message/acknowledgement/ acknowledgementDetail/ code/@code	<code code="NS250" codeSystemName="AcknowledgementDetailCode"/>
Acknowledgement Error Text	MCCI_MT002300HT01.Message/acknowledgement/ acknowledgementDetail/ text	<text mediaType="text/plain" encoding="TXT"> Application: CTB, Message Name: HDR_MS_INVALID_PROCESS_MD_CD. Tokens: PROCESSING_MODE_CODE = T1; </text>
Acknowledgement Error Location	MCCI_MT002300HT01.Message/acknowledgement/ acknowledgementDetail/location	<location> HDR_MS_IMP_EXCEPTION_LOCATION2 :Error occurred while processing XML data located at line 6, column 30. XPATH: /PRPA_IN400000[1] COMPLEX_TYPE: MCCI_MT000100HT04.Message</location>
HDR Error Code	MCCI_MT002300HT01.Message/acknowledgement/ acknowledgementDetail/text	CTB_MS_INVALID_PROCESS_MD_CD
Responder Information	MCCI_MT002300HT01.Message/sender/device/id	<sender type="CommunicationFunction"> <typeCode code="SND"/> <device type="Device" classCode="DEV" determinerCode="INSTANCE"> <id root="9.989898.5.100" extension="ORG1000"/> <asAgent type="RoleHeir" classCode="AGNT"> <representedOrganization type="Organization" classCode="ORG" determinerCode="INSTANCE"> <id root="9.989898.5.100" extension="ORG1000"/> </representedOrganization> </asAgent> </device> </sender>

Sender Configuration

Before processing a message, the message type must be configured for the sender. IMP extracts Sender, Receiver, and Interaction Id available in the message, and picks up the associated side-effect configuration. If Interaction ID is not configured for the Sender and Receiver, IMP rejects the message.

Based on the side-effect configuration, IMP sets the reference modifier on RIM objects available in the message. If a particular RIM object is not configured for side-effect, IMP defaults the value of reference modifier for the RIM object to MUST_EXIST. There are certain side-effect rules in IMP that influences the value of reference modifier of a RIM Object. These rules are illustrated in Oracle Healthcare Data Repository Programmer's Guide.

Message Validation

In addition to being compliant with messaging schema, IMP imposes certain validations on messages before processing the message. Major validations that affect messages are described in this section.

Identified Object Processing

All RIM objects containing ids are identified objects. If a message instance contains repeating objects with same ids, IMP merges the information of repeating objects and persists union of data from different instances into HDR Repository. This is called Identified Object Processing. If the repeating objects in the message contain inconsistent information, IMP rejects the message. For example, if the age of a particular person (having same II) has different values at different segments of the message, IMP rejects the message. For information on complete set of rules to merge information of repeating objects, refer to the Oracle Healthcare Data Repository Programmer's Guide and Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification.

Media Type and MIME Type Validation for CDA Messages

For CDA Message Types, IMP supports only certain Media Type and MIME Type. Refer to the CDA Message Type section of the Oracle Healthcare Data Repository Message Conformance Specification V6.1.

Master Catalog Validation

Master Catalog entries must exist in HDR Repository for all Acts, Entities, and Roles submitted to HDR for persistence.

Vocabulary Validation

Code System Names used in the message must be loaded into ETS and the Codes used should be part of Coding Scheme.

State Transition Validation

All Acts, Entities, and Roles submitted to HDR for persistence is subjected to Generic State Transition validation. The Focal object in the message is subjected to focal class state transition.

Immutable Attributes Validation

An update message cannot modify values of structural attributes and code (example, act.ClassCode) of an already persisted object.

RIM Service Validation

Every message is persisted as a control act graph in HDR Repository and subjected to the validations done by RIM Persistence Service.

Messaging Metadata

To process a message, IMP needs the following RMIM schematic information about the message elements:

Name of RIM Foundation Class of the RIM Object available in the message element.
Type of RIM Association.
Constrained RMIM Data Type of the attribute.
If the association is a choice.

The RMIM schematic information is not available in the schemas for message types, but present in the MIF files for the same message type. The information is extracted from the MIF file and loaded into the database after installing HDR. This information is known as Messaging Metadata.

To load Messaging Metadata, use ConcurrentProgService.loadMessagingMetadata() API.

Profile Options and System Properties

Use the CTB: Store Incoming Message profile option to indicate whether the incoming message has to be stored or not. The valid values are Y and N. If the value is Y, the incoming message is stored in the submission unit table. If the value is N, the incoming message is not stored.

The following system properties impacts behavior of the IMP engine:

Table 2-26 IMP System Properties

Property Name	Valid Values	Description
IgnoreUnrecognizedElements	Y or N	With value 'N' throws an exception when an unrecognized RIM attribute is encountered. With 'Y', just skips it. If N, IMP throws an exception when an unrecognized RIM attribute is encounters. If Y, IMP skips the validation. The default value is N.
IMP_NONDESTRUCTIVE_MODE	Y or N	If Y, IMP rollbacks all transactions and does not update the audit log. The default value is N.
IMP_BUNDLED_MODE	Y or N	If Y, IMP collects all non-runtime exceptions, and continues processing. If N, each exception aborts processing immediately. The default value is N.

Configuring Interactions

IMP extracts Interaction Id and Trigger Event Code from the incoming message and checks whether it is configured or not. The following table lists the location of the parameters in the message

Table 2-28 Location of the Parameters in the Message

Parameter	XPath
Interaction Id	Top Level Element in the message. Example, PRPA_IN400000
Trigger Event Code	PRPA_IN400000/controlActProcess/code/@code

Interaction Ids for all supported message types are seeded. Refer to the Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification for the list of seeded interaction ids. You can also configure new Interactions Id for supported messages. Use the Interactions window to configure new Interaction Id. For more information on the Interactions window, refer to Oracle Healthcare Data Repository User Interface Guide.

When you configure a new Interaction Id, an Interaction schema is generated by the Healthcare Data Repository User Interface and stored at the following location with the name of {InteractionId}.xsd::

<HDR_DOMAIN>/config/hdr/message/defs/customSchema/newMessageType/interaction.

Configuring Sender, Sender Interaction, and Side Effect

IMP extracts the following information (in the table) from the message and validates them for the configuration:

Table 2-29 Information Extracted and Validated by IMP

Parameter	XPath
Interaction Id	Top Level Element in the message. Example, PRPA_IN400000
Sender Root	PRPA_IN400000/sender/device/ id/@root
Sender Extension	PRPA_IN400000/sender/device/id/@extension
Receiver Root	PRPA_IN400000/receiver/device/asAgent/representedOrganization /id/@root
Receiver Extension	PRPA_IN400000/receiver/device/as Agent/representedOrganization/id/@extension
Trigger Event Code	PRPA_IN400000/controlActProcess/code/@code

If the Sender Root and Extension and Receiver Root and Extension is not configured, IMP rejects the message. This configuration thus controls a valid sender and HDR enterprises authorized to send messages. This is called the Sender Configuration.

Important: You must only use Organization's external II while creating sender configuration. You must not use any of the Internal IIs that are automatically generated in HDR.

Upon validation of the Sender Configuration, IMP uses its configuration to determine if the Interaction Id is valid for the Sender Configuration. If it is not configured for that Sender Configuration, IMP rejects the message. This configuration thus controls which types of Interaction Id a sender is permitted to send to a receiver. This is called the Sender Interaction Configuration.

Upon validation of the Sender Configuration and Sender Interaction Configuration combination, IMP processes the message payload. The focal object is created or updated in the HDR Repository. However, for non-focal objects, IMP inspects its side effect configuration to determine its behavior. You can configure IMP to let each non-focal object type create or not create the object if it is not present in the repository, and to update or overlay or not update or overlay the object if it is present in the repository. This configuration of side effects is called the Side Effect Configuration.

Use the IMPConfigAdminIntrService to configure sender and side effects.

Invoke Inbound Messaging Services

Reference

Oracle Healthcare Data Repository Javadoc
Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification

The following table lists the principal IMP service and methods:

Table 2-30 Service and Methods: IMP

Level	Detail
Package	oracle.hsgbu.hdr.message.improcessor
Class	IMPService
Methods	processMessage
Class	RawIMPService
Methods	processMessage
Class	Result
Methods	getResponseXML getStatus getControlActId getTriggerEvent

This is an API-based implementation procedure.

Navigation

This is an API-based implementation procedure.

Steps

Use the Service Locator to access the IMP Service.

Note:
RawIMPService is implemented as a container-managed transactions (CMT) bean, and does not create SubmissionUnit. Use RawIMPService if you want to use the Java Transaction API (JTA) support of IMP.
Use the processMessage method with an HDR-compliant message (see following Note) as a parameter to invoke message processing services; a Result object is returned.
Use the following methods to inspect the result of processing the message:
- getResponseXML
- getStatus

Note:

IMP supports XML formatted inbound messages that conform to the HL7 version 3 messaging standard. The messages must conform to the messaging schema for the message types supported in HDR. The schemas for all supported message type is available at the following location:

<HDR_DOMAIN>/config/hdr/messge/defs/rim214101/schemas

The list of supported message types is provided in Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification. Using Messaging Tool Kit, additional message types can be supported. For more information, refer to Oracle Healthcare Data Repository Messaging Tool Kit User Guide.

Task-Step	Description	Optional?	Interface
9-1	Configuring Interactions	Yes	API
9-2	Configuring Sender, Sender Interaction, and Side Effect	No	API
9-3	Invoke Inbound Messaging Services	Yes	API