1. Using Oracle SOA Suite for Healthcare Integration
  2. Working with Endpoints

4 Working with Endpoints

This chapter describes the concept of an endpoint in Oracle SOA Suite for healthcare integration, and provides instructions for creating and configuring endpoints for healthcare integration applications.

This chapter contains the following topics:

4.1 Introduction to Endpoints

In Oracle SOA Suite for healthcare integration, endpoints are communication channels from where predefined documents are sent or received. Endpoints define how documents are exchanged with an external system, specifying the location, transport protocol, documents to be exchanged, and other configuration parameters.

An endpoint can be a URL, folders, or path, among others. Based on the direction of the message, an endpoint can be inbound, outbound, or both. For example, when Oracle SOA Suite for healthcare integration reads from a directory, the directory is the inbound endpoint. Conversely, when Oracle SOA Suite for healthcare integration writes to or sends messages to a directory, the directory is the outbound endpoint. Also, an MLLP endpoint can be used both for receiving and sending messages.

For Oracle SOA Suite for healthcare integration, you must associate an endpoint with document definitions and enable the endpoint to be able to start sending and receiving messages.

Figure 4-1 displays a sample endpoint, which is yet to be associated with a document definition.

Figure 4-1 Oracle SOA Suite for healthcare integration Sample Endpoint

Description of Figure 4-1 follows
Description of "Figure 4-1 Oracle SOA Suite for healthcare integration Sample Endpoint"

4.2 Creating Endpoints

The Oracle SOA Suite for healthcare integration user interface provides an Endpoints page where you can create and configure endpoints. This procedure describes how to create endpoints using the interface.

You can create endpoints both for bidirectional (MLLP) and single-directional (FILE, JMS) transport protocols. Bidirectional protocols enables you to send or receive response messages or functional acknowledgements (FAs) by using the same endpoint. However, single-directional protocols must be configured to send and receive documents; only then you can send or receive messages or FAs per endpoint.

To create endpoints with bidirectional transport protocol (MLLP):

  1. Log on to the Oracle SOA Suite for healthcare integration user interface.

  2. In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create button as shown in Figure 4-2.

    Figure 4-2 Create Endpoint Button

    Description of Figure 4-2 follows
    Description of "Figure 4-2 Create Endpoint Button"

  3. In the Create window, enter the following and click OK, as shown in Figure 4-3:

    • Name: Name of the endpoint.

    • Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select MLLP10.

    • Connection Mode: Server or Client. If the endpoint is configured as server, Oracle SOA Suite for healthcare integration engine starts listening on a port and waits for a client to connect to it. In general, the server connection mode is for inbound case. When configured as client, the engine connects to hostname and port of a remote computer or device. In general, this is for an outbound case.

      Note:

      Oracle Healthcare supports multiple client connections for a single server channel. So, multiple clients can connect to the same server and exchange data and receive FAs.

      If the message is passed to the back-end application, then the message can be sent in the following ways:

      • Oracle Healthcare passes the endpoint details to the back-end application using dynamic IP address, and the application populates the same values back into outbound dynamic IP header. Oracle Healthcare makes use of this dynamic IP header to pick the correct connection.

      • Clients can set the replytoMsgId property in the properties of the acknowledgement or response message and then connection details can be fetched from the request message.

    • Host Name: In case of an MLLP Server endpoint, it should be name or IP address of the computer hosting Oracle SOA Suite, and in the case of an MLLP Client endpoint, it should be the remote host name or device name. Typically, this should be localhost. However, when localhost is specified, the WLS server listen address is used instead (not the localhost/127.0.0.1 address).

      Note:

      When using NIO mode, you must specify the IP address or the computer name instead of localhost.

    • Port: Port number should be more than 500. If the connection mode is set to Server, then the port must be a valid TCP port number. If the connection mode is set to Client, then the port must be the same as the port used on the MLLP server.

    This creates the endpoint and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

    Figure 4-3 Specifying Endpoint Parameters

    Description of Figure 4-3 follows
    Description of "Figure 4-3 Specifying Endpoint Parameters"

To create endpoints with single-directional transport protocol (FILE):

  1. Log on to the Oracle SOA Suite for healthcare integration user interface.
  2. In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create button.
  3. In the Create window, enter the following and click OK, as shown in Figure 4-4:

    • Name: Name of the endpoint.

    • Transport Protocol: Transport protocol for the sending or receiving messages. In this case, select FILE.

    • Direction: Inbound or Outbound based on your requirement. If the endpoint is configured as inbound, then it can receive response messages or FAs from other endpoints. Conversely, if the endpoint is configured as outbound, it can send messages or FAs.

    • Folder Name: An absolute directory path is recommended and this folder does not contain the inbound or outbound messages or FAs. Inbound messages are expected in this folder, and outbound messages or FAs must be delivered here.

    This creates the endpoint and the endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

    Figure 4-4 Specifying Endpoint Parameters

    Description of Figure 4-4 follows
    Description of "Figure 4-4 Specifying Endpoint Parameters"

    Note:

    After a single-directional endpoint (inbound/outbound) is created, then it can be edited later to add inbound or outbound configuration by clicking the Configure link.

