Building Your Hello Mediation Project using IBM WebSphere Process Server 7 and Enterprise Service Bus 7

This article will help you build your first HelloWorld WebSphere Enterprise Service Bus (WESB) mediation application and WESB mediation flow-based application. This article will then give an overview of Service Message Object (SMO) standards and how they relate to building applications using an SOA approach. At the completion of this article, you will have an understanding of how to begin building, testing, and deploying WESB mediations including:

  • Overview of WESB-based programming fundamentals including WS-*? standards and Service Message Objects (SMOs)
  • Building the first mediation module project in WID
  • Using mediation flows
  • Deploying the module on a server and testing the project
  • Logging, debugging, and troubleshooting basics
  • Exporting projects from WID

WS standards

Before we get down to discussing mediation flows, it is essential to take a moment and acquaint ourselves with some of the Web Service (WS) standards that WebSphere Integration Developers (WIDs) comply with. By using WIDs, user-friendly visual interfaces and drag-and-drop paradigms, developers are automatically building process flows that are globally standardized and compliant. This becomes critical in an ever-changing business environment that demands flexible integration with business partners. Here are some of the key specifications that you should be aware of as defined by the Worldwide Web Consortium (W3C):

What are mediation flows?

SOA, service consumers and service providers use an ESB as a communication vehicle. When services are loosely coupled through an ESB, the overall system has more flexibility and can be easily modified and enhanced to meet changing business requirements. We also saw that an ESB by itself is an enabler of many patterns and enables protocol transformations and provides mediation services, which can inspect, modify, augment and transform a message as it flows from requestor to provider. In WebSphere Enterprise Service, mediation modules provide the ESB functionality.

The heart of a mediation module is the mediation flow component, which provides the mediation logic applied to a message as it flows from a service consumer to a provider. The mediation flow component is a type of SCA component that is typically used, but not limited to a mediation module. A mediation flow component contains a source interface and target references similar to other SCA components. The source interface is described using WSDL interface and must match the WSDL definition of the export to which it is wired. The target references are described using WSDL and must match the WSDL definitions of the imports or Java components to which they are wired. The mediation flow component handles most of the ESB functions including:

  • Message filtering which is the capability to filter messages based on the content of the incoming message.
  • Dynamic routing and selection of service provider, which is the capability to route incoming messages to the appropriate target at runtime based on predefined policies and rules.
  • Message transformation, which is the capability to transform messages between source and target interfaces. This transformation can be defined using XSL stylesheets or business object maps.
  • Message manipulation/enrichment, which is the capability to manipulate or enrich incoming message fields before they are sent to the target. This capability also allows you to do database lookups as needed.
  • If the previous functionalities do not fit your requirements, you have the capability of defining a custom mediation behavior in JAVA.

The following diagram describes the architectural layout of a mediation flow:


In the diagram, on the left-hand side you see the single service requester or source interface and on the right-hand side are the multiple service providers or target references. The mediation flow is the set of logical processing steps that efficiently route messages from the service requestor to the most appropriate service provider and back to the service requestor for that particular transaction and business environment. A mediation flow can be a request flow or a request and response flow. In a request flow message the sequence of processing steps is defined only from the source to the target. No message is returned to the source. However, in a request and response flow message the sequence of processing steps are defined from the single source to the multiple targets and back from the multiple targets to the single source. In the next section we take a deeper look into message objects and how they are handled in the mediation flows.

Mediation primitives

What are the various mediation primitives available in WESB?

Mediation primitives are the core building blocks used to process the request and response messages in a mediation flow.

  • Built-in primitives, which perform some predefined function that is configurable through the use of properties.
  • Custom mediation primitives, which allow you to implement the function in Java.
  • Mediation primitives have input and output terminals, through which the message flows. Almost all primitives have only one input terminal, but multiple input terminals are possible for custom mediation primitives.
  • Primitives can have zero, one, or more output terminals.
  • There is also a special terminal called the fail terminal through which the message is propagated when the processing of a primitive results in an exception.

The different types of mediation primitives that are available in a mediation flow, along with their purpose, are summarized in the following table:

Service invocation


Service Invoke

Invoke external service, message modified with result

