Using Normalized Message Properties

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 are used to provide additional capabilities in Open ESB, such as:

• 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/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, for example, the message ID property, which can be utilized to uniquely identify or track a given message in the integration.

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 variables predefined NM properties. If the specific NM property you need is not currently listed, additional NM properties can be added.

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. From the Output pane, expand the Variable you want to edit and its Properties file.

   The Properties file contains the predefined Normalized Message (NM) properties.

   
   
4. To use a predefined NM Property, select the property and use it to build an expression or an assign.

Adding Additional Normalized Message Properties to a BPEL Process

If the specific NM Property you want is not listed, you can add additional NM properties.

There are two options available when adding NM Properties:

• Add NM Property Shortcut: This option typically supports simple type properties, in that it does not grant access to some data within the NM Property.

• Add NM Property: This option provides access to data within the NM property used to build expressions.

To Add a Normalized Message Property Shortcut to a BPEL Process

1. From the Output or Input panes of the BPEL Mapper, expand the node for the variable to which you want to add an NM property. Right-click that variable's Properties directory node and then select Add NM Property Shortcut.

   The Add NM Property Shortcut dialog box appears.

2. Enter the information for the new NM property into the Add NM Property Shortcut dialog box, as follows:

   • Property Name: The NM property name (see each binding component's documentation for available NM properties).

   • Display Name:The display name for the NM property. This is a user-defined name that appears in the Mapper tree. The display name is optional.

     
3. Click OK.

   The new NM property is added to the Mapper tree under the variables Properties directory. The property can now be used in assigns and to build expressions.

To Edit an NM Property Shortcut

1. To edit an existing NM property shortcut, right-click the NM property shortcut in the BPEL Mapper tree and then select Edit NM Property Shortcut.

   The Add NM Property Shortcut dialog box appears.

2. Edit the NM Property Name or Display Name, and click OK.

To Delete an NM Property Shortcut

1. To delete an NM property shortcut, right-click the property in the Mapper tree.
2. Select Delete NM Property Shortcut.

   The NM Property Shortcut is deleted.

To Add a Normalized Message Property to a BPEL Process

1. From the Output or Input panes of the BPEL Mapper, expand the node for the variable to which you want to add an NM property. Right-click that variable's Properties directory node and then select Add NM Property.

   The Add NM Property dialog box appears.

2. Enter the information for the new NM property in the Add NM Property dialog box, as follows:

   • Property Name: User-defined property name. This name is displayed in mapper tree and stored in WSDL file.

   • Type or Element:Displays the property type or element associated with the selected node in the Map Property To tree.

   • Associate property with message: To associate the new NM property with all variables of any message type select this checkbox.

   • Map Property To: The Map Property To tree displays all of the predefined NM properties. This is used to build a query or choose a property type.

     When you select a node within the property tree the Type or Element and Query fields are populated automatically. Valid endpoint nodes are displayed in bold.

   • New NM Property: Select the New NM Property checkbox to add a specific NM property, and enter the name of the property in the New NM Property field. The new NM property is added to the Map Property To tree.

   • Sync with tree:When this checkbox is selected, the Query field is automatically synchronized with the selected node in the Map Property To tree.

   • Query: Displays the query type associated with the selected node in the Map Property To tree.

     
3. Click OK. The new NM property name is added to the tree in the BPEL Mapper, and the NM property is stored in nmPropertiesDefinitions.wsdl as a pair of elements: <vprop:property> and <vprop:propertyAlias>
   

   The new NM property can now be used in assigns and to build expressions.

To Delete an NM Property

1. To delete a new NM property, right-click the property in the Mapper tree.
2. Select Delete NM Property.

   The property is deleted.

BPEL Code Generation Using NM Properties

Data copied from an NM property or an NM property shortcut generates code that is similar to the following:

<from variable="inputVar" sxnmp:nmProperty="org.glassfish.openesb.file
.outbound.dcom.username"/>

Data copied from WSDL properties based on NM property generates code that is similar to the following:

<from variable="inputVar" property="ns3:DemoNMProperty"/>

When properties and NM properties are used to build an expression, code similar to the following code is generated:

<from>concat(bpws:getVariableProperty('inputVar', 'ns3:DemoNMProperty'), 
sxnmp:getVariableNMProperty('inputVar','org.glassfish.openesb.file.outbound.dcom.
username'))</from>

An NM property used in a condition generates code that is similar to the following:

<condition>sxnmp:getVariableNMProperty('inputVar', 'my.nmProperty.boolean')</condition>

General Normalized Message Properties

Normalized Message properties are either General, available to all participating JBI components, or protocol/binding specific, used by a particular binding component. The following General NM properties are available to all binding components.

Table 1 General Normalized Message Properties

Binding Component Specific Normalized Message Properties

Binding components each have their own protocol specific Normalized Message properties. These include inbound and outbound specific, as well as general NM properties for each binding component.

For a list of binding component specific NM properties, refer to the following:

• File Binding Component NM Properties

• HTTP (SOAP) Binding Component NM Properties

• JMS Binding Component NM Properties