Note:

See Creating Endpoints with Different Transport Protocols for more information on creating endpoints with different transport protocols.

4.2.1 Configuring Channels in an Endpoint with Single-Directional Protocols

When a bidirectional transport protocol (such as MLLP) is used to create an endpoint, the endpoint can handle both request and reply (inbound and outbound) or ACK. However, in the case of a single-directional transport protocol (such as File or FTP), typically, you can only configure either the inbound or the outbound channel, but not both together.

Oracle SOA Suite for healthcare integration, in the case of single-directional protocols, allows you to configure two communication channels (one for sending and one for receiving messages) as a single entity (endpoint) for management and monitoring. This concept allows you to enable or disable, view the supported documents, and display related monitoring data (message counts and actual messages) for the related channels at the same time.

Using this feature, when you use a single-directional transport protocol, you must configure only one channel. The configuration for the other channel (for the reverse direction) is optional. The Oracle SOA Suite for healthcare integration console, in this case, displays that one channel has been configured to send or receive messages, but the other channel has not been configured yet as shown in Figure 4-5.

Figure 4-5 Undefined Secondary Channel

Description of Figure 4-5 follows
Description of "Figure 4-5 Undefined Secondary Channel"

You can configure the other channel by clicking the + button in the undefined channel section, as shown in Figure 4-6, and providing the required channel details in the configuration dialog box.

Figure 4-6 Defining the Secondary Channel

Description of Figure 4-6 follows
Description of "Figure 4-6 Defining the Secondary Channel"

The transport protocol and other settings are defined per channel. You can use different single-directional transport protocols for the two channels. For example, the one channel can use FTP, whereas the other channel can use File. The only requirement is that both the protocols used should be single directional.

After you have defined both the communication channels and associated documents with the channels (see Associating an Endpoint with a Document), the endpoint appears as Figure 4-7.

Figure 4-7 Single-Directional Endpoint with Both Channels Configured

Description of Figure 4-7 follows
Description of "Figure 4-7 Single-Directional Endpoint with Both Channels Configured"

You can edit the configuration of either of the channels if required. You can also delete the configuration of either of the channels by using the Delete links in the relevant channel section.

4.3 Associating an Endpoint with a Document

After you have created an endpoint, you must associate it with a document to enable the endpoint to send or receive messages. You can configure an endpoint to send or receive messages or both.

To associate a bidirectional endpoint with a document:

  1. Open the required endpoint.

  2. Configure the endpoint to send or receive messages:

    1. In the Send or Receive section of the endpoint, click the + button to display the Document selection window.

    2. Select the required document definition from available document hierarchy, for example, ADT_A04_def. The document definition gets associated with the endpoint. You can specify whether you require functional acknowledgment, validation, or translation of the endpoint as well as required internal delivery channel, transport or agreement level callouts, and mapsets.

      Note:

      you can also drag-and-drop the document definition to the Send or Receive section.

      Figure 4-8 displays an endpoint associated with a document definition.

      Figure 4-8 Associating an Endpoint with Document Definitions

      Description of Figure 4-8 follows
      Description of "Figure 4-8 Associating an Endpoint with Document Definitions"

      Note:

      For FA, Functional ACK, Validation, Translation, Retry Interval, and Reattempt Count are disabled.

    3. Select any of the following document configuration options:

      Option Description

      Functional ACK

      Select to enable the functional acknowledgment for success or error criterion

      Validation

      Select to enable validation of the document against the configured ECS file

      Translation

      Select to enable the translation of XML to native format and vice-versa

    4. If any of the following have been defined for the endpoint, select them from the appropriate field: Internal Channel, Document Callout, Mapset, or Composite. For more information, see Creating and Deploying Trading Partner Agreements in Using Oracle B2B.

      Note:

      Selecting the composite name and JMS internal delivery channel name are optional for an inbound document. Oracle Healthcare can support only one composite for a specific document definition. If multiple composites are available, the result is unpredictable because Oracle Healthcare sends messages to the one that is first registered to Oracle Healthcare during runtime.

  3. Select the Enabled check box and click Apply to enable the endpoint for sending and receiving messages.The Apply operation sometimes could take about 30 to 60 seconds. This is due to the XSD/ECS creation and metadata validation.

    Note:

    After making any changes to an endpoint, you can right-click the endpoint name in the left-side panel and click Refresh to update the endpoint.

    Note:

    You can enable or disable an endpoint by selecting or deselecting the Enabled check box and clicking the Apply button.

