This document provides a guide for developing mediation flows using the WID (Websphere Integration Developer) tool. It covers various mediation primitives such as the trace primitive for debugging, custom mediation primitive for implementing custom logic, message filter primitive for conditional routing, and others. It also describes how to use inbound adapters like flat file and JDBC adapters to integrate with external systems. The chapters provide step-by-step instructions on how to configure and use each primitive in a mediation flow.
3. WID Development Guide
Revision History
Name Date Summary Of Changes Version
Ravi, Reddy 03/18/2011 Initial creation of document. 1.0
4. WID Development Guide
Chapter 1 Mediation flows overview
Mediation flows intercept and modify messages that are passed between existing services
(providers) and clients (requesters) that want to use those services. They are most
commonly used for transforming data and accessing header information, such as JMS,
MQ
Introducing mediation flows between services enables you to process the messages that
are being passed between these services. A message is a communication sent from one
application or service to another application or service. Mediation flows provide the logic
that processes the messages. For example, mediation flows can be used to find services
with specific characteristics that a requester is seeking and to resolve interface differences
between requesters and providers. For complex interactions, mediation primitives can be
linked sequentially. Typical mediations include:
• Transforming a message from one format to another so that the receiving service
can accept the message
• Conditionally routing a message to one or more target services based on the
contents of the message
• Augmenting a message by adding data from a data source
Development Steps
• Create a mediation project in WID tool.
• Create a MemberBO with the properties of 1) id 2) firstName 3) lastName
• Create an input service interface with “memberRegister” operation and set the
request parameters to the service operation.
• Create an output service interface with “memberDetails” operation and set the
request parameters to the service operation.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
* Note: See below images (figures) for above steps.
6. WID Development Guide
• Once done with the above steps deploy and start the application on server (WPS/
WESB)
• Right click on mediation box in assembly diagram select the “Test Component” in
the panel and pass the member information and see the output information by
putting debug(system out) statements in *serviceImpl class.
7. WID Development Guide
Chapter 2 Trace Primitive
Trace mediation primitive to develop and debug mediation flows, and to specify trace
messages to be logged to the server logs or to a file. The trace messages can contain
service message object (SMO) message content and other information about the
mediation flow.
Trace mediation primitive has one input terminal (in), one output terminal (out) and one
fail terminal (fail). The in terminal is wired to accept a message and the other terminals
are wired to propagate a message. The input message triggers the writing of a trace
message and if the tracing is successful, the out terminal propagates the original message.
If an exception occurs during the processing of the input message, the fail terminal
propagates the original message, together with any exception information.
Usage
Trace mediation primitive to write your own trace messages to help with developing and
debugging mediation flows.
Trace can use the destination property to determine where a trace message is written to:
either the server system logs, the User Trace log file, or to a specified file.
Development Steps
• Create a mediation project in WID tool.
• Create an input service interface with “memberRegister” operation and set the
request parameters to the service operation.
• Create an output service interface with “memberDetails” operation and set the
request parameters to the service operation.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
• Drag the trace primitive from Trace palette into mediation flow and configure
trace properties.
* Note: See below images (figures) for above steps.
9. WID Development Guide
Chapter 3 Custom Mediation Primitive
Custom Mediation primitive to implement your own mediation logic in Java code. The
primitive combines the flexibility of a user-defined mediation primitive, with the
simplicity of a pre-defined mediation primitive. You can add new terminals and create
your own properties, and this allows you to create complex transformations and routing
patterns.
Usage
Custom Mediation primitive has one input terminal (in), one output terminal (out), and
one fail terminal (fail).
The input terminals are wired to accept a message; the output and fail terminals are wired
to propagate the message. The input message is passed as the input parameter to the Java
code. If the operation returns successfully, the response from the Java code is propagated
to an output terminal. If the operation returns unsuccessfully, the fail terminal propagates
the original message,
Development Steps
• Create a mediation project in WID tool.
• Create an input service interface with “memberRegister” operation and set the
request parameters to the service operation.
• Create an output service interface with “memberDetails” operation and set the
request parameters to the service operation.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
• Drag the custom mediation primitive from Transformation palette into mediation
flow and configure primitive properties.
* Note: See below images (figures) for above steps.
11. WID Development Guide
Chapter 4 Message Filter Primitive
The Message Filter mediation primitive uses XPath expressions to allow you to direct
messages, which meet certain criteria, down different paths of a flow. The Message Filter
mediation primitive has one input terminal (in), one fail terminal (fail), and multiple
output terminals, (one of which is the default terminal). The in terminal is wired to
accept a message and the other terminals are wired to propagate a message.
Usage
You can use the message filter primitive to check that the inbound message meets some
criterion. If the criterion is not met you can raise a fault using the Fail mediation
primitive, or send an error response.
The message filter mediation primitive lets different messages take different paths. For
example, a message might need forwarding to different service providers based on the
request details.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the message filter primitive from Routing palette into mediation flow and
configure primitive properties.
• Configure the properties for message filter primitive; under terminals create two
new output terminals memberSuccess and memberFailure.
• Under details (properties) configure the newly created terminals for example
1) memberSuccess used filter condition if input member id is >= 1001 it will
route the message to SuccessTransformation.
2) memberFailure used filter condition if input member id is < 1000 it will route
the message to FailureMediation.
* Note: See below images (figures) for above steps.
13. WID Development Guide
Chapter 5 Message Logger Primitive
The Message Logger mediation primitive can store messages in a relational database or
in other storage mediums if you use the custom logging functionality. The Message
Logger mediation primitive logs messages to a relational database using an IBM-defined
database schema (table structure). It can write to other storage mediums, such as flat files,
through the use of the custom logging facility.
The Message Logger mediation primitive logs an XML transcoded copy of the service
message object (SMO). The default behavior is to log just the message payload but the
mediation primitive can be configured to log the complete SMO, or a part of the SMO
defined by an XPath expression. Along with the message contents the mediation
primitive also logs a timestamp, the message identifier, the primitive instance name, the
mediation module instance name and the SMO version number.
Usage
You can use the Message Logger mediation primitive to store messages that you process
later. The logged messages can be used for various purposes. For example, you could use
the logged messages for data mining, message replay or for auditing.
Because the data is logged as XML it can be processed by any XML-aware application.
Many databases, including DB2, provide built-in capabilities to handle XML contained in
a database column. Each Message Logger mediation primitive must have a Handler
implementation class specified. If you have multiple Message Logger mediation
primitives they can either use the same Handler implementation class or any number of
appropriate Handler implementation classes. You can, optionally, provide Formatter
implementation classes, Filter implementation classes, or both.
By default, the default Handler implementation class logs every message to a file stored
in the system temporary directory as defined by the java.io.tmpdir system property The
file will be called MessageLog.log
• On a Unix system typically /tmp or /var/tmp
• On a Windows C:Documents and Settings<user>Local SettingsTemp.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the message logger primitive from tracing palette into mediation flow and
configure primitive properties.
* Note: See below images (figures) for above steps.
15. WID Development Guide
Chapter 6 Flow Order Primitive
You can use the Flow Order mediation primitive to customize the flow by specifying the
output terminals to be fired. The Flow Order mediation primitive does not change the
input message.
The Flow Order mediation primitive has one input terminal (in) and any number of
output terminals. The in terminal is wired to accept a message and the other terminals are
wired to propagate a message. The output terminals are fired in the order that they are
defined on the primitive, with each branch completing before the next starts. Each output
terminal is fired with an unmodified copy of the input message.
Usage
You can use the flow order mediation primitive anywhere that you want to branch a flow.
A named output terminal is created for each branch. Each branch of the flow is completed
before the next terminal is fired.
The only exception to this rule is that if an Asynchronous Service Invoke mediation
primitive is reached, the service is called but the flow order does not wait for the service
invocation to complete before moving on to the next branch.
If an exception is thrown by any of the down stream mediation primitives and they do not
handle it themselves (for example, via their fail terminal), any remaining flow branches
are not fired.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the flow order primitive from routing palette into mediation flow and
configure primitive properties.
• Create custom mediation primitives for each output terminals of flow order
primitive for logging to test the terminals are firing out or not.
• You can verify the outputs in the console after running an integration test of the
mediation with in WESB.
* Note: See below images (figures) for above steps.
17. WID Development Guide
Chapter 7 FanOut Primitive
The Fan Out mediation primitive lets you iterate through a single input message, that
contains a repeating element, and store each instance of the repeating element in the
service message object (SMO) context. The Fan Out mediation primitive does not change
the input message.
Default mode sends the entire input message once. Generally, the default mode is needed
because a Fan In mediation primitive requires a preceding Fan Out mediation primitive.
Iterate mode lets you iterate through a single input message that contains a repeating
element. Every occurrence in the repeating element, which you specify using an XPath, is
processed. The Fan Out mediation primitive has one input terminal (in), two output
terminals (out and no Occurrences), and a fail terminal (fail). The in terminal is wired to
accept a message and the other terminals are wired to propagate a message..
Usage
Fan Out to broadcast the responses (message) into different service paths i.e. into
multiple output messages. For example, customer order information can broadcast into
shipping and billing services.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the fan-out primitive from routing palette into mediation flow and configure
primitive properties.
• Fan-out primitive broadcast the message to difference service (Member, Provider
and Pharmacy services) callouts with in mediation flow.
• You can verify the outputs in the console by placing debug statements in service
*Impl classes after running an integration test of the mediation with in WESB.
* Note: See below images (figures) for above steps.
19. WID Development Guide
Chapter 8 FlatFile Inbound Adapter
Flat File inbound adapter can create integrated processes that include the exchange of
data with the local file system, without special coding.
Usage
Flat File adapter to read data from a file in the local file system, use it in an application
on websphere process server (WPS) or websphere enterprise service bus (WESB), and
send it back to the local file system. You can also use the adapter to poll a directory in
the local file system for new files and send them to an application for processing.
The adapter can be used to read and write to any type of file stored in the local file
system. It can:
• Create new files
• Append to or overwrite existing files
• Retrieve the content of a given file, retrieve a list of file names in a directory, or
delete a file
• Check whether a particular file exists
• Poll a directory for new files and send them to an application for processing
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the flat file inbound adapter into assembly diagram and set the following
base properties like.
Event Directory Path,
Archive Directory Path (It’s not mandatory),
File Type Patterns.
• Flat File inbound adapter uses the IBM FlatFile object.
• Create a service partner to print the input file content.
• Note: See below images (figures) for above steps.
21. WID Development Guide
Chapter 9 JDBC Inbound Adapter
JDBC inbound adapter can create integrated applications that include the exchange
of information with a database; it enables communication between an application
running on Websphere Process Server or Websphere Enterprise Service Bus and a
database. By using the adapter, an application can send requests (read, create, update,
or delete) to the database, as well as receive events from the database, often without
the need for SQL code.
Usage
The adapter provides a standard interface that integrates with diverse database software
vendors and versions; it supports any database server with a Java™ Database
Connectivity (JDBC) driver that supports the JDBC 2.0 or later specification. Examples
of such servers include IBM® DB2®, Oracle, Microsoft® SQL Server, Sybase, Derby,
and Informix®.
The adapter uses business objects to exchange data between the application and the
database, so the application does not need to use the JDBC application programming
interface (API). Business objects are containers for application data that represent
business functions or elements, such as a database table or the result of an SQL query.
The adapter understands the data format provided by the application, and can process the
data, perform the operation, and send the results back in that format.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the JDBC inbound adapter into assembly diagram and set the following base
properties like JDBC Driver Type and Connection URL
• IDE pops up to browse the schema to select the table or view to generate the
business objects.
• JDBC inbound adapter shows the options for the operations like
Create
Update
Delete
• A service interface gets created based on the selected operations from above step.
* Note: See below images (figures) for above steps.
23. WID Development Guide
Chapter 10 Message Element 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 change,
add or delete message elements by setting the mediation primitive properties. If you
want multiple message changes you can set multiple targets. Multiple target elements
are set sequentially, in the order in which they are specified; this means that elements
can build on each other.
You can set target elements to a constant value, or to a value copied from somewhere
in the input service message object (SMO). If a target element you specify does not
exist, it is created in the SMO. You can also delete message elements, if they are
optional or repeating elements.
Usage
It is often useful to combine the Message Element Setter mediation primitive with other
mediation primitives. For example, you can use the Message Element Setter mediation
primitive if you need to manipulate data, before or after the Database Lookup mediation
primitive is invoked.
.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the Message Element primitive from routing palette into mediation flow and
configure primitive properties.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
* Note: See below images (figures) for above steps.
25. WID Development Guide
Chapter 11 Event Emitter Primitive
The Event Emitter mediation primitive sends out events, during a mediation flow.
Because the events are generated in the form of Common Base Events (CBE) they
have a standard XML-based format. The events are sent to a Common Event
Infrastructure (CEI) server. For information on CEI resources and services refer to
the runtime product documentation and runtime online help.You can decide whether
generated events contain the message being processed, or not.
If you set the Root property, you can generate events that contain all or part of the
message being processed. The Root property is an XPath expression that specifies
the section of the Service Message Object (SMO) that is included in the CBE. The
Root property can specify the complete SMO, a sub tree or a leaf element.
Note: at run time, if the Root value does not match any of the elements in the SMO,
the message being processed is not included in the generated event. If you do not set
the Root property; any generated events do not contain the message being processed.
Usage
Use the Event Emitter mediation primitive to emit significant business events from inside
a mediation flow. The Event Emitter mediation primitive has one input terminal (in), one
output terminal (out) and a fail terminal (fail). The in terminal is wired to accept a
message and the other terminals are wired to propagate a message. The out terminal
propagates the original message. If an exception occurs during the processing of the input
message, the fail terminal propagates the original message, together with any exception
information contained in the fail Info element.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the Message Element primitive from routing palette into mediation flow and
configure primitive properties.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
* Note: See below images (figures) for above steps.
27. WID Development Guide
Chapter 12 Database Lookup Primitive
The Database Lookup mediation primitive can add to, or change, messages. It does
this using information from a user-supplied database. This mediation primitive looks
up values from a database and stores them as elements in the message. The
information obtained from the database might need converting to the correct type to
be stored in the message. This is specified using the Message value type property. If
the information obtained from the database cannot be converted into the type
expected by the message, then an exception occurs.
If a message element already exists in the message then the old value is overwritten
with the new value. If the new value is not compatible with the element type defined
by property Message value type, then an exception occurs. The Database Lookup
mediation primitive needs various database information, including a key. The key is
found using a property called Key path. If the Key path key does not exist in the
input message, then an exception occurs.
The Database Lookup mediation primitive has one input terminal and three output
terminals. The input terminal is wired to accept a message and the output terminals
are wired to propagate a message. One output terminal is used if the Key path key is
located both in the message and the database. In this case, the information obtained
from the database is stored in the message and the updated message is propagated.
Another output terminal is used if the Key path key is found in the message but not
in the database. In this case, the original message is propagated unchanged. The last
output terminal is used for failure output. If an exception occurs during the
processing of the input message, then the fail terminal propagates the original
message, together with any exception information
Usage
You can use the Database Lookup mediation primitive to ensure information in a
message is up-to-date. You can use the Database Lookup mediation primitive to add
information to a message, using a key contained in a message. For example, the key
could be an account number.
It is often useful to combine the Database Lookup mediation primitive with other
mediation primitives. For example, you might use an XSLT mediation primitive to
manipulate data, before or after the Database Lookup is invoked.
Development Steps
• Follow same steps from previous chapters for creating the mediation in WID tool.
28. WID Development Guide
• Drag the Database Lookup primitive from transformation palette into mediation
flow and configure primitive properties.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
* Note: See below images (figures) for above steps.
29. WID Development Guide
Chapter 13 WTx Primitive
The WTx Map primitive is a component of the Websphere Transformation Extender
for Websphere Enterprise Service Bus (Websphere ESB).Within a Websphere ESB
mediation flow, a series of steps is used to process a message. A mediation flow node
performs each step. The WTX Map primitive is a mediation flow primitive that you
can use in mediation flows. It runs a Websphere Transformation Extender map within
a mediation flow. The WTX Map primitive uses a service message object (SMO) as
its input, runs a Websphere Transformation Extender map that you specify, and
creates one or more service message objects as its output.
The map that the WTx Map primitive runs can either is a compiled map that is
redeployed to the server, or a source map that is compiled when the mediation flow
is built and deployed as part of project deployment. The map can have multiple input
cards, but the WTx Map primitive only has a single input terminal.
The service message object, which arrives at the input terminal, might be complex.
Specific data paths, both simple and complex, might be routed to specific input
cards. You can specify /, /body,/headers, or browse for your own XPath expression. If
a complex path is routed to an input card, the input card should contain the
corresponding XML schema. If a simple path, such as the path to a single string
element, is routed to an input card, the card should contain a standard Websphere
Transformation Extender type tree; the type tree is used to parse the input data.
Any cards that did not receive a message obtain data from the adapter that is
specified on them. The map can have multiple output cards. Select which output
cards to connect to other primitives in the mediation flow. If the output terminal for
an output card is connected, a service message object is built, and propagated down
the mediation flow. The data produced by each connected output card is sent to a
specific data path in the service message object its terminal generates. If the output
terminal for an output card is not connected, the data is sent to the adapter that is
specified on the card.
The WTx Map primitive is contained in the Websphere Transformation Extender
drawer of the Websphere Integration Developer mediation flow palette. Use the
mediation flow palette to add WTx Map primitives in the mediation flows you are
creating in the Mediation Flow editor. Drag primitive objects from the palette onto
the Mediation Flow editor, and create connections, also called wires, between two
primitives.
The WTx Map primitive is not an SCA export, and can not be used to trigger the
execution of the mediation flow.
Development Steps
30. WID Development Guide
• Follow same steps from previous chapters for creating the mediation in WID tool.
• Drag the wtx primitive from websphere wtx palette into mediation flow and
configure primitive properties.
• Configure the compiled maps in details properties.
• Configure the input and output map cards to appropriate business objects.
• Drag and drop the java primitive in assembly diagram name and configure the
primitive with output service interface and join the mediation and primitive boxes
in assembly diagram.
• Select java primitive and right click on primitive and implement the interface by
selecting “Generate Implementation” in the panel.
• Double click on mediation box in assembly diagram and go inside the mediation
and join the input and output service partners.
* Note: See below images (figures) for above steps.