Using the HL7 Binding Component

Dynamically Configuring HL7 Endpoints

Dynamic configuration is the ability to make changes at runtime, without reconfiguring a project's design-time configuration. WSDL files provide static configuration controls for the behavior of JBI endpoints.

To dynamically configure an HL7 project, there are three alternatives:

The following topics provide additional information and instructions on using normalized message properties:

Application Variables

Application Variables are name value pairs of a given type (String, number, Boolean, or password) and are defined at the binding component level. The Application Variable name acts as a token for a WSDL extensibility element attribute in a corresponding binding. For example, if you were defining an application variable for the hostname as FOO, then the WSDL attribute would be ${FOO}. In the Application Variables property you would enter a String value of FOO for the name, and the desired attribute as the value. For more information on using Application Variables see Using Application Variables to Define Name/Value Pairs.

Application Configurations

The Application Configuration property allows you to configure the connectivity and level parameters for an application that you have created, and without changing or rebuilding the application, deploy the same application into a different system. For example, you can take an application that is running in a test environment and deploy it to a production environment without rebuilding the application. A Composite Application's external connectivity parameters, which are normally defined in the WSDL service extensibility elements, can be configured in the runtime properties. For more information on using Application Configurations see Defining an HL7 Binding Component Application Configuration.

Dynamic Addressing Using Normalized Message Properties

Dynamic Addressing uses Normalized Message Properties to dynamically override the static configuration of an endpoint and reroute messages accordingly. The message payload can contain the location of the message consumer as well as other binding protocol specific information to configure endpoint behavior.

Normalized Message properties are commonly used to specify metadata that is associated with message content. javax.jbi.security.subject and javax.jbi.message.protocol.type are two examples of standard normalized Message properties defined in the JBI Specification.

Normalized Message properties provide additional capabilities, including the following:

Getting and setting transport context properties; for example, HTTP headers in the incoming HTTP request or file names read by the File Binding Component.
Getting and setting protocol-specific headers or context properties (SOAP headers).
Getting and setting additional message metadata; for example. a unique message identifier or an endpoint name associated with a message.
Dynamic configurations; for example, to dynamically overwrite the statically configured destination file name at runtime.

Some of the use cases mentioned above require protocol and binding specific properties, typically used by a particular binding component. Other properties are considered common or general purpose properties that all participating JBI components make use of, such asthe message ID property, which can be utilized to uniquely identify or track a given message in the integration.

Enabling Dynamic Endpoint Configuration

Normalized Message Properties are component specific, different for every binding component type. To enable HL7 Normalized Message properties to be applied to a Dynamic Endpoint configuration, set the HL7 runtime configuration property Allow Dynamic Endpoint to true (checked). You will also need to set the HL7 Normalized Message Property, Use Dynamic Endpoint, to true.

Image shows the HL7 Binding Component Runtime
Properties Editor with the Allow Dynamic Endpoint property set to
true

When Allow Dynamic Endpoint is enabled, the HL7 Binding Component behaves as follows:

Inbound Endpoint Behavior:
1. The HL7 Binding Component receives the message from the external system.
2. It creates the Message Exchange and adds the normalized message.
3. It checks to see if the runtime Allow Dynamic Endpoint property is enabled. If enabled, it populates the respective Normalized Message Properties with the specified values.
4. It appends these Normalized Message Properties to the Message Exchange.
5. It sends the Message Exchange to the delivery channel.
Outbound Endpoint Behavior:
1. The HL7 Binding Component receives the Message Exchange from the delivery channel.
2. It checks to see if the runtime Allow Dynamic Endpoint property, and the Outbound Normalized Message property Use Dynamic Endpoint (org.glassfish.openesb.hl7.use.dynamic.endpoint) are enabled. If enabled, it retrieves the Normalized Message properties from Message Exchange and uses them to overwrite the static binding configuration of the endpoint.
3. It uses the overwritten property information while communicating with the external system.

Using Normalized Message Properties in a BPEL Process

The Normalized Message properties are accessed from the BPEL Designer Mapper view. When you expand a variable's Properties folder it exposes the variable's predefined NM properties, as well as the regular BPEL specific WSDL properties used in correlation sets, assigns, and to build expressions .

Using Predefined Normalized Message Properties in a BPEL Process

Predefined Normalized Message properties are ready for use, from a variable's Properties file.

To Use Predefined Normalized Message Properties in a BPEL Process

From the Design View diagram, select the activity with the process you want to edit.

Click Mapper to switch to the Mapper view of the BPEL process.

Expand the Variable you want to edit and its Properties file.

To dynamically configure an endpoint, first expand the /Properties/General node to expose the General Normalized Message Properties.

Enter values for the Message ID property and the Endpoint Name property.

To enter a java.lang.String value for the General or HL7 Normalized Message Properties, do the following:
1. From the BPEL Designer's Mapper window, select the Normalized Message Property you want to configure.
  
  The property is highlighted with a blue field indicating that you are applying an action to this item.
2. From the String menu in the Mapper's toolbar select String Literal.
  
  A String Literal method box is added to the properties action field.