Associating a single-directional endpoint with a document

To associate a single-directional endpoint, such as File, the procedure is similar to that of a bidirectional endpoint. However, there are a few differences:

  • When creating the endpoint, based on the direction that you have selected, the Oracle SOA Suite for healthcare integration console opens the configuration option for that particular direction.

  • After you follow the other steps listed in associating a bidirectional endpoint with a document, the endpoint gets attached to a document as shown in Figure 4-9.

    Figure 4-9 Associating a Single-directional Endpoint with a Document

    Description of Figure 4-9 follows
    Description of "Figure 4-9 Associating a Single-directional Endpoint with a Document"

  • If when creating the endpoint, you have specified the direction of the endpoint as inbound, you can define the outbound configuration for the endpoint on the same page by using the Configure link. This feature helps in tying two related single-directional endpoints (one for sending and one for receiving messages) as a single entity for better management and monitoring.

Note:

You can disassociate a document from an endpoint by selecting the specific document entry in the Documents section and then by clicking the Delete (X) button.

4.3.1 Overriding Document Parameters at the Endpoint Level

Oracle SOA Suite for healthcare integration enables you to override document parameters at individual endpoint level. Typically, documents are common for all endpoints. In that case, it is not possible to modify the Document Version and the Document Type parameters for a specific endpoint.

With the document parameter override feature, you can override the document parameters specific to an endpoint. For example, Oracle SOA Suite for healthcare integration sends a generic acknowledgement if the HL7 Generic ACK option is enabled in the document definition. So, all the endpoints using the same document definition send generic acknowledgements. However, if you want this feature to be enabled only for a selected set of endpoints, you must override the document definitions for those endpoints.

To override document parameters:

  1. Open the required endpoint.
  2. Click the document link that you want to override under the Document To Send or Document To Receive sections to display the document details dialog box. This dialog box has a tab each for the Document Version and the Document Type.
  3. Click the Document Version tab to display all the sub-tabs related to Document Version, such as Batch Header, Message Header, Delimiters, File Header, and Miscellaneous, of the document that you have selected in the preceding step as shown in Figure 4-10.

    Figure 4-10 Overriding Document Version Parameters

    Description of Figure 4-10 follows
    Description of "Figure 4-10 Overriding Document Version Parameters"
  4. Select the Override check box to make the fields in each of these tab editable.
  5. Make your changes. See What You Might Need to Know About HL7 Document Version Parameters to know more about the HL7 document parameters.
  6. Click the Document Type tab to display the parameters related to the Document Type, such as HL7 Generic ACK, Map ACK Control ID, and Accept Acknowledgement as shown in Figure 4-11.

    Figure 4-11 Overriding Document Type Parameters

    Description of Figure 4-11 follows
    Description of "Figure 4-11 Overriding Document Type Parameters"
  7. Select the Override check box to make the fields in each of these tab editable.
  8. Make your changes. See What You Might Need to Know About HL7 Document Type Parameters to know more about the HL7 document parameters.
  9. Click OK.

The overridden document definition is marked with a button next to it as shown in Figure 4-12.

Figure 4-12 Overridden Document Definition

Description of Figure 4-12 follows
Description of "Figure 4-12 Overridden Document Definition"

4.4 Enabling Sequencing for an MLLP Endpoint

After you associate a document with an endpoint, several options are available for configuring the endpoint.

  • Acknowledgement (ACK) Mode: Select Sync, Async, or None for the mode in which the endpoint receives messages.

  • Retry Interval: The interval between each attempt to retry message delivery.

  • Reattempt Count: The number of times to retry message delivery.

  • Transport Callout: The transport callout to be invoked after receiving or before sending any message. A callout can be selected only after the callout is created.

  • Transport Protocol: Click the Transport Details button to customize the transport protocol parameters as shown in the following graphic.

    Description of endpt_trans_proto.gif follows
    Description of the illustration endpt_trans_proto.gif

    If HL7 messages over MLLP 1.0 are required to be sent in such a way that the next message is sent only after receiving a positive ACK for the current message, then the sequencing mode of MLLP 1.0 can be set to OnetoOne sequencing.

    When associating an MLLP 1.0 endpoint with a document, you can select from the following sequencing modes for outbound messages from the Advanced tab of the Transport Protocol Parameters dialog box:

    • None: Messages are dispatched in sequence without waiting for an ACK

    • OneToOne (Default): Messages are sent in a sequenced manner, but the ACKs are not expected to carry the Control Numbers (the correlation is done without checking the control number in the ACK). In case of a negative ACK, the message sending is retried until either a positive ACK is received or the retry count is exhausted (at which point, the message goes into an error state.)

    • OneToOneMapping: Messages are sent in a sequenced manner, but the ACKs must carry the Control Numbers for proper correlation. Control Number is used to correlate a ACK with the sent message.

    Figure 4-13 displays the available sequencing modes for outbound messages.

    Figure 4-13 Outbound Message Sequencing Modes

    Description of Figure 4-13 follows
    Description of "Figure 4-13 Outbound Message Sequencing Modes"

    For enabling Interface Sequencing for the endpoint, select the Interface Sequencing check box. See Interface Sequencing for more information on configuring Interface Sequencing.

    Note:

    The value selected for the Discard HL7 ACK check box indicates if the ACK payload is persisted or not. This is applicable only in the case of Immediate Acknowledgements or Discard Acknowledgement cases. Deselecting the check box reduces the I/O load at the database layer due to persistence of payloads.

    For more information on transport protocols and their corresponding exchange protocols, see table Transport Protocol Parameters and table Exchange Protocol Parameters in Using Oracle B2B.

