Skip Headers
Oracle® Fusion Middleware Healthcare Integration User's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.7)

Part Number E23486-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Working with Document Types and Protocols

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:

3.1 Introduction to Document Protocols

Oracle SOA Suite for healthcare integration supports the following document protocols:

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

Description of Figure 3-1 follows
Description of "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 runtime, the payload must conform to the document definition file type you use.

3.1.1 What You May Need to Know About the Document Hierarchy

You can think of a document protocol as a hierarchy, as shown in Figure 3-2.

Figure 3-2 Document Hierarchy

Document hierarchy
Description of "Figure 3-2 Document Hierarchy"

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.

Figure 3-3 HL7 V2.3.1 Document Hierarchy

Document protocol hierarchy with EDI X12 example
Description of "Figure 3-3 HL7 V2.3.1 Document Hierarchy"

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.

Example 3-1 Document Definition Name for an HL7 Document

Document protocol: HL7

Document protocol version: 2.3.1

Document type: ADT_A01

Document definition: ADT_A01_def

The resulting document definition is:

HL7-2.3.1-ADT_A01-ADT_A01_def

3.2 Using the Custom Document Protocol

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.

3.2.1 What You May Need to Know About Custom Document Version Parameters

No parameters need to be set when you create the document version for a Custom document.

3.2.2 What You May Need to Know About Custom Document Definition Parameters

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

Description of Figure 3-4 follows
Description of "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

Description of Figure 3-5 follows
Description of "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)

Identification Expression (XPath)

Locates a node in the XML payload

Identification Value

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.

DTD/XSD NamespaceConversion

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

XPath Name1

The XML XPath name for retrieving the value from the payload

XPath Expression1

The XML XPath expression for retrieving the value from the payload.

XPath Name2

The XML XPath name for retrieving the value from the payload.

XPath Expression2

The XML XPath expression for retrieving the value from the payload.

XPath Name3

The XML XPath name for retrieving the value from the payload.

XPath Expression3

The XML XPath expression for retrieving the value from the payload.

Correlation Tab

-

Correlation From XPath Name

The name of the correlation property for initiating the correlation.

Correlation From XPath Expression

The XML XPath for retrieving the value from the payload to initiate the correlation.

Correlation To XPath Name

The name of the correlation property for the correlation.

Correlation To XPath Expression

The XML XPath for retrieving the value from the payload for the correlation.

Flat Tab

-

Identification Start Position

Used in combination with the end position to retrieve a value from the payload between the start and end positions

Identification End Position

Used in combination with the start position to retrieve a value from the payload between the start and end positions

Identification Value

A value between the start and end positions

Apps Tab

-

Document

The name of the internal application document.

Action

A sub-classification within the document.

XSLTFile

The name of the XSLT file.


3.2.2.1 How to Configure the XPath Expression for a Custom XML Document

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:

3.2.2.1.1 Option 1: Specify the XPath and the Matching Value

Assume that the transaction ID is 12345. Set the parameters as follows:

Field Value

Identification Value

12345

Identification Expression

//*[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>
3.2.2.1.2 Option 2: Check for the Existence of a Node

Assume that you are checking for the existence of a node called registerCommand. Set the parameters as follows:

Field Value

Identification Value

Leave blank.

Identification Expression

/*[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>
3.2.2.1.3 Option 3: Check the Value of an Attribute

Assume that the value of the country attribute is US. Set the parameters as follows:

Field Value

Identification Value

US

Identification Expression

//*/@country


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>

3.3 Using the HL7 Document Protocol

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

3.3.1 What You May Need to Know About HL7 Document Version Parameters

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

Description of Figure 3-6 follows
Description of "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

-

Security

In some applications of HL7, this field is used to implement security features.

Processing ID

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.

Accept Acknowledgement Type

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.

Application Acknowledgment Type

MSH.16. The value AL (always) is supplied.

Country Code

Sets the country of origin for the message. The value US is supplied.

Character Set

Sets the character set for the entire message. The value ASCII is supplied.

Internationalization Code Identifier

MSH.19

Internationalization Code Text

MSH.19

Internationalization Coding System Name

MSH.19

Internationalization Code Alternate Identifier

MSH.19

Internationalization Code Alternate Text

MSH.19

Internationalization Code Alternate Coding System Name

MSH.19

International Version Identifier

MSH.12

International Version ID Text

MSH.12

International Version ID Coding System Name

MSH.12

International Version ID Alternate Identifier

MSH.12