3. Double-click the value field of the String Literal box and enter the appropriate value.
4. Map the String Literal box to the property. To do this, click on the outbound handle of the String Literal box, and drag your cursor to the Normalized Message Property.
  
  A line now links the String Literal box to the property.

Expand the /Properties/HL7 node to expose the HL7 Normalized Message Properties.

Set the String value of the Use Dynamic Endpoint property to true. Also add String values to any other HL7 properties you want to dynamically configure.

Save your changes.

Normalized Message Properties

The HL7 Binding Component uses the General Normalized Message properties, as well as the HL7 Normalized Message properties for outbound and inbound endpoints.

General Normalized Message Properties

The following General NM properties are available to all binding components.

Table 7 General Normalized Message Properties


Property Name	Type	Description and Use
Endpoint Name org.glassfish.openesb.exchange.endpointname	java.lang.String	Specifies the endpoint name set on the exchange. This represents the endpoint name of the "owner" of the message, and can be made available by JBI runtime.
Message ID org.glassfish.openesb.messaging.messageid	java.lang.String	Specifies a unique identifier for a message. This might be a record number (for example, a particular record in a file), or a GUID.
Last Record org.glassfish.openesb.messaging.lastrecord	java.lang.String	Specifies the last record in a group, e.g. the last record in an RM sequence for SOAP messages, or the last record in a file when multiple record processing is turned on for File BC.
Group ID org.glassfish.openesb.messaging.groupid	java.lang.String	Specifies a unique identifier for a group to which a message belongs. For example, it applies the RM sequence group number for SOAP messages, or a time stamped file name (where the file record message comes from).

HL7 Binding Component Normalized Message Properties for Outbound Endpoints

The following table defines the HL7 Normalized Messages for outbound endpoints.

Table 8 HL7 NM Properties for Outbound Endpoints


