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:

• Application Variables

• Application Configurations

• Dynamic Addressing Using Normalized Message Properties

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

• Enabling Dynamic Endpoint Configuration

• Using Normalized Message Properties in a BPEL Process

• 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 as the 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.

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

1. From the Design View diagram, select the activity with the process you want to edit.
2. Click Mapper to switch to the Mapper view of the BPEL process.
3. Expand the Variable you want to edit and its Properties file.
4. To dynamically configure an endpoint, first expand the /Properties/General node to expose the General Normalized Message Properties.
5. Enter values for the Message ID property and the Endpoint Name property.
6. 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.

7. Expand the /Properties/HL7 node to expose the HL7 Normalized Message Properties.
8. 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.
   
9. 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

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

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