For a single-directional endpoint:

4.5 Managing Connection Timeout for MLLP Endpoints

If a bi-directional connection is a permanent connection, the connection may timeout after being idle for a period of time. You can change the timeout value to prevent this.

The timeout interval is determined by the timeout value on the Advanced tab in the Transport Protocol Parameters dialog box. If you do not change the default value, the actual timeout value comes from the hc.mllp.permanentConnectionTimeout property set in the EM console. If you change the default value, then the updated value is honored as the timeout interval.

Note:

A non-permanent connection always uses the timeout parameter value. The default timeout for a permanent connection is 24 hours. If there is no activity for 24 hours, the connection closes, even though it is permanent.

To manage the TCP connection timeout for an MLLP endpoint:
  1. Open the endpoint.
  2. Click the Transport Details button.
    The Transport Protocol Parameters dialog box opens.
  3. Click the Advanced tab.
  4. Change the interval in the Timeout field.
  5. Click OK.

4.6 Enabling SSL/TLS Support for MLLP Endpoints

Oracle SOA Suite for Healthcare Integration provides support for exchanging messages over secured socket connections by using Secured Socket layer (SSL)/Transport Layer Security (TLS) protocol. SSL/TLS protocols provide security to Oracle SOA Suite for healthcare integration to ensure that the security of the messages are not compromised in the process of exchange by potential hackers. Oracle SOA Suite for healthcare integration provides you the option of using either SSL or TLS for securing your message exchange. Currently, this is supported only for MLLP 1.0 endpoints.

SSL is a cryptographic protocol used for transmitting private documents by using the Internet. SSL uses a cryptographic system that uses two keys to encrypt and decrypt data - a public key that is known to everyone is the network and a private key that is known only to the recipient of the message. Please see http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/x64.html to learn more about SSL.

TLS is actually a standardized version of SSL. In fact, SSL version 3 is the last update of SSL, post which TLS comes into being. Essentially, TLS is an advanced version of SSL, which provides the following benefits over SSL:

  • Provides a new cryptographic encryption algorithm for securing connection

  • Allows both secure and insecure connections over the same port

  • Is more extensible

  • Enables two-way (both server and client) authentication at the time of data exchange; server authentication is done by default

To enable SSL/TLS support for MLLP 1.0 endpoints:

  1. Open the endpoint.
  2. Click the Transport Details button to display the Transport Protocol Parameters dialog box.
  3. Click the Connection tab to display a list of configurable connection options as shown in Figure 4-15.

    Figure 4-15 Enabling SSL/TLS in an Endpoint

    Description of Figure 4-15 follows
    Description of "Figure 4-15 Enabling SSL/TLS in an Endpoint"
  4. Select the required protocol from the Security Protocol list. The available options are:

    • NONE: No security protocol to be used; this is the default selection

    • SSLv3: SSLv3 security to be used

    • TLSv1: TLSv1 security to be used

  5. Click Enable Client Authentication to allow two-way authentication. By default, server certificate authentication takes place whenever a client requests for secured data exchange. Selecting the Enable Client Authentication check box allows for client certificate authentication as well. However, this is optional.

    Note:

    The Enable Client Authentication check box is enabled only if you have selected Server as the Connection Mode and anything other than NONE as the Security Protocol. If you select Client as the Connection Mode and NONE as the Security Protocol, this check box is greyed out, because in case of a client endpoint, server authentication happens by default.

  6. Click OK and then click Apply in the endpoint page.

The secured data exchange requires an infrastructure where client/server trusted certificates and the cryptographic algorithm and public/private key pairs are stored. For this, you must define keystores and specify private key passwords. For a two-way authentication, you require to configure two keystores, one at the client side to store server certificates, and the other at the server side to store client certificates.

See Table 13-1 for more information on configuring keystores and specifying private key passwords from the Oracle SOA Suite for healthcare integration console.

4.7 Handling Actionable Errors for an MLLP Endpoint