Routing primitives


Message Filter

Selectively forward messages based on element values

Type Filter

Selectively forward messages based on element types

Routing primitives


Endpoint Lookup

Find potential endpoint from a registry query

Fan Out

Starts iterative or split flow for aggregation

Fan In

Check completion of a split or aggregated flow

Policy Resolution

Set policy constrains from a registry query

Flow Order

Executes or fires the output terminal in a defined order

Gateway Endpoint Lookup

Finds potential endpoint in special cases from a registry

SLA Check

Verifies if the message complies with the SLA

UDDI Endpoint Lookup

Finds potential endpoints from a UDDI registry query

Transformation primitives


XSL Transformation

Update and modify messages using XSLT

Business Object Map

Update and modify messages using business object maps

Message element setter

Set, update, copy, and delete message elements

Set message type

Set elements to a more specific type

Database Lookup

Set elements from contents within a database

Data Handler

Update and modify messages using a data handler

Custom Mediation

Read, update, and modify messages using Java code

SOAP header setter

Read, update, copy, and delete SOAP header elements

HTTP header setter

Read, update, copy, and delete HTTP header elements

JMS header setter

Read, update, copy, and delete JMS header elements

MQ header setter

Read, update, copy, and delete MQ header elements

Tracing primitives


Message logger

Write a log message to a database or a custom destination

Event emitter

Raise a common base event to CEI


Send a trace message to a file or system out for debugging

Error handling primitives



Stop a single path in flow without an exception


Stop the entire flow and raise an exception

Message Validator

Validate a message against a schema and assertions

Mediation subflow primitive



Represents a user-defined subflow

Service Message Objects (SMO)

The primary function of a mediation flow is to operate on a message between endpoints, where a service requestor and a service provider are those endpoints. However, this presents a problem. The first point is that a message can take on many different forms because the protocol used to send a message, whether JMS or Web services, can vary. Also, each message is different depending upon the interface and operation associated with the message and whether this is the request side or response side of the interaction between the requestor and provider.

The next point to understand is that within the mediation flow, mediation primitives are used to operate on the message. Mediation primitives examine and update the message contents and therefore must understand what is contained in the message. The solution is to provide mediation primitives with some kind of a common representation of a message, and that is what a Service Message Object does. SMOs provide a common representation of a message that accounts for differing protocols and differing interfaces, operations, and parameters that the message represents. SMOs are built using Service Data Object (SDO) technology. SDO uses a schema that describes the basic structure of an SMO which is composed of three major sections.

The body of the message represents the specific interface, operation, and parameters relevant to this message. The headers section of the message represents information about the protocol over which the message was sent. The context section represents data that is important to the internal logic of the flow itself. Each of these major sections of the SMO is examined in more detail in subsequent slides. The data within an SMO is accessed using SDO, specifically the SDO DataObject, which enables access using XPath, the generic DataObject APIs, and some SMO-specific APIs that are aware of the SMO schema.


The service requestor and service provider interact with the bus through the bindings for the exports and imports of the mediation service module. The data representing the message depends on the binding used for exports and imports. If the primitives in the mediation flow component had to support the data representation for all the various bindings, it would be difficult to implement primitives. For this reason, the first thing the runtime does is that it converts the binding-specific data into common data structure, called Service Message Objects (SMO).

The SMO interface extends the DataObject interface, which is defined by the Service Data Object (SDO), similar to other business objects used in WebSphere Process Server. SMO includes the message headers, message data (payload) and context information and provides an interface to access and modify the SMO data, including headers, payload, and context information. In addition, the SDO data can be accessed using the XPath reference mechanism. The mediation module input contains binding-specific data representation. The mediation module output import binding dictates the data representation that must be sent to the output message. As a result, there is a lack of consistency in data representation and if the mediation flow primitives had to handle all the different data representation, it would become a huge challenge. To solve this problem, the data from binding-specific interaction is converted to a common data structure called the Service Message Object (SMO).

