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)
![Typical Application Topology (IMP) Typical Application Topology (IMP)](img/ctb01101.gif)
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. |
See also:
- Oracle Healthcare Data Repository Programmer's Guide
- Oracle Healthcare Data Repository Javadoc
- Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification
Prerequisites
- Implement HDR Object Identifiers: The following HDR Object Identifiers must be configured:
- INTERNAL_ROOT
- CDA_MMID
- Implement Master Catalog and Focal Class State Transitions: Master Catalog must be implemented before assigning them in Sender and Receiver configuration, and every act, role and entity referenced in an incoming message must have a pre-existing entry in a Master Catalog table.
- Enterprise Terminology Services: Terminologies used in messages should be loaded.
Inbound messages can contain coded data types that include a codeSystemName, and code but no codeSystemVersion. In the absence of a version, IMP searches for the code in the default version of the terminology as configured in ETS. If no default version is found the message is rejected. Configuring default versions is critical because some terminologies may reuse codes across versions. To use the concept with the intended meaning, ETS must know explicitly which version to use for a certain terminology.
Procedures:
The following chart provides an overview of the implementation process for Inbound Messaging Services:
Figure 2-11 Implementation Process: Inbound Messaging Services
![Implementation Process: Inbound Messaging Services Implementation Process: Inbound Messaging Services](img/ctb30006.gif)
To implement Inbound Messaging Services, refer to the following procedure table:
Table 2-27 HDR Implementation Procedures: Inbound Messaging Services
Task-Step |
Description |
Optional? |
Interface |
9-1 |
Yes |
API |
|
9-2 |
No |
API |
|
9-3 |
Yes |
API |
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.
See also:
- Oracle Healthcare Data Repository Programmer's Guide, for more information on Side Effect Processing Rules.
- Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification for a list of side effect configuration records required for each message type.
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 |
|
Class |
RawIMPService |
Methods |
|
Class |
Result |
Methods |
|
Login
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 createSubmissionUnit
. UseRawIMPService
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.
See also:
- Oracle Healthcare Data Repository HL7 Version 3 Conformance Specification, for information about message types supported by IMP.
- Oracle Healthcare Data Repository Messaging Tool Kit User Guide.
- Oracle Healthcare Data Repository Programmer's Guide.