This chapter provides information about the document protocols and message types supported by Oracle SOA Suite for healthcare integration, and describes how to work with document definitions in the healthcare integration user interface.
This chapter contains the following topics:
Oracle SOA Suite for healthcare integration supports the following document protocols:
Custom
HL7 V2.x
Figure 3-1 displays the document protocols supported in Oracle SOA Suite for healthcare integration.
Figure 3-1 Oracle SOA Suite for healthcare integration Document Protocols
As part of the document definition, you provide the document guideline files, which are typically created in Oracle Document Editor. (For Custom documents, you cannot use Oracle Document Editor and validation of documents is also not possible.) If validation is enabled, then, at run time, the payload must conform to the document definition file type you use.
You can think of a document protocol as a hierarchy, as shown in Figure 3-2.
A document protocol can consist of multiple document protocol versions. A document protocol version can consist of multiple document types. A document type can consist of multiple document definitions. Typically, you start with one document definition and customize it for different endpoints.
Figure 3-3 shows a document protocol hierarchy as it applies to HL7 V2.3.1.
In the Oracle SOA Suite for healthcare integration user interface, as you create a document definition, the document protocol hierarchy is reflected in the definition:
DocumentProtocol—Version—DocumentType—DocumentDefinitionName
Example 3-1 shows the hierarchy reflected in the definition for an HL7 document.
Oracle SOA Suite for healthcare integration supports custom document protocols to create documents needed for proprietary transactions. With XML messages, you have the advantage of schema enforcement (XSDs).
With non-XML messages, you can create endpoints for specific message types.
When creating a Custom document, you specify rules to identify the incoming document. For XML documents, specify an XPath expression or an XPath expression and a value, which is the expected result of the expression.
For non-XML documents such as a flat file, you can specify Identification Start Position, End Position, and Identification Value.
No parameters need to be set when you create the document version for a Custom document.
When you create a Custom document definition (see Section 3.4, "Creating Document Definitions" for more information on creating document definitions), select the identification type—XML or Flat, and set parameters in the tabbed areas. Figure 3-4 shows the document definition parameters for an XML-type Custom document.
Figure 3-4 Document Definition Parameters for an XML-Type Custom Document
Figure 3-5 shows the document definition parameters for a flat-file Custom document.
Figure 3-5 Document Definition Parameters for a Flat-FIle Custom Document
Table 3-1 describes the document definition parameters for a Custom document.
Table 3-1 Document Definition Parameters for a Custom Document
Parameter | Description |
---|---|
XML Tab |
(Available if XML is selected from Identification Type) |
Locates a node in the XML payload |
|
Provides the value to match in the node identified by the Identification Expression. If the values match, then the document is successfully identified. If the value is left blank, then Oracle SOA Suite for healthcare integration checks for the existence of the node and the document is successfully identified. |
|
Select from None, Both, Inbound, or Outbound. |
|
Routing Tab |
- |
Document Routing ID |
Sets the consumer name to the back-end application |
XPath Tab |
See Section 3.2.2.1, "How to Configure the XPath Expression for a Custom XML Document." |
The XML XPath name for retrieving the value from the payload |
|
The XML XPath expression for retrieving the value from the payload. |
|
The XML XPath name for retrieving the value from the payload. |
|
The XML XPath expression for retrieving the value from the payload. |
|
The XML XPath name for retrieving the value from the payload. |
|
The XML XPath expression for retrieving the value from the payload. |
|
Correlation Tab |
- |
The name of the correlation property for initiating the correlation. |
|
The XML XPath for retrieving the value from the payload to initiate the correlation. |
|
The name of the correlation property for the correlation. |
|
The XML XPath for retrieving the value from the payload for the correlation. |
|
Flat Tab |
- |
Used in combination with the end position to retrieve a value from the payload between the start and end positions |
|
Used in combination with the start position to retrieve a value from the payload between the start and end positions |
|
A value between the start and end positions |
|
Apps Tab |
- |
The name of the internal application document. |
|
A sub-classification within the document. |
|
The name of the XSLT file. |
The XPath expression identifies a Custom XML document. You configure the XPath expression when you specify the document type parameters.
The options when configuring an XPath expression are as follows:
Assume that the transaction ID is 12345. Set the parameters as follows:
Field | Value |
---|---|
12345 |
|
//*[local-name() = 'TransactionID']/text() |
Oracle SOA Suite for healthcare integration compares the value of Identification Expression in the payload to the value specified in Identification Value. If the values match, then the document is identified successfully and the corresponding document type and document protocol version are used to identify the endpoint. Example 3-2 shows an excerpt of the XML payload for this option.
Example 3-2 Specify the XPath and the Matching Value
<?xml version="1.0" encoding="UTF-8" ?>
<Message xmlns:ns1="http://www.example1.org" xmlns:ns2="http://www.example2.org"
xmlns="http://www.example3.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns="http://www.example4.org">
<MessageHeader>
<Source>201944019</Source>
<Destination>205704856</Destination>
<TransactionID>123456</TransactionID>
<Version>1-0-0</Version>
</MessageHeader>
<Body>
<ns:Case xsi:schemaLocation="http://www.example4.org" ns1:caseCategoryID="1">
<ns1:OfficialProvisionNumber>String</ns1:OfficialProvisionNumber>
</ns:Case>
</Body>
</Message>
Assume that you are checking for the existence of a node called registerCommand
. Set the parameters as follows:
Field | Value |
---|---|
Leave blank. |
|
/*[local-name()='envelope']/body/transaction/command/*[local-name()='registerCommand'] |
When the Identification Value field is left blank, Oracle SOA Suite for healthcare integration checks for the node identified in Identification Expression. If a node in the payload matches, then the document is identified successfully. Example 3-3 shows an excerpt of the XML payload for this option.
Example 3-3 Check for the Existence of a Node
<uccnet:envelope xmins:eanucc="http://www.ean-ucc.org/schemas/1.3/eanucc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:uccnet="http://www.uccnet.org/schemas/2.2/uccnet" communicationVersion="2.2" xsi:schemaLocation="http://www.uccnet.org/schemas/2.2/uccnet http://www.testregistry.net/xmlschema/uccnet/2.2/Envelope.xsd"> <messageHeader> <messageIdentifier> <value>791:1_EB3CDC749A1F2BABE03014906CC4605A</value> </messageIdentifier> <userId>oraclesupXSD</userId> <representingParty> <gin>0060974050142</gin> </representingParty> </messageHeader> <body> <transaction> <entityIdentification> <uniqueCreatorIdentification>856</uniqueCreatorIdentification> <globalLocationNumber> <gin>0060974050142</gin> </globalLocationNumber> </entityIdentification> <command> <uccnet:registerCommand> <registerCommandHeader type="ADD" /> </uccnet:registerCommand> </command> </transaction> </body> </uccnet:envelope>
Assume that the value of the country attribute is US. Set the parameters as follows:
Oracle SOA Suite for healthcare integration compares the value of the country attribute to the value set for Identification Value. If the values match, then the document is identified successfully. Example 3-4 shows an excerpt of the XML payload for this option.
Example 3-4 Check the Value of an Attribute
<?xml version="1.0" encoding="windows-1252" ?>
<MyAddress country="US" xmlns="http://www.example.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="PO.xsd">
<name>B2B Buyer</name>
<street>100 Oracle Parkway</street>
<city>Redwood City</city>
<state>CA</state>
<zip>94065</zip>
</MyAddress>
Oracle SOA Suite for healthcare integration implements the Health Level 7 (HL7) version 2.x to exchange documents containing health care information using the Generic exchange or MLLP exchange. When using HL7, the standard Oracle SOA Suite for healthcare integration features, such as validation, translation, automatic generation of outbound envelope headers, and acknowledgments, are available.
For information about the organization that created and maintains the HL7 standards, go to
http://www.hl7.org
When you create an HL7 document version, you can set various parameters. Figure 3-6 shows document version parameters for an HL7 document.
Figure 3-6 Document Version Parameters for an HL7 Document
Table 3-2 describes the document version parameters for an HL7 document.
Table 3-2 Document Version Parameters for an HL7 Document
Parameter | Description |
---|---|
Message Header Tab |
- |
In some applications of HL7, this field is used to implement security features. |
|
MSH.11 - This field is used to decide whether to process the message as defined in HL7 Application (level 7) processing rules. The first component defines whether the message is part of a production, training, or debugging system (refer to HL7 table 0103 - Processing ID for valid values). The second component defines whether the message is part of an archival process or an initial load (refer to HL7 table 0207 - Processing mode for valid values). This allows different priorities to be given to different processing modes. |
|
Sets the conditions under which application acknowledgments are required to be returned in response to the message. The value AL (always) is supplied. Oracle SOA Suite for healthcare integration checks the payload (MSH.15) of an incoming message to see if an ACK has to be generated. In some HL7 Systems, MSH.15 is not sent in the payload at all and it is expected that an ACK is still sent. |
|
MSH.16. The value AL (always) is supplied. |
|
Sets the country of origin for the message. The value US is supplied. |
|
Sets the character set for the entire message. The value ASCII is supplied. |
|
MSH.19 |
|
MSH.19 |
|
MSH.19 |
|
MSH.19 |
|
MSH.19 |
|
MSH.19 |
|
MSH.12 |
|
MSH.12 |
|
MSH.12 |
|
MSH.12 |
|
MSH.12 |
|
MSH.12 |
|
Batch Header Tab |
- |
Select the box to create batch headers. |
|
Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used. |
|
BHS.8 |
|
BHS.7. The system date-time stamp is supplied ( |
|
File Header Tab |
- |
Select the check box to create file headers. |
|
Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used. |
|
FHS.8 |
|
FHS.7. The system date-time stamp is supplied ( |
|
Delimiters Tab |
Click Select Hexadecimal Characters next to any of the delimiter fields to provide values. |
A single character that follows the segment identifier and separates each data element in a segment except the last. The value 0x7c is supplied. |
|
The value 0x5c is supplied. |
|
A service character used to separate adjacent occurrences of a repeating data element, or to separate multiple occurrences of a field.The value 0x7e is supplied. |
|
A syntax character indicating the end of a segment (a logical grouping of data fields) within a message. The value 0x0d is supplied. |
|
The value 0x26 is supplied. |
|
The value 0x5e is supplied. |
|
Miscellaneous Tab |
- |
Use this option to provide a list of envelope elements, separated by commas, to be ignored during look-up validation. For an HL7 agreement, the possible values include MessageSendingApp, MessageReceivingApp, MessageSendingFacility, and MessageReceivingFacility. |
|
Select this option to specify whether to send a single acknowledgment or multiple acknowledgments for inbound batched HL7 messages. |
When you create an HL7 document type, you can set various parameters. Figure 3-7 shows the document type parameters for an HL7 document.
Figure 3-7 Document Type Parameters for an HL7 Document
Table 3-3 describes the document type parameters for an HL7 document.
Table 3-3 Document Type Parameters for an HL7 Document
Parameter | Description |
---|---|
Transaction Tab |
- |
If selected, Oracle SOA Suite for healthcare integration sends a generic ACK. |
|
Select to enable mapping the MSH.10 of the business message to the MSH.10 of the acknowledgment. Note: This Map ACK Control ID parameter is for the functional ACK. |
|
A functional acknowledgment is generated when MSH.15 has no value. Select None to take no action. Acknowledgment generation is dependent on the value in MSH.15 of the business message. Select AL (always) to generate the acknowledgment under any conditions. Select ER (error/reject) to generate the acknowledgment when the message errors or is rejected. Select SU (successful completion) to generate the acknowledgment when the message is successfully processed. |
When you create an HL7 document definition (see Section 3.4, "Creating Document Definitions" for more information on creating document definitions), you can set various parameters. Figure 3-8 shows document definition parameters for an HL7 document.
Figure 3-8 Document Definition Parameters for an HL7 Document
Table 3-4 describes the document definition parameters for an HL7 document.
Table 3-4 Document Definition Parameters for an HL7 Document
Parameter | Description |
---|---|
Transaction Tab |
- |
Use the Browse button to find the ecs file. |
|
Routing Tab |
- |
Sets the consumer name to the back-end application |
|
XPath Tab |
-See Section 3.2.2.1, "How to Configure the XPath Expression for a Custom XML Document," for more information. |
The XML XPath name for retrieving the value from the payload |
|
The XML XPath expression for retrieving the value from the payload |
|
The XML XPath name for retrieving the value from the payload |
|
The XML XPath expression for retrieving the value from the payload |
|
The XML XPath name for retrieving the value from the payload |
|
The XML XPath expression for retrieving the value from the payload |
|
Correlation Tab |
- |
The name of the correlation property for initiating the correlation. |
|
The XML XPath for retrieving the value from the payload to initiate the correlation. |
|
The name of the correlation property for the correlation. |
|
The XML XPath for retrieving the value from the payload for the correlation. |
|
Apps Tab |
- |
The name of the internal application document. |
|
A sub-classification within the document. |
|
The name of the XSLT file. |
No business message is produced for an HL7 immediate acknowledgment (transport-level acknowledgment).
Negative acknowledgment messages indicating errors in an HL7 exchange may be truncated because of the 80-character length limitation in HL7 versions 2.1 through 2.5.
A document definition specifies the document protocol—the document protocol version and document type—that is used to validate the message. The document definition can be an ECS file, in the case of HL7 messages, or an XSD/DTD, in the case of XML messages.
The same document definition is used by participating endpoints in a transaction. It must adhere to the standards for document protocols, protocol versions, and document types.
Note:
To ensure that the document definition conforms to standards, you can use Oracle Document Editor to create the document guideline files and then use the Oracle SOA Suite for healthcare integration user interface to import those files when creating the document definition.
After creating transaction set files by using Oracle Document Editor, you use the Oracle SOA Suite for healthcare integration user interface to create the document definition and import the transaction set files.
Note:
The document version, document type, and document definition are not editable after they are created. You must delete the specific document element (version, type, or definition) and create a new one. Updating the document elements after creation can lead to metadata inconsistency, metadata validation issues, and run-time errors.
To create a document definition:
Log on to Oracle SOA Suite for healthcare integration. The Oracle SOA Suite for healthcare integration user interface opens with the Configuration tab selected.
In the left-hand navigation panel, expand Document Protocol. This displays the list of supported protocols, which are Custom and HL 7 V2.x.
Select one of the document protocols, for example HL7, as shown in Figure 3-9, and click the Create button. This displays the Create Document Version window.
Note:
You can also right-click the document protocol name and select Create from the shortcut menu.
Note:
In the Create Document Protocol Version dialog box, enter a protocol version name, for example, 2.3.1.
Enter the document protocol version name in the Name field.
Specify the document version parameters as applicable, and click OK.
The version is used for document identification and can be case sensitive. Use a fixed syntax that conforms to the protocol standards.
Figure 3-10 shows the document protocol version page for an HL7 V2.3.1 document.
Figure 3-10 Entering Document Protocol Version Information
For parameter descriptions, see Table 3-2, "Document Version Parameters for an HL7 Document".
Click the newly created Version name, and then click the Create button to display the Create Document Type window. Alternatively, you can right-click the version name and select Create from the shortcut menu.
Enter a document type name, specify document type parameters as applicable, and then click OK.
Figure 3-11 shows the document type parameters page for an HL7 V2.3.1 document.
Figure 3-11 Entering Document Type Parameter Information
For document type parameter descriptions, see Table 3-3, "Document Type Parameters for an HL7 Document".
With the new document type name selected, click Create to display the Create Document Definition window.
Enter a document definition name and do the following:
Browse for an optional definition (XSD) file for any of the document protocols.
Browse for the required transaction set ECS file for HL7 or positional flat file.
Specify document definition parameters as applicable and click OK.
Figure 3-12 shows the document definition parameters page for an HL7 V2.3.1 document.
Figure 3-12 Entering Document Definition Parameter Information
For definition parameter descriptions, see the following:
Note:
You can also use the post install script, install the standard library, and import hl7 doctypes file to create a document tree in Healthcare console.