IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Enterprise Service Bus programming > Data Transformation

Message Element Setter and Data Handler mediation primitives

In addition to the BO Mapper, Mapping and Custom mediation primitives, there are other data transformation mediation primitives available within WebSphere ESB. These transformation primitives do not change the entire message structure of the SMO, they transform the content of a particular subsection of the message.

When transforming a subsection of a message, two mediation primitives that can be used are:

  1. Message Element Setter mediation primitive

  2. Data Handler mediation primitive
Both of these mediation primitives can change a subsection within the context, the headers, the body, or the attachments of the SMO. The Message Element Setter mediation primitive sets, deletes, or copies content into specified fields, or appends to an array of fields within a message. The Data Handler mediation primitive transforms native data to a business object, or vice-versa, so that it has a structure that can be accessed within the mediation flow component.


Message Element Setter mediation primitive

The Message Element Setter mediation primitive provides a simple mechanism for setting message content. It does not change the type of the message.

You can set, copy, append or delete message elements using statements containing XPath expressions. You can specify multiple statements in one Message Element Setter mediation primitive by setting multiple targets, with the changes carried out in the sequence specified.

You can set target message elements to a constant value, or to a value copied from a location in the input SMO. If the target message element you specify does not exist then it will be created in the SMO. You can also delete message elements if they are optional or repeating elements.


Example scenario

The fictional company Personal Holidays are making an internal service available to external clients using a web service interface and a mediation flow, as shown in Figure 1.

Figure 1. Message Element Setter in a mediation flow component

The external clients send in SOAP messages, through the web service export, that contain a SOAP header called PersonalHolidaysClient. The value of this header must be stored in the SMO correlation context so it can be used in the response flow but should not be passed to the internal service. Additionally the internal service must have a SOAP Header named PersonalHolidaysInternalHeader, which must be set to a value of EXTERNAL_CLIENT_SERVICE_CALL for all incoming messages from the external clients.

We can use a Message Element Setter primitive to achieve this by:

  1. Copying the value of the PersonalHolidaysClient SOAP header to the appropriate position in the correlation context.
  2. Override the PersonalHolidaysClient to be PersonalHolidaysInternalHeader by:
    1. Setting the name of the PersonalHolidaysClient SOAP header to PersonalHolidaysInternalHeader.
    2. Setting the value of the PersonalHolidaysInternalHeader SOAP header to EXTERNAL_CLIENT_SERVICE_CALL.

Figure 2 shows the properties view within Integration Designer, where the actions of the Message Element Setter primitive are set. Each statement has the additional information needed to perform the action. All of the statements have a target XPath expression identifying the target of the action.

Figure 2. Message Element Setter properties within Integration Designer


Data Handler mediation primitive

The Data Handler mediation primitive transforms a targeted section of a message. The Data Handler primitive is used to convert an element of a message from a physical format to a logical structure, or from a logical structure to a physical format. The source and target of the transformation are indicated by XPath expressions. The Data Handler mediation primitive can be used when you are trying to integrate services, and parts of the message have not been parsed. By transforming the native data in a message into a business object, that data can be used by other mediation primitives. The part of the message that is not referenced by the XPath expression is left unmodified. Figure 3 shows the data formats that can be transformed by a Data Handler mediation primitive. Additionally you can define and use your own data format transformation.

Figure 3. Data Handler Configuration

data handler configuration to show the data format transformation types" />


Example scenario

The fictional company My Airways outsource the supply of their airline meals to a fictional company called Flight Meals. My Airways specify that the ingredients of meals must be supplied to customers, should they request them. Flight Meals provide menuCourseIngredients information in a CSV format, as shown in the following XML: 

<menuCourseDetails>
	<menuCourseID>DessertABC1234</menuCourseID>
	<menuCourseDescription>Sticky Date Pudding served with Caramel Sauce</menuCourseDescription>
	<menuCourseIngredients>Dates,Butter,Sugar,Bicarbonate of Soda,Eggs,Flour, 	  Cream,Vanilla essence</menuCourseIngredients>
</menuCourseDetails>
My Airways process the menuCourseIngredients information into a business object format as shown in the following XML: 
<menuCourseDetails>
	<menuCourseID>DessertABC1234</menuCourseID>
	<menuCourseDescription>Sticky Date Pudding served with Caramel Sauce</menuCourseDescription>
	<menuCourseIngredients>Dates,Butter,Sugar,Bicarbonate of Soda,Eggs,Flour, 	  Cream,Vanilla essence</menuCourseIngredients>
	<ingredientsList>
		<ingredients>Dates</ingredients>
		<ingredients>Butter</ingredients>
		<ingredients>Sugar</ingredients>
		<ingredients>Bicarbonate of Soda</ingredients>
		<ingredients>Eggs</ingredients>
		<ingredients>Flour</ingredients>
		<ingredients>Cream</ingredients>
		<ingredients>Vanilla essence</ingredients>
	</ingredientsList>
</menuCourseDetails>

A Data Handler mediation primitive is used to transform data from a CSV format into the required business object. Figure 4.shows how a Service Invoke mediation primitive is used to call the Flight Meals Service Provider, to retrieve the menuCourseIngredients, containing the CSV formatted ingredients information from the Flight Meals Service Provider. The CSV formatted message is then passed to a Data Handler mediation primitive, which is able to transform the CSV data into a business object that can be used by the My Airways Service Provider.

Figure 4. Data Handler within a mediation flow component

data handler mediation primitive," />

Within Integration Designer, the source and target XPath expressions are specified for the Data Handler mediation primitive, and the CSVDataHandler, data format transformation is chosen. This is shown in Figure 5.

Figure 5. Data Handler in Integration Designer

Data Transformation