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 IBM® Business Process Manager. 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:
- Message Element Setter mediation primitive
- Data Handler mediation primitive
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:
- Copying the value of the PersonalHolidaysClient SOAP header to the appropriate position in the correlation context.
- Override the PersonalHolidaysClient to
be PersonalHolidaysInternalHeader by:
- Setting the name of the PersonalHolidaysClient SOAP header to PersonalHolidaysInternalHeader.
- 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
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><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
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