Property Name	Type	Description and Use
Use Dynamic Endpoint org.glassfish.openesb.hl7.use.dynamic.endpoint	java.lang.String	Specifies if the message uses "DynamicAddressing." This is a mandatory property if you are using NM properties for dynamic addressing. This property has no equivalent WSDL attribute.
Host	java.lang.String	Specifies the host part of a URL used to connect to an HL7 external system. The equivalent WSDL attribute is hl7:address -> location(host).
Port org.glassfish.openesb.hl7.outbound.address.port	java.lang.String	Specifies the port part of a URL used to connect to an HL7 external system. The equivalent WSDL attribute is hl7:address -> location(port).
Lower Layer Protocol Type org.glassfish.openesb.hl7.outbound.protocolproperties.llptype	java.lang.String	Indicates the Lower Layer Protocol Type as MLLPv1 (Minimal Lower Layer Protocol release 1), MLLPv2 (Minimal Lower Layer Protocol release 2), and HLLP (Hybrid Lower Layer Protocol). The equivalent WSDL attribute is hl7:protocolproperties -> llpType.
Start Block Character org.glassfish.openesb.hl7.outbound.protocolproperties.startblockcharacter	java.lang.String	Indicates the Start Block Character Value in a decimal ASCII number from 1 to 127. Unless there is a conflict, the value should be ASCII VT, which is decimal 11. The equivalent WSDL attribute is hl7:protocolproperties -> startBlockCharacter.
End block Character org.glassfish.openesb.hl7.outbound.protocolproperties.endblockcharacter	java.lang.String	Indicates the End Block Character Value in decimal ASCII number from 1 to 127. To be strictly comply with the HL7 standard, this parameter must be set to a carriage Return, which is decimal 13. The equivalent WSDL attribute is hl7:protocolproperties -> endBlockCharacter.
End Data Character org.glassfish.openesb.hl7.outbound.protocolproperties.enddatacharacter	java.lang.String	Indicates the End Data Character Value in decimal ASCII number from 1 to 127. Unless there is a conflict, the value should be ASCII VT, which is decimal 28. The equivalent WSDL attribute is hl7:protocolproperties -> endDataCharacter.
Enable HLLP Checksum org.glassfish.openesb.hl7.outbound.protocolproperties.hllpchecksumenabled	java.lang.String	Specifies if HLLP CheckSum is enabled. “true” indicates enabled. The equivalent WSDL attribute is hl7:protocolproperties -> hllpChecksumEnabled.
Enable Sequence Number Protocol org.glassfish.openesb.hl7.outbound.protocolproperties.seqnumenabled	java.lang.String	Specifies if sequence number protocol is enabled. “true” indicates enabled. The equivalent WSDL attribute is hl7:protocolproperties -> seqNumEnabled.
MSH Processing ID org.glassfish.openesb.hl7.outbound.protocolproperties.processingid	java.lang.String	Specifies the ProcessingID value against which the MSH-11-ProcessingID field in the received message is validated when validateMSH is set to “true”. Valid values are P (production), D (debugging), or T (training). The equivalent WSDL attribute is hl7:protocolproperties -> processingID.
Enable MSH Validation org.glassfish.openesb.hl7.outbound.protocolproperties.validatemsh	java.lang.String	Specifies if the MSH segment in the HL7 message is validated against initiation rules. “true” indicates enabled. The equivalent WSDL attribute is hl7:protocolproperties -> validateMSH.
Enable adding SFT Segment org.glassfish.openesb.hl7.outbound.protocolproperties.enablesft	java.lang.String	A toggle property to enable/disable SFT segment processing. The equivalent WSDL attribute is hl7:protocolproperties -> enabledSFT.
SFT Field — Software Vendor Organization org.glassfish.openesb.hl7.outbound.protocolproperties.softwarevendororganization	java.lang.String	Defines the Software Vendor Organization field (SFT-1-Software Vendor Organization) which identifies the vendor who is responsible for maintaining the application. The equivalent WSDL attribute is hl7:protocolproperties -> softwareVendorOrganization.
SFT Field — Software Certified Version Or Release Number org.glassfish.openesb.hl7.outbound.protocolproperties.softwarecertifiedversionorreleasenumber	java.lang.String	Specifies HL7 segment SFT-02, the Software Certified Version or Release Number. The latest software version number or release number for the sending system, helps to provide a more complete profile of the application that is sending or receiving HL7 messages. The equivalent WSDL attribute is hl7:protocolproperties -> softwareCertifiedVersionOrReleaseNumber.
SFT Field — Software Product Name org.glassfish.openesb.hl7.outbound.protocolproperties.softwareproductname	java.lang.String	Specifies HL7 segment SFT-03, the name of the software product that submitted the transaction. The software product name is a key component for identifying the sending application. The equivalent WSDL attribute is hl7:protocolproperties -> softwareProductName.
SFT Field — Software Binary ID org.glassfish.openesb.hl7.outbound.protocolproperties.softwarebinaryid	java.lang.String	Specifies HL7 segment SFT-04, the Software Binary ID. This property is available starting with HL7 version 2.5. Software Binary IDs are issued by a vendor for each unique software version instance. These IDs are used to differentiate between differing versions of the same software.Identical Primary IDs indicate that the software is identical at the binary level, but configuration settings may differ. The equivalent WSDL attribute is hl7:protocolproperties -> softwareBinaryID.
SFT Field — Software Product Information org.glassfish.openesb.hl7.outbound.protocolproperties.softwareproductinformation	java.lang.String	Specifies HL7 segment SFT-05, software product identification information. This may include a description of the software application, configuration settings, or modifications made to the software. The equivalent WSDL attribute is hl7:protocolproperties -> softwareProductInformation.
SFT Field — Software Install Date org.glassfish.openesb.hl7.outbound.protocolproperties.softwareinstalldate	java.lang.String	Specifies HL7 segment SFT-06, the Software Install Date. This is the date, in YYYYMMDDHHSS format, on which the submitting software was installed at the sending site. The equivalent WSDL attribute is hl7:protocolproperties -> softwareInstallDate.
MLLPv2.0 Retries Count On NAK org.glassfish.openesb.hl7.protocolproperties.mllpv2retriescountonnak	java.lang.String	Specifies the maximum number of retries on receipt of MLLP V2 negative acknowledgement. The equivalent WSDL attribute is hl7:protocolproperties -> mllpv2RetriesCountOnNak.
MLLPv2.0 Retry Interval org.glassfish.openesb.hl7.outbound.protocolproperties.mllpv2retryinterval	java.lang.String	Specifies the time duration to wait in milliseconds before each retry. The equivalent WSDL attribute is hl7:protocolproperties -> mllpv2RetryInterval.
MLLPv2.0 TimetoWait For ACK/NAK org.glassfish.openesb.hl7.outbound.protocolproperties.mllpv2timetowaitforacknak	java.lang.String	Specifies the time duration to wait in milliseconds for receiving MLLP V2 commit acknowledgement / negative acknowledgement. The equivalent WSDL attribute is hl7:protocolproperties -> mllpv2TimeToWaitForAckNak.

HL7 Binding Component Normalized Message Properties for Inbound Endpoints

The following table defines the HL7 Normalized Messages for inbound endpoints.

Table 9 HL7 NM Properties for Inbound Endpoints


Property Name	Type	Description and Use
Host org.glassfish.openesb.hl7.inbound.address.host	java.lang.String	A URL part, which specifies the connectivity information to connect to the HL7 external system. The equivalent WSDL attribute is hl7:address -> location (host).
Port org.glassfish.openesb.hl7.inbound.address.port	java.lang.String	A URL part, which specifies the connectivity information to connect to the HL7 external system. The equivalent WSDL attribute is hl7:address -> location (port).
Client Address org.glassfish.openesb.hl7.inbound.client.address	java.lang.String	Represents the client address and port information. This property has no equivalent WSDL attribute.
Enable Sequence Number Protocol org.glassfish.openesb.hl7.inbound.protocolproperties.seqnumenabled	java.lang.String	Specifies whether sequence number protocol is enabled or not. The equivalent WSDL attribute is hl7:protocolproperties -> seqNumEnabled.