If the mediation primitives in a message flow require a temporary area to save data for other primitives down the message flow or need data set in the request flow to be available during the response flow, context information is used as a scratch pad. There are two types of context information: Transient context, as the name suggests, is temporary and available only on the specific request flow or the response flow but is not carried from the request to the response flow, and is therefore stored in memory. Correlation context is the second type of context data that is available for the duration of the complete request/response flow. Data set in the request flow is available for all the primitives in the response flow. Any primitive can modify the context information and downstream primitives in the message flow will have access to that information. The context data are represented as data objects and the structure is inserted in the SMO structure at the start of the mediation flow.

Creating mediation modules

You now have an understanding of the basic concepts of mediation and mediation flows. Let's try implementing these concepts in a simple HelloMediationModule.

For this we shall build upon our example from the previous chapter. In the previous article, we had built a simple HelloProcess integration solution. We will use the HelloProcess requirements as the basis and will build a mediation flow based solution that will satisfy the following requirements:

  • It should be capable of getting user input and more specifically their first name, last name, and age
  • It should return a customized greeting based on their age
    • Ages 25 and younger it should return—"What's up < FirstName LastName>! Congrats on your first hello world mediation flow"
    • Ages 26 to 65 it should return—"Hey < FirstName LastName>! Congrats on your first hello world mediation flow"
    • Ages 65 and above it should return—"Greetings < FirstName LastName>! Congrats on your first hello world mediation flow"
  • The solution should be exposed through Web Services

If you remember, we used a XPath object within the BPEL to develop the logic to return the custom greeting message. In this example, we shall build this logic in a mediation flow using the message filter primitive along with the use of a correlation context and message element setter primitive we just learnt.

Creating the Hello Mediation Flow

In order to create Hello Mediation Flow,

  1. In a new WID workspace, create a new Integration Solution in WID, File | New | Integration Solution and name it Greeting_Solution.
  2. Import the GreetingLibrary
  3. Click on File | New and select Mediation Module from the context menu. Give the module the name HelloMediationModule and the name of the mediation component as GreetingsFlow as shown in the following figure:

  4. Specify the GreetingLibrary in the required libraries wizard screen and proceed to next.
  5. Make this mediation module part of the Greeting_Solution Integration Solution. Click on the Finish button.

Upon clicking Finish the mediation module gets created and the Assembly diagram opens for the new mediation module. On the canvas of this assembly diagram you will notice that the GreetingsFlow mediation flow component has been created. We will specify the HandleGreetingMessage as the interface on this mediation flow component.

This can be done by as shown in the following steps:

  1. Right-click on GreetingsFlow | Add... | Interface | HandleGreetingMessage. Click on the OK button, as shown in the following diagram:

  2. Right-click on HelloMediationModule | Generate Export... | Web Service Binding | SOAP1.1/HTTP. Click on the OK button, as shown in the following screenshot:<

  3. The Assembly Diagram should now look like the following screenshot:

