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:
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 need to 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
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 need to 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):
Log on to the Oracle SOA Suite for healthcare integration user interface.
In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create icon as shown in Figure 4-2.
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 backend application, then the message can be sent in the following ways:
Oracle Healthcare passes the endpoint details to the backend application using dynamic IP address, and te 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, Host name can also be the name of the remote host or device.
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
To create endpoints with single-directional transport protocol (FILE):
Log on to the Oracle SOA Suite for healthcare integration user interface.
In the Configuration tab under the Design tab, click the Endpoint folder and then click the Create icon.
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 need to 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
Note:
Once 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 Appendix B, "Creating Endpoints with Different Transport Protocols" for more information on creating endpoints with different transport 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 need to 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.
You can configure the other channel by clicking the Configure link 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
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.
Once you have defined both the communication channels and associated documents with the channels (see Section 4.3, "Associating an Endpoint with a Document"), the endpoint appears as Figure 4-7.
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.
Once you have created an endpoint, you need to 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:
Open the required endpoint.
Configure the endpoint to send or receive messages:
In the Send or Receive section of the endpoint, click the + icon to display the Document selection window.
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
Note:
For FA, Functional ACK, Validation, Translation, Retry Interval, and Reattempt Count are disabled.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 |
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 Chapter 6 Creating and Deploying Trading Partner Agreements in Oracle Fusion Middleware User's Guide for 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.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.
Once 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
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.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 need to override the document definitions for those endpoints.
To override document parameters:
Open the required endpoint.
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.
Click the Document Version tab to display all the subtabs 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, "Overriding Document Version Parameters".
Figure 4-10 Overriding Document Version Parameters
Click the Override check box to make the fields in each of these tab editable.
Make your changes. See Section 3.3.1, "What You May Need to Know About HL7 Document Version Parameters" to know more about the HL7 document parameters.
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, "Overriding Document Version Parameters" .
Figure 4-11 Overriding Document Version Parameters
Click the Override check box to make the fields in each of these tab editable.
Make your changes. See Section 3.3.2, "What You May Need to Know About HL7 Document Type Parameters" to know more about the HL7 document parameters.
Click OK.
The overridden document definition is marked with an icon next to it as shown in Figure 4-12, "Overridden Document Definition" .
Figure 4-12 Overridden Document Definition
After you associate a document with an endpoint, the following 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.
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
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 5-3 Transport Protocol Parameters and Table 5-5 Exchange Protocol Parameters in the Chapter 5 Configuring Trading Partners in Oracle Fusion Middleware User's Guide for Oracle B2B.
For a single-directional endpoint:
When you click the Transport Details button, the Transport Protocol Parameters dialog box that appears, is prompts for a set of parameters that are different from the bidirectional endpoint. Figure 4-14 displays the Transport Protocol parameters dialog box for a single-directional endpoint.
Figure 4-14 The Transport Protocol Parameters Dialog Box
For more information on transport protocols, see Table 5-3 Transport Protocol Parameters in the Chapter 5 Configuring Trading Partners in Oracle Fusion Middleware User's Guide for Oracle B2B.
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:
Open the endpoint.
Click the the Transport Details button to display the Transport Protocol Parameters dialog box.
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
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
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 Authetication check box will be 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 will be greyed out, because in case of a client endpoint, server authentication happens by default.Click OK and then click Apply in the endpoint page.
The secured data exchange requires an infrastructure where client/server trusted certicates and the cryptographic algorithm and public/private key pairs are stored. For this, you need to 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, "Runtime Configuration Settings" for more information on configuring keystores and specifying private key passwords from the Oracle SOA Suite for healthcare integration console.
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. In addition, it provides support for automatically retrying failed messages, resetting TCP connections that may 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).
Once 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 need to 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.
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.
If a Notification Queue is not specified, then Oracle Healthcare sends the system notification to the default queue.
You can set these actions either at:
The endpoint level
The global 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:
Open the endpoint.
Click the Transport Details button to display the Transport Protocol Parameters dialog box.
Click the Error Actions tab to display the configurable error actions and when these actions need to be performed as shown in Figure 4-16.
Select any of the actions listed in Table 4-1:
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 :
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:
To reset the connection when the Functional ACK times out and the retries are exhausted, you need to set the server property |
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. |
Click OK.
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:
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
.
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
On the B2B Server Properties page, click the More B2B Configuration Properties... link to display the System MBean Browser.
Click the Operations tab and then click addProperty as shown in Figure 4-18.
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 ) |
---|---|
|
|
|
|
|
Value greater than zero |
|
Value greater than zero |
|
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.
To delete an endpoint, log on to the Oracle SOA Suite for healthcare integration user interface. In the Configuration tab under the Design tab, select the endpoint name and click the Delete icon. You can also right-click the endpoint name and click Delete from the shortcut menu.
Note:
An enabled endpoint cannot be deleted. you need to disable the endpoint before deleting it.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:
Log on to the Oracle SOA Suite for healthcare integration user interface.
In the Configuration tab under the Design tab, double-click the Endpoint folder.
Figure 4-19 displays the Endpoint window.