International Version ID Alternate Text

MSH.12

International Version ID Alternate Coding System Name

MSH.12

Batch Header Tab

-

Create Batch Header

Select the box to create batch headers.

Batch Header Ecs File

Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used.

Batch Security

BHS.8

Batch Date

BHS.7. The system date-time stamp is supplied (#SystemDateTime(CCYYMMDDHHMM)#).

File Header Tab

-

Create File Header

Select the check box to create file headers.

File Header Ecs File

Use the Browse button to find an ecs file to override the standard file. If not provided, the provided default file is used.

File Security

FHS.8

File Date

FHS.7. The system date-time stamp is supplied (#SystemDateTime(CCYYMMDDHHMM)#).

Delimiters Tab

Click Select Hexadecimal Characters next to any of the delimiter fields to provide values.

Element Delimiter

A single character that follows the segment identifier and separates each data element in a segment except the last. The value 0x7c is supplied.

Escape Character

The value 0x5c is supplied.

Repeating Separator

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.

Segment Delimiter

A syntax character indicating the end of a segment (a logical grouping of data fields) within a message. The value 0x0d is supplied.

Subcomponent Delimiter

The value 0x26 is supplied.

Subelement Delimiter

The value 0x5e is supplied.

Miscellaneous Tab

-

Ignore Envelope Parameters

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.

Ack Mode

Select this option to specify whether to send a single acknowledgment or multiple acknowledgments for inbound batched HL7 messages.


3.3.2 What You May Need to Know About HL7 Document Type Parameters

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

Description of Figure 3-7 follows
Description of "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

-

HL7 Generic ACK

If selected, Oracle SOA Suite for healthcare integration sends a generic ACK.

Map ACK Control ID

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.

Accept Acknowledgement

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.


3.3.3 What You May Need to Know About HL7 Document Definition Parameters

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

Description of Figure 3-8 follows
Description of "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

-

*Transaction Set ecs File

Use the Browse button to find the ecs file.

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," for more information.

XPath Name1

The XML XPath name for retrieving the value from the payload

XPath Expression1

The XML XPath expression for retrieving the value from the payload

XPath Name2

The XML XPath name for retrieving the value from the payload

XPath Expression2

The XML XPath expression for retrieving the value from the payload

XPath Name3

The XML XPath name for retrieving the value from the payload

XPath Expression3

The XML XPath expression for retrieving the value from the payload

Correlation Tab

-

Correlation From XPath Name

The name of the correlation property for initiating the correlation.

Correlation From XPath Expression

The XML XPath for retrieving the value from the payload to initiate the correlation.

Correlation To XPath Name

The name of the correlation property for the correlation.

Correlation To XPath Expression

The XML XPath for retrieving the value from the payload for the correlation.

Apps Tab

-

Document

The name of the internal application document.

Action

A sub-classification within the document.

XSLTFile

The name of the XSLT file.


3.3.4 What You May Need to Know About Using HL7

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.

3.4 Creating Document Definitions

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 runtime errors.

To create a document definition:

  1. Log on to Oracle SOA Suite for healthcare integration. The Oracle SOA Suite for healthcare integration user interface opens with the Configuration tab selected.

  2. In the left-hand navigation panel, expand Document Protocol. This displays the list of supported protocols, which are Custom and HL 7 V2.x.

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

    Figure 3-9 Selecting a Document Protocol

    Document protocols available in B2B
    Description of "Figure 3-9 Selecting a Document Protocol"

    Note:

    In the Create Document Protocol Version dialog box, enter a protocol version name, for example, 2.3.1.

  4. Enter the document protocol version name in the Name field.

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

    Input the document version
    Description of "Figure 3-10 Entering Document Protocol Version Information"

    For parameter descriptions, see Table 3-2, "Document Version Parameters for an HL7 Document".

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

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

    Input the document type name.
    Description of "Figure 3-11 Entering Document Type Parameter Information"

    For document type parameter descriptions, see Table 3-3, "Document Type Parameters for an HL7 Document".

  8. With the new document type name selected, click Create to display the Create Document Definition window.

  9. Enter a document definition name and do the following:

    1. Browse for an optional definition (XSD) file for any of the document protocols.

    2. Browse for the required transaction set ECS file for HL7 or positional flat file.

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

    Input the document definition name.
    Description of "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.

3.5 Deleting a Document Definition

To delete a document definition, select the document definition name and click Delete. Alternatively, you can select the definition name, right-click, and select Delete from the shortcut menu.