Oracle SOA Suite for healthcare integration provides support for receiving and delivering HL7 v2.x Messages over the MLLP 1.0 protocol and handling issues such as message parse failure, message validation failure, or rejection.

  • Message parse failure is a term is used for HL7 message MSH (HL7 message Message Header Segment) parse/validation failures in SOA Healthcare.

  • Message validation failure is a term is used for payload validation failures in SOA Healthcare.

In addition, it provides support for automatically retrying failed messages, resetting TCP connections that might be in a faulty state, and stopping message flow after several consecutive message delivery failures.

Typically, message delivery can fail due to the following errors:

  • Parse failure: Caused due to an error in grammar or semantics of the HL7 message

  • Validation failure: Caused to due incorrect value in an HL7 message

  • ACK errors: Caused due to a negative Acknowledgement being received

In case you encounter any parse failure and validation failure errors, you can perform certain corrective actions at the server side (inbound), and in case of ACK errors, you can perform actions at the client side (outbound).

After an endpoint encounters conditions where a corrective action has to be performed (based on the preceding errors), Oracle Healthcare is capable of sending system notifications (similar to Exception messages that are sent for error encountered during processing of messages).To enable Oracle Healthcare to send system notification regarding the corrective actions taken for the preceding system errors, you must set the hc.mllp.EnableEventNotification server property in Oracle Fusion Middleware Enterprise Manager Control console. If this property is set to true, only then Oracle Healthcare generates system notification for the system-level errors, else no system-level notification is generated.

Example - Notification.xsd shows the file used to send notification messages to the notification queue.

Notification.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://integration.oracle.com/B2B/Notification"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns="http://integration.oracle.com/B2B/Notification">
  <xs:element name="Notification">
    <!--xs:complexType name="Notification"-->
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="eventType" minOccurs="0"/>
        <xs:element ref="eventCode" minOccurs="0"/>
        <xs:element ref="eventText" minOccurs="0"/>
        <xs:element ref="eventDescription" minOccurs="0"/>
        <xs:element ref="eventSeverity" minOccurs="0"/>
              <xs:element ref="ComponentDetails" minOccurs="0"/>
              <xs:element ref="eventDetails" minOccurs="0"/>				
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="eventType" type="xs:string"/>
  <xs:element name="eventCode" type="xs:string" />
  <xs:element name="eventText" type="xs:string" />
  <xs:element name="eventDescription" type="xs:string" />
  <xs:element name="eventSeverity" type="xs:string" />
 
  <xs:element name="ComponentDetails">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="ComponentName" minOccurs="0"/>
             <xs:element ref="ComponentType" minOccurs="0"/>
             <xs:element ref="ComponentSubType" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="ComponentName" type="xs:string" />
  <xs:element name="ComponentType" type="xs:string" />
  <xs:element name="ComponentSubType" type="xs:string" />
 
  <xs:element name="eventDetails">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="parameter" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="parameter">
    <xs:complexType>
      <xs:attribute name="name" type="xs:string" use="required" /> 
      <xs:attribute name="value" type="xs:string" use="required" /> 
    </xs:complexType>
  </xs:element>
</xs:schema>

If the hc.mllp.EnableEventNotification server property is set to true, and if a Notification Queue value is specified under Settings > Runtime> Notification Queue in the Administration tab of the Oracle Healthcare console, in the case of Reset Connection and Pause Endpoint error actions, Oracle Healthcare sends system notifications that are sent to the specified Notification Queue.

All notification messages now go to the notification queue. The user need not set the filter to differentiate between notification messages and error messages because they go to different queues. The Message_Type header is added to the notification messages for the following reasons:

  • Backward compatibility.

  • If the user does not set the notification and exception queues, both set of messages go to the same default queue. If this occurs, the Message_Type header can be used to differentiate the messages.

Note:

By default, the Notification Queue dropdown list is empty. To populate the list, you must use Designer > Administration > Internal Delivery Channel > Send to Internal to create a JMS channel (Send to Internal, Internal Delivery Channel).

If a Notification Queue is not specified, then Oracle Healthcare sends the system notification to the default queue or to the SOA notification composite.

You can set these actions either at:

  • The endpoint level

  • The global level

4.7.1 Handling Errors at the Endpoint Level

Oracle SOA Suite for healthcare integration provides you the option of handling the error messages at the endpoint level by using the Oracle SOA Suite for healthcare integration console.

