Mediation policy for target services: Constructing a dynamic mediation for WebSphere ESB V7 based on which target service has been selected

This article shows you how to use the extended mediation policy function in WebSphere ESB V7 to apply mediation policy conditionally, depending on the target service invoked, and how to attach and use mediation policies at target services, both at a service and an operation level. This article includes a scenario based on the service gateway pattern, an ideal pattern for target service mediation policies, and one that shows these mediation policies simplify the mediation flow.


Brian Hulse (, Senior Software Engineer, WebSphere Service Registry and Repository, IBM

Photo of Brian HulseBrian Hulse is a senior software engineer for WebSphere Enterprise Service Bus based in Hursley, United Kingdom. He has worked in software development at Hursley for 20 years, the last five of which have been in the SOA arena.

Callum Jackson (, Software Engineer, IBM

Photo of Callum Jackson Callum Jackson is a Software Engineer on the WebSphere ESB team at the IBM Hursley Software Lab in the UK. He has worked on the WebSphere ESB team since 2005, and before that he worked in Software Services on SOA applications for the telecommunications industry. You can contact Callum at

27 January 2010

Also available in Chinese Spanish


This article shows you how to use the extended mediation policy function provided in IBM® WebSphere® Enterprise Service Bus (hereafter called WebSphere ESB) V7. The article shows how to attach and make use of mediation policies at target services. The examples show how use mediation policies attached at a service level and at an operation level. The scenarios described are based on a service gateway pattern -- a pattern that lends itself to the use of target service mediation policies. Using mediation policies in a service gateway scenario leads to a simplification in mediation flow.

WebSphere ESB V6.2 introduced the ability to control the configuration of a mediation flow using mediation policy documents stored in WebSphere Service Registry and Repository (WSRR). For more information on this topic, see What's new in WebSphere ESB V6.2, Part 3: Mediation Policy. In WebSphere ESB V6.2, the mediation policies were referenced in WSRR via the SCA Module that contained the mediation flow in question; this can be termed the scope of the mediation policies. WebSphere ESB V7 extends the concept of scope to encompass the target service of the mediation flow. Moreover, it allows for the application of mediation policies at various target service scope points:

  • Service
  • Endpoint
  • Operation

These scope points allow for configuration of the mediation flow based conditionally on which service, endpoint, or operation is invoked. This article shows real-life examples of both the service and operation levels. The examples are based on a service gateway pattern, a powerful pattern with respect to mediation policies for target services. One can envision a gateway for numerous back-end services with a standard pattern of mediation functionality, logging, and transformation for example, with the logging and type of transformation dependent on the service or operation being called. In this way, you can have a single, simplified mediation flow, with mediation policies applied conditionally, rather than multiple flows or branches servicing the different targets.

WebSphere ESB V7 also introduced the ability to administer mediation policies in WSRR via Business Space widgets, which are referenced throughout this article.

Designing the flow

Both of the scenarios involve a gateway that fronts a couple of HR services, one dealing with applications for employment (Application) and the other with generalised HR queries (Employee). Each of the two services constructs an identifier for the request in a different fashion, and in this way, they require a different transformation to be applied in the mediation flow. Additionally, in the first scenario, there is a business need for all interactions with the Applications service to be logged for auditing purposes, whereas this is not needed for the Employee service. Logging can be done by having a single flow with a logging primitive, which can be enabled and disabled with a mediation policy, and an XLST primitive that can apply a different transformation for either service based on information in an externally stored mediation policy.

Interfaces and data types

Since this is a service gateway pattern, the interface used should be the Service Gateway interface:

Figure 1. Service Gateway interface
Service Gateway interface

Each of the target services are described below:

Figure 2. HR Application Service interface
HR Application Service interface
Figure 3. HR Employee Query interface
HR Employee Query interface

The referenced data types are:

Figure 4. Application data type
Application data type

The applicationID is built by the mediation flow by appending the dateTime field onto the applicant's surname:

Figure 5. Employee data type
Employee data type

The queryID is built by the mediation flow by appending the dateTime field onto the employee's employeeID:

Figure 6. HRInput data type
HRInput data type
Figure 7. HROutput data type
HROutput data type

Although the standard endpoint lookup mediation primitive could be used in this flow, it would require the mediation flow to provide the portType for the interaction, and in this respect, the Gateway Endpoint Lookup mediation primitive used in Action mode is a much better match for this usage pattern. In order to make the action-based routine work, a slight addition is required to the WSDLs describing the target services. In the WSDLs produced by WebSphere Integration Developer for the the target services, each operation is annotated with a soapAction attribute. For services generated in WebSphere Integration Developer, the default value is empty, but in these scenarios we will update it manually to enable us to use the Gateway Endpoint Lookup mediation primitive in Action mode. An example of the original WSDL is shown for one of the operations on one of the services:

Figure 8. Original soapAction attribute
Original soapAction attribute

In order to modify this WSDL, open the Java EE perspective and the WSDL representing the binding for the particular service. The change in perspective is needed since the binding WSDL is not shown in the Business Integration perspective. Modify soapAction so that it contains a string of the form operationName/portType, which in this case results in:

Figure 9. Modified soapAction attribute
Modified soapAction attribute

The order -- operation followed by portType -- is important, because it makes processing easier in the second scenario, an operation level mediation policy flow. Make this change for all four of the referenced operations in this scenario. You are now ready to construct the flow itself. As previously described, the flow uses the service gateway interface, and you will use only the requestResponse operation. The flow is very simple -- the reduced complexity resulting from the use of dynamic configuration by mediation policy:

Figure 10. Request flow
Request flow
Table 1. Summary of request flow mediation primitives
Primitive NameDescription
findEndpointByActionThis Gateway Endpoint Lookup mediation primitive extracts the target service information from WSRR based on the soapAction.
getPolicyThis Policy Resolution mediation primitive extracts the mediation policies associated with the target service selected by findEndpointByAction and places them in the message so that they can act upon the rest of the mediation primitives.
logMessageThis Message Logger mediation primitive logs the message under mediation policy control.
buildIdentifierThis XSLT mediation primitive constructs an identifier, used by the target service, from the message details. Which transform is used is controlled by mediation policy.
reassertMessageTypeThis Set Message Type mediation primitive reasserts the service gateway message prior to the callout to the target service.

The following sections explain the use of each of these mediation primitives. First, the Input Node needs some configuration.

Input Node

The message arrives in this mediation flow as a service gateway message, which means it is not typed to the target service. However, you need to examine the contents of the body in order to construct the identifier later in the flow. Consequently, you must inform the flow that a conversion to the particular message type is needed. This has the effect of parsing the inbound TextBody automatically into the concrete business object representation that would be expected in a strongly typed module. For this to be possible, all of the schema information needs to be available for the message types passing through the service gateway. A check box on the properties of the input node performs this function:

Figure 11. Input node properties
Input node properties


This mediation primitive has a number of modes of operation, but we require it to lookup endpoints by Action :

Figure 12. Gateway endpoint lookup properties
Gateway endpoint lookup properties

This mediation primitive is configured to use a particular WSRR instance, the definition for which needs to be set up in the WebSphere administration console. In this case, the default WSRR definition is used. For information on this task, see the WebSphere ESB V7 information center.


This mediation primitive also has a number of modes of operation. In this case you want it to extract the policies associated with the target service:

Figure 13. Policy Resolution properties
Policy Resolution properties

This mediation primitive is using the default registry definition. The registry definition must be the same as the one used in the Gateway Endpoint Lookup.


You need to make the messages log dependent upon the mediation policy, so you must promote the Enabled property of the mediation primitive. In this example, you have promoted the property with a group name of Audit, an alias of enabled, and a default value of false. These values will be seen later when a mediation policy is created to set the value to true for one of the services.

Figure 14. Message Logger Properties
Message Logger Properties


This is the second mediation primitive that will be controlled via mediation policy, so it requires the promotion of a property if it is to be dynamic. In this example, you promoted the Mapping File property with a group name of Transform, an alias of xslFile, and a default value of xlst/Employee.xsl. These will be seen later when a mediation policy is created to load a different xsl file for each of the services, thus allowing a different identifier for each service. You also need to create a different xsl file for each transformation. For information on this task, see the developerWorks article What's new in WebSphere ESB V6.2, Part 3: Mediation Policy.

Figure 15. XSLT properties
XSLT properties


By selecting Automatically convert the ServiceGateway message in the Input Node, you have effectively typed the message to be specific to the particular target service. However, the flow is still a service gateway flow, so you must reassert the message type back to a ServiceGateway message prior to calling the service:

Figure 16. Set Message Type properties
Set Message Type properties

Importing into WSRR

The flow is now ready for its interaction with WSRR. New in WebSphere ESB V7 is the ability to create and attach mediation policies using Business Space widgets, but before this, you need to make WSRR aware of:

  • The vocabulary of the mediation policy domains in this mediation flow (which in this case are the groups Audit and Transform).
  • The WSDLs defining the services, along with our soapAction annotations, so that the Gateway Endpoint Lookup can find them.

To do this you will need access to the WSRR administration console.

SCA Module

From the Business Integration perspective, select Export and use the Integration modules and libraries option followed by the Files for server deployment option to create an EAR file containing the SCA module which contains the mediation flow. Import this EAR file into the WSRR system to be used by the Policy Resolution and Gateway Endpoint Lookup mediation primitives in the mediation flow.

WSDLs and schemas

From the Business Integration perspective, select Export and use the WSDL and XSD option followed by selecting all of the WSDLs and XSDs used in the flow. Import these WSDLs into the same WSRR system as the SCA module. You are now done with the WSRR console; all other administrative work is done via Business Space.

Creating and attaching mediation policies

Prior to using Business Space to administer the mediation policies, the SCA Module must be installed on a WebSphere ESB (WebSphere Process Server) runtime system. Follow your local processes to install the SCA Module containing the service gateway mediation flow.

Open a Business Space supported browser at the address http://localhost:9080/BusinessSpace/ (using the address root appropriate for your runtime). The welcome page for Business Space will open. Create a new space to administer your mediation policies: select Actions => Create space. After supplying a suitable name for the new space, select Service Administration from the pull-down under Create a new space using a template. When the space has been created, select the Service Administration tab, which lets you create and attach new mediation policies. The left- hand widget is the Service Browser, which shows the services running on the runtime system. In this example, the two back-end services are tagged as:

  • Export1_EmployeeHttpService
  • Export1_ApplicationHttpService

You will attach mediation policies to these two services. In the following figure, the first service is expanded to show the different attachment points available, which appear under the label Mediation Policies:

Figure 17. Service Browser
Service Browser

You must select the WSRR definition before performing any mediation policy work. In this case, the WSRR definition is called radcliffe, which is how it will appear in the WebSphere administration console. The attachment points shown are explained in more detail in the following table:

Table 2. Mediation policy attachment points
Attachment NameScopeDescription
Export1_EmployeeHttpServiceService Any mediation policies attached at this scope level apply to all invocations of this service.
Export1_EmployeeHttpPortEndpoint Any mediation policies attached at this scope level apply to all invocations of the specific endpoint.
askHROperationAny mediation policies attached at this scope level apply to all invocations of the named operation.
addEmployeeOperationAny mediation policies attached at this scope level apply to all invocations of the named operation.

In the first scenario, you want mediation policies to be applied depending on which service is invoked, so you need to select the service level in the Service Browser, in this case Export1_EmployeeHttpService under the Mediation policies heading. Next, when the scope level is selected on the left-hand widget, the right-hand widget labeled Mediation policy administration indicates that it is loading attachments. Initially an empty list results as there are no mediation policies attached -- you will need to create them before attaching them. In the first scenario, the Employee service should have logging disabled, and even though this is the default value for the particular mediation primitive, create a mediation policy to control it in order to a dynamic change in strategy later without redeploying the flow.

Creating a policy attachment

Enter the name of the new policy attachment in the entry field labeled New policy attachment, which in this case is entered as EmployeeServiceAttachment -- use a meaningful name for the attachment. Then click Create:

Figure 18. Creating a policy attachment
Creating a policy attachment

The scope level where the attachment is being created is shown on the widget, which in this case is Service, along with the specific attachment point, which is Export1_EmployeeHttpService.

Creating a mediation policy

The next panel takes a few seconds to load as it needs to present which mediation policy group names are available in the modules in the runtime. It does this by cross-checking the modules against the same SCA modules in the referenced WSRR; this is one of the reasons why the SCA Module needs to be imported into WSRR as well as installed on the runtime system. Figure 19 shows that there are only two groups available here: Audit and Transform. It also shows which modules support these groups, since modules can support multiple groups, and groups can be available across multiple modules:

Figure 19. Creating a mediation policy
Creating a mediation policy

Once a group is selected, the widget loads all existing mediation policies in that group so that you can use an existing one or create a new one. This example uses the group Audit, and rather than use the default policy in this group, create a new one and enter the name AuditDisabled as the mediation policy name and click Next -- again, use meaningful names when creating mediation policies. To use an existing mediation policy, select Use existing, which causes the pull-down to display all of the mediation policies in the selected group on the WSRR system specified.

Adding an assertion

The next panel takes a few seconds to load as it needs to find the vocabulary (the list of assertions) available in the mediation policy group selected. There is a single assertion in the group Audit called enabled. This is exactly what was specified on the promoted properties of the mediation flow. For this mediation policy you want the value to be false. Figure 20 shows the panel with the assertion about to be added. Click Add Assertion, and the new assertion appears in the list. This panel also lets you add in gate conditions, which are not being used in this scenario since the conditionality involves target service and not message content.

Figure 20. Adding an assertion to a mediation policy
Adding an assertion to a mediation policy

The next figure shows our new mediation policy with our newly added assertion. The panel also shows:

  • Policy attachment name -- EmployeeServiceAttachment
  • Mediation policy name -- AuditDisabled
  • Scope level -- Service
  • Attachment point -- Export1_EmployeeHttpService
  • Assertions in this mediation policy -- enabled in group Audit

Click Save to create all of the documents in the referenced WSRR:

Figure 21. New assertion in a mediation policy
New assertion in a mediation policy

The widget returns to the original panel and now shows the policy attachment that you just created:

Figure 22. New policy attachment
New policy attachment

You have now attached a mediation policy that will disable logging for any invocations of the Employee service. There is still work to -- three further mediation policies to create and attach to support this scenario. The process for doing this is basically the same as described above -- here is a summary of all of the mediation policies required by this scenario:

Table 3. Scenario for service-based mediation policies
PolicyGroupAssertionAttachment Point (Scope)

With all of these mediation policies in play, whenever the Employee service gets called, there will be no logging, and xslt/Employee.xsl will be used in the transformation. Equally, whenever the Application service gets called, there will be logging and xslt/Application.xsl will be used in the transformation.

Extending to operation scope

The second scenario is based on the first and is used to show how mediation policies can be conditionally applied based on which operation is being called. The creation of the flow, annotation of WSDLs, export from WebSphere Integration Developer, import into WSRR, and install into the runtime steps are all the same. For this scenario, take the transformations to be the same as previously defined, since the creation of the identifier is more naturally tied to the service. However, change when logging is performed, as shown below:

  • registerApplicant on the Application service should have logging enabled
  • addEmployee on Employee service should have logging enabled
  • getApplicantStatus on the Application service should have logging disabled
  • askHR on Employee service should have logging disabled

The process is the same as described in the first scenario, except that when creating the logging policy attachments, select the relevant operation. For example, when creating a policy attachment for addEmployee:

Figure 23. Policy Attachment at Operation Scope
Policy attachment at operation scope
Table 4. Scenario for operation based mediation policies
PolicyGroupAssertionAttachment point (scope)

If this scenario is developed immediately after the first, you need to delete the policy attachments at the two service levels that control logging.

Deleting policy attachments

The figure below shows the previously created policy attachment at the service level for the service Employee. Select the attachment and move the cursor to the far right of the selection to reveal two icons. Select the pencil icon to open the attachment so that you can see what assertions and gate conditions apply. The cross icon deletes the policy attachment. To make the logging for this scenario completely operation driven, delete both of the service level attachments controlling logging:

Figure 24. Deleting a Policy Attachment
Deleting a Policy Attachment

Mediation flow using operation level mediation policies

The mediation flow is basically the same as the flow described above for service level mediation policies. One additional mediation primitive is needed: Policy Resolution needs to be informed which operation is active, and it does this by checking the Operation field in the SMOHeader. In the gateway pattern, this is the generalised operation requestResponse; the flow needs to take responsibility for supplying the name of the target service operation being called. This task is trivial, since you already know the operation; it is encoded in the Action in the form operationName/portTypeName. So place a Message Element Setter mediation primitive before the Policy Resolution mediation primitive to interpret the Action field and load the Operation field. The new flow looks like this:

Figure 25. Request flow for operation level mediation policies
Request flow for operation level mediation policies


The Message Element Setter simply copies the first part of the Action field into Operation field; both of these are in the SMOHeader:

Figure 26. Message Element Setter Properties
Message Element Setter Properties

The Policy Resolution mediation primitive acts upon this Operation field, extracting all of the mediation policies associated with it in WSRR. It also extracts and uses all of the other mediation policies that are relevant, such as the service level mediation policies.

The second scenario is a simple extension from the first, requiring the Policy Resolution mediation primitive to be informed of the operation in play. Beyond this, you can now configure the flow according to service or operation by simply changing the mediation policies via Business Space; the mediation flow does not need to be redeployed.


The introduction of target service-based mediation policy in WebSphere ESB V7 creates an extremely powerful tool that simplifies mediation flows, bringing dynamic configuration via external metadata stored in WSRR. This article showed you how to achieve a dynamic mediation flow and how the service gateway pattern lends itself to use of service and operation based mediation policy for this dynamic configuration.


Code sampleDummyWebServices_PI.zip25 KB
Code sampleHR_Operation_PI.zip127 KB
Code sampleHR_Service_PI.zip125 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Mediation policy for target services: Constructing a dynamic mediation for WebSphere ESB V7 based on which target service has been selected