Implementing the HelloMediationModule

  1. Right-click on HelloMediationModule. Select Generate Implementation and then select New Folder (or you can double-click on the component). Enter the name of the new folder as com.junglesea.solution.greeting.mediation and click on the OK button.
  2. This will open the mediation flow overview. Click on the returnGreeting operation and select Blank Mediation Flow, as shown in the following screenshot:

  3. The mediation flow editor should now be open.
  4. We will first use a "Message Filter" primitive to route the incoming message based on age value. continue with this bullet. In the palette of the mediation editor under Routing category, select and drag the Message Filter primitive onto the canvas. Rename the message filter primitive to AgeBasedFilter by clicking on the MessageFilter1 text below the component, as shown in the following screenshot:

  5. Message Filter primitive is used to route messages to target based on a pre-defined condition or filter. In our example, we will use this primitive to check the age in the incoming message and accordingly route the message to one of the three custom mediation primitives that will print the response greeting in Chapter 6, Mediations Fundamentals covers more in-depth details.

  6. Select AgeBasedFilter and open Properties, and select the Terminal tab on the left-hand side. Rename the Output terminal match1 to LessThan25. Right-click on Output terminal (shown in the following figure) and select Add Output Terminal, and add one more output terminals named MoreThan25LessThan65 as shown in the following screenshot:

  7. Wire the Input node to the AgeBasedFilter primitive.
  8. From the palette of the mediation editor under the Transformation category, select and drag the Custom Mediation primitive on to the canvas. Name this primitive SayGreetingWhatsUp. Repeat the same and create two more custom mediation primitives named SayGreetingWhatsHappening and SayGreetingGoodDay.
  9. Wire the AgeBasedFilter primitive default terminal to the SayGreetingGoodDay custom mediation primitive . Similarly wire LessThan25 and MoreThan25LessThan65 terminals to the SayGreetingWhatsUp and SayGreetingWhatsHappening custom mediation primitives respectively.
  10. Now let’s specify the age based message filtering patterns. Select the AgeBasedFilter primitive and open Properties and select the Details tab on the left-hand side. Click on the Add button as shown in the following screenshot:

  11. In the Add/Edit properties dialog box enter the pattern /body/returnGreeting/inputPartyInfo/Age[self::node()<=25].
  12. As shown in the following screenshot select Terminal name as LessThan25 and click on the Finish button.

  13. Repeat the preceding steps to add the /body/returnGreeting/inputPartyInfo/Age[self::node()>25 and self::node()<=65] matching pattern to the MoreThan25LessThan65 terminal.
  14. We will define a correlation context named greetingMessageCtx to store the greeting message so that it can be used to hold the greeting message and can be mapped to the response message – outputGreetingMessage. Correlation context’s are for passing values from the request flow to the response flow inside a mediation flow. Think of them as temporary variables that are accessible in both the request and response flows with a mediation flow.

  15. Then specify within the custom mediation primitives the greeting messages to return. Go to SayGreetingGoodDay primitive and switch to the Visual implementation model and add the logic as shown in the following figure. As you can see we use the append text standard utility function to create the response message and then store it in the greetingMessageCtx correlation context we defined in the previous step.

  16. Repeat the same steps for the SayGreetingWhatsHappening and SayGreetingGoodDay custom mediation primitives as shown in the following screenshot:

  17. From the palette of the mediation editor under Service Invocation category, select and drag the Callout primitive on to the canvas. A callout node is an end point in the request flow. It sends the processed message to the target operation and in our case this will be sent back as the response. Wire the output of the SayGoodDayGreeting custom primitive and go to the Callout node. If you look you will see a response flow that will get added when you add the Callout. Repeat the same for the SayGreetingWhatsUp and SayGreetingWhatsHappening custom primitives.
  18. Go to the response flow and add a Message Element Setter primitive (that will copy the value of the greeting from the correlation context to the response element) in between the callout response and input response. Your mediation response flow will look as shown in the following screenshot.

Congratulations! You have now created your first mediation module. We will now unit test the mediation flow.

Deploying the modules

You will now deploy your HelloMediationModule on your WebSphere Process Server UTE environment (or the WESB server if you have it set up). In the Server view,

  1. Click on the Servers tab, and start the WPS server by clicking on the green play button and wait for the server to start. This may take a few minutes.
  2. Right-click on WebSphere Process Server v7.0, select Add and Remove Projects. Select HelloMediationModuleApp, and then click on Add | Finish. The HelloMediationModule will now get deployed and published on the WebSphere Process Server. You will be able to verify this by seeing it listed under WebSphere Process Server v7.0, as shown in the following screenshot:

Executing the modules

After deploying the modules, the next step is to execute the modules. Similar to how we did in the previous chapter, we will use the integration test client to unit test the HelloMediationModule module and more specifically test the interface operations of the GreetingsFlow mediation flow component.

  1. Right-click anywhere in the assembly diagram and select Test Module. This will bring up the Integration Test Client editor. Enter appropriate values and press the play button that will execute the module and you will be able to see the greeting message depending on the age you entered.
  2. In the following figure the request values and the appropriate response messages are shown when the mediation module is executed.


This article gave an overview of WESB-based programming fundamentals including Service Message Objects (SMO) and Mediation Flows. This discussion gave the fundamentals to build our first mediation flow component. Instructions were provided to create, implement and assemble the HelloMediationFlow. This mediation module was deployed on the server and unit tested using the WID Unit Test Environment.

You've been reading an excerpt of:

Application Development for IBM WebSphere Process Server 7 and Enterprise Service Bus 7

Explore Title