To set error actions at the endpoint level:

  1. Open the endpoint.
  2. Click the Transport Details button to display the Transport Protocol Parameters dialog box.
  3. Click the Error Actions tab to display the configurable error actions and when these actions must be performed as shown in Figure 4-16.

    Figure 4-16 The Error Actions Tab

    Description of Figure 4-16 follows
    Description of "Figure 4-16 The Error Actions Tab"
  4. Select any of the actions listed in Table 4-1:

    Table 4-1 Error Actions

    Error Actions Description

    Server Failure Action

    It is the action to be performed while receiving HL7 messages in case of any message failure, such as message parsing failure and message validation failure.

    The available options are :

    • Default: The property set in the Oracle Fusion Middleware Enterprise Manager Control console will be enforced. If nothing is specified, no action will be taken.

    • None: No action will be taken for the endpoint.

    • ResetConnection: The connection is reset when either the parse failure or a validation failure count reaches the specified limit. The client needs to establish the connection to send the messages again.

    • PauseEndpoint: The endpoint is paused when either the parse failure or validation failure count reaches the specified limit. If the soa server restarts, the endpoint will get started, however, the outbound direction will remain paused because of the entry into sequence manager table. You need to resume the outbound direction manually by using Oracle SOA Suite for healthcare integration console or by using the command line utility for further processing of messages. Once the validation failure count is reached, for Oracle Healthcare to pause the endpoint, you need to configure a Functional ACK.

    Note: For a parse failure error action to be invoked with validation failure error action, you need to configure an Immediate ACK set to Negative, and for validation failure error action, you need to configure a Functional ACK; else these error actions will not be invoked.

    Client Failure Action

    It is the action to be performed while receiving HL7 messages in case of any negative Acknowledgement being received.

    The available options are:

    • Default: The property set in the Oracle Fusion Middleware Enterprise Manager Control console will be enforced. If nothing is specified, no action will be taken.

    • None: No action will be taken for the endpoint.

    • SkipMessage: The message is to be skipped in case of a negative Acknowledgement being received. If the SkipMessage error action is selected, then Oracle Healthcare skips the message that has received negative acknowledgement and moves on to deliver the next message until the skip count is not reached. Once the skip count is reached, if the next message receives a negative Acknowledgement, the endpoint is paused.

      The SkipMessage action works only if the server property b2b.discardACKList is set to either AE (Application Error) or AR (Application Reject) or ALL.

    • PauseEndpoint: If the PauseEndpoint error action is selected, then Oracle Healthcare pauses the endpoint once a negative acknowledgment is received. The endpoint is also paused when the number of skipped messages reaches the specified limit. You need to manually resume the endpoint from the Oracle SOA Suite for healthcare integration dashboard to further process the messages.

      Note: When the client endpoint is paused, a server restart keeps the client endpoint in paused state because of the presence of the sequence manager entry, which blocks outbound messages.

    To reset the connection when the Functional ACK times out and the retries are exhausted, you need to set the server property hc.mllp.ResetConnectionOnAckTimeOut to true. and set the Retry Interval value under Channel/Documents. So, when the retry interval time exceeds, and if the preceding proerty is set, the connection is reset.

    Parse Failure Count

    The maximum number of parse failures for an endpoint before the Server Failure Action is performed.

    Validation Failure Count

    The maximum number of validation failures for an endpoint before the Server Failure Action is performed.

    Skip Messages Count

    The maximum number of consecutive messages that will be skipped before endpoint gets paused.
  5. Click OK then click the Save Changes button.

4.7.2 Handling Errors at the Global Level

Oracle SOA Suite for healthcare integration provides you the option of handling the error messages at the global level by setting the Server properties by using the Oracle Fusion Middleware Enterprise Manager Control console.

To set the properties for setting error actions:

  1. Log on to Oracle Fusion Middleware Enterprise Manager Control console by accessing the following:

    http://<hostname>:<port>/em, where hostname is the name of the computer where the Oracle Weblogic server is running, and port is typically 7001.

  2. Navigate to B2B Server Properties by expanding SOA > SOA Administration, and then right-clicking <soa domain name> as shown in Figure 4-17.

    Figure 4-17 Accessing B2B Server Properties

    Description of Figure 4-17 follows
    Description of "Figure 4-17 Accessing B2B Server Properties"
  3. On the B2B Server Properties page, click the More B2B Configuration Properties... link to display the System MBean Browser.
  4. Click the Operations tab and then click addProperty as shown in Figure 4-18.

    Figure 4-18 Adding B2B Server Properties

    Description of Figure 4-18 follows
    Description of "Figure 4-18 Adding B2B Server Properties"
  5. Add the properties listed in Table 4-2. The properties are equivalent to the error actions listed in Table 4-1 that you can configure in the Oracle SOA Suite for healthcare integration console.

    Table 4-2 Server Properties for Configuring Error Actions

    Property Name (java.lang.String) Valid Property Values (java.lang.String)

    hc.mllp.ServerFailureAction

    ResetConnection, PauseEndpoint

    hc.mllp.ClientFailureAction

    SkipMessage, PauseEndpoint

    hc.mllp.ParseFailureCount

    Value greater than zero

    hc.mllp.ValidationFailureCount

    Value greater than zero

    hc.mllp.SkipMessagesCount

    Value greater than zero

The parameters set in the Oracle SOA Suite for healthcare integration console are applicable at each endpoint level, and the Server properties set using the Oracle Fusion Middleware Enterprise Manager Control console are applicable for all the endpoints. At runtime, for each endpoint, the values set at the endpoint level in the Oracle SOA Suite for healthcare integration console (other than Default for Failure Actions and 0 for the counts) override the values set at global level, which means that the global level values are only used if the Default value or 0 is selected at the console level.

4.8 Message Flow Throttling

Oracle B2B can pause, or throttle, the endpoint to publish messages to B2B_EVENT_QUEUE if the messages in B2B_EVENT_QUEUE grow large.

By default, b2b.useJMSDataSourceCache is set to true. If you want to use throttling, b2b.useJMSDataSourceCache cannot be set to false.

For more information about controlling the message flow, see Controlling the Flow of Messages on JMS Servers and Destinations in Oracle Fusion Middleware Tuning Performance of Oracle WebLogic Serverguide.

To pause the endpoint:
  1. In the B2B Console, go to the B2BEventQueueConnectionFactory settings page and click the Flow Control tab.
  2. Set the Flow Maximum, Flow Minimum, Flow Interval, and Flow Steps values as appropriate for your environment.
  3. Go to the B2BEventQueue settings page and click the Thresholds and Quotas tab.
  4. Set the Messages Threshold High and Messages Threshold Low values as appropriate for your environment.

4.9 Cloning Endpoints

If you need a new endpoint that is similar to an existing endpoint, you can clone the endpoint.

To clone an endpoint:
  1. In the Configuration tab under the Design tab, click the Endpoint folder
  2. Select the endpoint you want to clone.
  3. Click the Clone button on the toolbar.
  4. Enter a name for the endpoint.

    Note:

    You can also change any parameters, if desired.

  5. Click OK to save the endpoint.
A new endpoint is created with the data from the original endpoint. Note that the endpoint is in Disabled mode by default.

4.10 Deleting an Endpoint

To delete an endpoint, you must first disable it. An enabled endpoint cannot be deleted.

To delete an endpoint, log on to the Oracle SOA Suite for healthcare integration user interface. In the Configuration tab under the Designer link, select the endpoint name and click the Delete button. You can also right-click the endpoint name and click Delete from the shortcut menu.

4.11 Working with the Endpoint Window

You can use open the Endpoint window to view a list of existing endpoints. In addition, using the endpoint window, you can create, modify or delete endpoints. You can also perform bulk modification or deletion using this window by selecting all or the required endpoints and then performing the operation of your choice.

To access the Endpoint window:

  1. Log on to the Oracle SOA Suite for healthcare integration user interface.
  2. In the Configuration tab under the Designer link, double-click the Endpoint folder.

Figure 4-19 displays the Endpoint window.

Figure 4-19 The Endpoint Window

Description of Figure 4-19 follows
Description of "Figure 4-19 The Endpoint Window"

4.12 Healthcare and Oracle Managed File Transfer Integration

Oracle SOA Suite for healthcare integration (Oracle Healthcare) recognizes Oracle Managed File Transfer (MFT) as a remote endpoint. In endpoint configurations, MFT is added as additional transport protocol. Oracle Healthcare uses an outbound endpoint to send files to MFT and an inbound endpoint to receive files.

You must configure an Oracle Healthcare domain in MFT if Oracle Healthcare is not co-located with MFT. For more information, see "Managing Domains" in Oracle Fusion Middleware Using MFT.

4.12.1 Oracle Healthcare Endpoint Configurations

The following sections describe how to create Oracle Healthcare endpoint configurations.

4.12.1.1 Creating an Outbound Endpoint for an Oracle Healthcare Source

An Oracle Healthcare source in MFT corresponds to an outbound endpoint for a remote endpoint in Oracle Healthcare.

The steps for this process are:

  1. In Oracle Healthcare, in the Configuration tab under the Design tab, click the Endpoint folder and then click the Create button
  2. In the Create Endpoint dialog (Figure 4-20), enter the following and click OK:

    • Name: Type a name for the new endpoint.

    • Transport Protocol: Select MFT

    • Direction: Select Outbound

    • Source: Type the MFT source name

      Figure 4-20 Create Endpoint Dialog

      Description of Figure 4-20 follows
      Description of "Figure 4-20 Create Endpoint Dialog"

      The endpoint is displayed in the right panel of the Oracle SOA Suite for healthcare integration user interface.

  3. Click the Transport Details button.
  4. In the Transport Protocol Parameters window (Figure 4-21), enter the following and click OK:
  5. Find the document to be transferred under the Document Protocol folder
  6. Drag and drop the document to be transferred into the Document to Send table.
  7. Save the endpoint.

For more information, see the previous sections in this chapter.

4.12.1.2 Creating an Inbound Endpoint for an Oracle Healthcare Target

An Oracle Healthcare target in MFT corresponds to an inbound endpoint for a remote endpoint in Oracle Healthcare.

The steps for this process are:

  1. In Oracle Healthcare, in the Configuration tab under the Design tab, click the Endpoint folder and then click the Create button.
  2. In the Create window (Figure 4-22), enter the following and click OK:
  3. Find the document to be transferred under the Document Protocol folder.
  4. Drag and drop the document to be transferred into the Document to Receive table.
  5. Save the endpoint.

For more information, see the previous sections in this chapter.

4.12.2 Creating the Required MFT Artifacts for Oracle Healthcare

The following sections describe how to create the artifacts required for Oracle Healthcare.

4.12.2.1 Creating an MFT Domain to interact With Oracle Healthcare Endpoints

Use the following steps to configure a domain for Oracle Healthcare in the MFT user interface.

  1. Open the Domains tab on the Administration page.
  2. Click the Add button.

    An empty row is added to the domain table.

  3. Enter the following information in the table cells (Figure 4-23):

    • Domain Alias: The host name used to connect to the domain. The domain alias setting for a source or target maps to this alias.

    • Connection URL: The service endpoint URL for connecting to Oracle Healthcare applications running on remote servers. These servers can be in the same Oracle WebLogic Server domain as MFT or in a different domain. It is used to send messages to Oracle Healthcare endpoints.

    • User: The user accessing the domain.

    • Password: The user password.

    • Confirm Password: User password confirmation.

    • Tracking URL: The Oracle Healthcare URL used by MFT for constructing the Oracle Healthcare reports URL.

    • Type: Select the domain type Healthcare from the dropdown list.

    • Description: A text description of the domain.

  4. Click Save.
4.12.2.2 Creating an MFT Source for an Outbound Oracle Healthcare Endpoint

An MFT outbound endpoint in Oracle Healthcare corresponds to an MFT Source in MFT.

The following steps describe how to create an MFT Source:

  1. In the MFT user interface, in the Designer tab under the Design tab, click the Sources folder and then click the Create button.
  2. In the Create Source (Figure 4-24) window, enter the following and click OK:

    • Name: Name of the new Source.

    • Description: Description of the new Source.

    • Type: Select Source Type Healthcare from the dropdown list.

    • Endpoint Name: Type the corresponding endpoint name intended for this source.

    • Domain Alias: Select the corresponding Oracle Healthcare domain from the dropdown list

    Figure 4-24 Create Source Dialog

    Description of Figure 4-24 follows
    Description of "Figure 4-24 Create Source Dialog"

The created source is displayed in the right panel of the MFT user interface.

4.12.2.3 Creating an MFT Target for an Inbound Oracle Healthcare Endpoint

An MFT target corresponds to a Oracle Healthcare inbound endpoint.

Use the following steps to create an MFT target:

  1. Select Targets in the left pane navigator and click the Create button
  2. In the Create Target dialog (Figure 4-25), enter the following and click OK

    • Name: Name of the target

    • Description: Description for the new target

    • Type: Select Target Type Healthcare from the dropdown list

    • Endpoint Name: Type the corresponding endpoint name intended for this target.

    • Domain Alias: Select the corresponding Oracle Healthcare domain from the dropdown list.

Figure 4-25 Create Target Dialog

Description of Figure 4-25 follows
Description of "Figure 4-25 Create Target Dialog"

The new target is displayed in the right panel of the MFT user interface.

4.12.2.4 Creating an MFT Transfer

An MFT transfer is a binding entity of sources and targets created for Oracle Healthcare endpoints.

Use the following steps to create a transfer:

  1. Click Transfers in the left pane navigator:
  2. Type a Name and Description for the transfer and click OK. A tab for the transfer opens.
  3. Add the corresponding source and targets created for Oracle Healthcare endpoints.
  4. Add preprocessing and postprocessing actions such as compression and encryption.

    This is optional and applies only to targets. Source actions are added directly in the source artifact.

  5. Click the Save button.
  6. Click the Deploy button after saving. You can add an optional comment.

If the associated source and target have not been previously deployed, deploying the transfer automatically deploys the associated source and target.

Figure 4-26 MFT Transfer Page

Description of Figure 4-26 follows
Description of "Figure 4-26 MFT Transfer Page"

4.12.3 Interlinked Oracle Healthcare and MFT Reports

An MFT instance report for a Oracle Healthcare source or target has a Correlation Flow ID link. Click this link to open the corresponding report for the Oracle Healthcare endpoint.

Likewise, a Oracle Healthcare endpoint instance report for MFT has an MFT source or target button. Click this button to open the corresponding MFT instance report.

See "Interpreting Source, Transfer, and Target Reports" in Oracle Fusion Middleware Using Oracle Managed File Transfer for more information about MFT instance reports.