This article introduces the concept of mediation policies when building mediation flows to use the dynamic configuration capabilities in IBM® WebSphere® ESB V6.2. It describes how default mediation policies are created by WebSphere Integration Developer to control the default configuration of a mediation flow, and how these policies are represented by and extracted from WebSphere Service Registry and Repository. It also shows you how to use WebSphere Service Registry and Repository to author new mediation policies to be used in a mediation flow.
The power of mediation policies lies in enabling a single mediation flow to be used with multiple configurations, when previously each configuration would have required a separately deployed flow. Equally, mediation policy gives real administrative power in controlling configuration in a truly dynamic fashion.
The article describes the concepts of a mediation policy, its form, and how it is created, then uses a realistic example to show each step in the process from authoring a new mediation policy to using it in a flow.
Mediation policy concepts
WebSphere ESB V6.2 enables you to define dynamic configurations in the form of mediation policy documents, which can be loaded by a mediation flow in order to configure it. Additionally, these mediation policies can be conditionally loaded depending upon message context, giving a flexible mechanism to construct a single mediation flow that can exhibit multiple behaviours, based on the number of mediation policies available to it.
Prior to the introduction of mediation policies, a mediation flow could be controlled only by using promoted properties. Any property promoted from a mediation flow is visible in the administrative console and can be changed so that the flow configuration is changed. Any changes to promoted properties in the administrative console affect all of the flows that reference the properties, and the change is permanent within the deployed application. New to WebSphere ESB V6.2 is the concept that any property that can be promoted is available for dynamic update via mediation policy, but any changes that are affected via policy control only have a lifetime of the current invocation of the flow. New to promoted properties in WebSphere ESB V6.2 is the concept of a group, which enables promoted properties concerned with a common area of interest to be tagged with a common and descriptive identifier.
Promoted properties can be considered as points of variability within any mediation flow, with the mediation policies used to define what values are used at those points of variability. Mediation policies use the WS-Policy format and there is a simple mapping between the concepts used in WS-Policy and those defined by WebSphere ESB in promoted properties.
As described above, all promoted properties can now be gathered into groups. A promoted property group maps directly to a policy domain. A domain is typified by a unique namespace,
which is constructed from the group name of promoted property, taking the form:
<GroupName> is the name of the promoted property group.
A policy consists of a number of assertions that define the values of concepts defined within the particular policy domain. In the case of mediation policies, an assertion is a representation of the promoted property, the name being the alias name of the promoted property it represents. For example, considering the following promoted property:
Figure 1: Mapping file promoted property
Figure 2: Mediation policy representation
Figures 1 and 2 show the relationship between promoted property fields and mediation policy fields. The promoted property called
XSLFile within the group
AddressServices is mapped directly to the mediation policy assertion called
XSLFile in the domain with the xml tag
sibx, which translates as:
In this example, the mediation policy takes the same value for the assertion as the promoted property. However, it should be stressed that both WebSphere Integration Developer and WebSphere Service Registry and Repository help in the creation of mediation policies, so you do not need to be aware of the exact form of the XML. So far the discussion has focused on the relationship between promoted properties and mediation polices; it is now time to consider how WebSphere ESB V6.2 uses mediation policies.
Extraction and propagation of mediation policy
WebSphere ESB V6.2 has introduced two new concepts to enable the use of dynamic overrides in a mediation flow: a new mediation primitive called the Policy Resolution primitive, and a new context area of the Service Message Object, called the Dynamic Property Context.
Policy Resolution primitive
The Policy Resolution primitive:
- Allows for the association of parts of the message with policy condition names, which is used in calculating which mediation policies apply to the current message. An example is shown in Figure 8 below.
- Finds the mediation policies that apply to the current flow in WebSphere Service Registry and Repository.
- Resolves all of these mediation policies into a single mediation policy.
- Loads the single mediation policy into the Dynamic Property Context.
It is the use of the Dynamic Property Context that allows mediation primitives to be dynamically configured. Consequently, this primitive should be used at the start of a mediation flow; allowing all primitives that follow it to be dynamically configured.
Dynamic Property Context
As part of WebSphere ESB V6.2, promoted properties can now be overridden based on values in the Dynamic Property Context. This contains groups of
each one describing a group of name/value pairs. Each
propertySet is typified by a group, corresponding to the group of the promoted property to be overridden.
The name of the property corresponds to the alias name of the promoted property, with the value being the override value for the promoted property.
Figure 3: Dynamic Property Context
Figure 3 shows the values used in the Dynamic Property Context for the override of the XSL file used for the
formatAddress promoted property.
Default mediation policy creation
With WebSphere Integration Developer and WebSphere ESB V6.2, whenever a deployment artifact containing promoted properties is created, the mediation policy representation of those properties is also created and packaged with the deployment artifact. This may involve a number of policies, since one is created to represent each group mentioned in the promoted properties. These mediation policies are an alternative representation of the configuration of the promoted properties in the flow, and are referred to as the default mediation policies. These default mediation policies can be associated with an SCA module in WebSphere Service Registry and Repository, so that promoted properties can be controlled via values expressed in these policies and not the values presented in the administrative console.
Importing into WebSphere Service Registry and Repository
When a deployment artifact generated from WebSphere Integration Developer/WebSphere ESB V6.2 is imported into WebSphere Service Registry and Repository, a number of things happen:
- The SCA module contained in the EAR file is registered to WebSphere Service Registry and Repository.
- The default mediation policies contained in the EAR file are registered to WebSphere Service Registry and Repository.
- All mediation policy domains mentioned in the default mediation policies are registered to WebSphere Service Registry and Repository.
You can view the newly imported SCA module and mediation policies using the WebSphere Service Registry and Repository administrative console. Additional mediation policies for any of the newly defined domains can be authored using WebSphere Service Registry and Repository, as described below. However, before any of the default or newly authored mediation policies can be used by WebSphere ESB to dynamically configure mediation flows, they must be associated with the appropriate SCA module by creating a policy attachment document, as described below.
As mentioned above, mediation policies can be loaded conditionally based on message content. In order to do this, gate conditions have to be applied to the policy attachment document, indicating which policies apply to the current invocation of the flow. Once again, examples of this will be given in the following scenario.
Scenario: Address formatting mediation
The creation and use of mediation policies is best described by example. In this scenario we will create a mediation flow, select a property for dynamic override, create new policies to provide values for the overrides, attach these policies to an SCA module, and create gate conditions to conditionally load these mediation policies into the flows defined in the module.
This scenario is based on a dispatch service where the back-end service needs to receive the address that the postal item in question needs to be sent to. The information in the message is generic and needs to be formatted into a postal address appropriate for the country in which the postal address exists; the mediation provides the formatting function for the system. So regardless of the country and formatting, the input and output messages have the same structure, which means that the same mediation flow can be used and different XSL files loaded for each country's formatting.
Figure 4: Request message business object
Figure 5: Response message business object
The mediation to achieve this function is simple, consisting of a Policy Resolution primitive to extract the relevant mediation policies for the flow, and an XSLT primitive to load the XSL file indicated by the mediation policy and to use it to transform the message.
Figure 6: Mediation flow for address services
Looking at the promoted properties for the
Figure 7: XSLTransform promoted properties
There is a single promoted property with a group of
AddressServices and an alias of
The alias value shown here is the transformation used if no mediation policies apply -- the default value.
In our solution, all XSL files except our default transformation file are stored in WebSphere Service Registry and Repository. In order to load each file conditionally based on the country of the dispatch address, you need to add gate conditions. In order to do this, you set up an association between a policy condition name and part of the message, using the Policy Resolution primitive:
Figure 8: Policy condition
This example has a single policy condition name, called
Country, which is associated with the
Country field in the request message.
Using WebSphere Service Registry and Repository
This mediation flow is exported as an EAR file and imported into WebSphere Service Registry and Repository as an SCA Module:
Figure 9: SCA Integration Modules
The act of importing the module also defines the policy domain called
AddressServices to the WebSphere Service Registry and Repository policy editor
and also registers the default mediation policy for this single domain.
Figure 10: Default mediation policy for AddressServices
A choice is made here either to ignore this policy and let the default behaviour for the mediation flow be controlled via the administrative console access to promoted properties, or to associate this default policy with the SCA module and control the complete configuration of the flow via mediation policies. Our example does not use the default policy.
Creating XSL files
The XSL files used and stored in WebSphere Service Registry and Repository can be created via whatever means is suitable for your systems. This example uses the WebSphere Integration Developer Mapping Editor to create the files for exported into WebSphere Service Registry and Repository:
- Open the
- Select Details => New.
- Select an appropriate file name for the map. In this example you are creating a mapping for French addresses, so it is named
- Select input and output types for the transformation:
Figure 11: New XML Mapping
You can then use the Mapping Editor to create the transformation appropriate to the country. Then the Mapping Editor will have created an XSL file representing this transformation, which you can view
by opening the J2EE perspective, where the
xslt folder of the mediation flow folder will contain the new XSL file:
Figure 12: New XSL file
Copy and paste this file into a temporary directory ready for import into WebSphere Service Registry and Repository. Load the new XSL file into WebSphere Service Registry and Repository with a document type of XML:
Figure 13: Loading new XSL files
Once the new XSL file has been loaded into WebSphere Service Registry and Repository, it will appear under the XML documents list. Opening our new document, we will see that it has been assigned a new unique identifier, or
bsrURI, by WebSphere Service Registry and Repository. This value is important, as it will enable us to build an http request, allowing the
XSLTransform primitive in the mediation flow
to load it dynamically. To find the assigned
bsrURI, open the new XML document and look under Additional Properties as shown in the following figure:
bsrURI of the XSL file
An XSL file needs to be created for as many different formats as are needed. Now that we have our XSL files, we can create a mediation policy files that references them.
Creating a mediation policy
For information on the procedure, see Creating
mediation policies in WebSphere Service Registry and Repository, a tutorial in the product information centre. Be sure to select the mediation domain
which has only a single assertion:
XSLFile. The value used for this assertion is the complete HTTP request to extract the XSL file, which is constructed as follows:
<server>-- Name of the WebSphere Service Registry and Repository server
<port>-- Port servicing WebSphere Service Registry and Repository request
<bsrURI>-- WebSphere Service Registry and Repository id of the XSL document to be loaded
Figure 15: Policy document
Remember to give the mediation policy an identifier, in this example it is
Figure 16: Policy Identifier
This policy document now needs to be associated with the SCA module
Attaching the policy to the module
Open the SCA Module from the Service Metadata section, select the Policy tab, and then select Edit Policy Attachments:
Figure 17: Editing Policy Attachments
The Search dialog lets you select the newly created Policy, which in the example is in a document called
In fact, what appears in the list are the identifiers of the policies, so you will actually see
Select the appropriate policy and click Finish. What is happening here is that WebSphere Service Registry and Repository is automatically generating a policy attachment document, and it is on this document that we are going to define the appropriate gate condition.
Defining a gate condition
The mediation policy defined as
PostalFrance should only be applied when the dispatch country is actually
France, so you need to make sure that
the mediation policy is only applied in this condition. To do so, define a mediation gate condition to the automatically generated policy attachment document.
Open the SCA module itself and select Applied Policy Attachments. You will see is the newly generated policy attachment document, associating the
with the mediation policy
PostalFrance. Open this document and select Edit Properties => Add Property:
Figure 18: Mediation gate condition name
All mediation gate condition names must start with the characters
The value of the gate condition, in this case, must indicate when the policy called
PostalFrance is to be loaded:
Figure 19: Mediation gate condition value
Setup is now complete so the runtime processing goes as follows:
- Message arrives with
/body/dispatch/input/Country = France.
- Policy Resolution primitive finds that mediation policy
- Policy Resolution primitive loads the
dynamicPropertyContextwith the new configuration:
XSLFile = http://<server>:<port>/WSRR/6.2/Content/<bsrURI>in a group labeled
formatAddressrecognizes the field
AddressServicesand uses the value to override its associated promoted property.
XSLTransformprimitive sends an HTTP request to WebSphere Service Registry and Repository to extract this XSL File, referenced as the
- Message is transformed according to this XSL file.
Country is not
France, and no other mediation policies apply, the mediation flow will default to the value of
The power of this model is in its extensibility. You can add new countries with new transformations without having to alter the mediation flow in any way.
This article introduced the concept of a mediation policy to control the dynamic configuration of a mediation flow using WebSphere ESB V6.2. It then showed you how to use WebSphere Service Registry and Repository to author and store these policies, along with XSL files, used by the mediation flow to dynamically configure the flow. Finally, it showed how to load these mediation policies conditionally, based on context in the message passing through the flow.
- What's new in WebSphere Enterprise Service Bus V6.2, Part 1: Overview
Part 1 describes the new or enhanced transport protocol bindings, data binding capabilities, mediation primitives, and declarative flow control introduced in WebSphere ESB V6.2 and its associated tooling, WebSphere Integration Developer.
- What's new in WebSphere Enterprise Service Bus V6.2, Part 2: Service gateway support
Part 2 describes the service gateway and policy capabilities.
Creating mediation policies in WebSphere Service Registry and Repository
This tutorial gives a step by step account of how mediation policies are created and used from WebSphere Service Registry and Repository.
- WebSphere ESB developer resources page
Technical resources to help you use WebSphere ESB as a flexible connectivity infrastructure for integrating applications and services to support an SOA.
- WebSphere ESB product page
Product descriptions, product news, training information, support information, and more.
- WebSphere ESB information center
A single Web portal to all WebSphere ESB documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere ESB.
- WebSphere ESB documentation library
WebSphere ESB product manuals.
- WebSphere ESB FAQs
Basic questions and answers about the new WebSphere ESB product and its relationship to other WebSphere products.
- WebSphere ESB support
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- Redbook: Patterns: SOA Design Using WebSphere Message Broker and WebSphere ESB
Patterns for e-business are a group of proven, reusable assets that can be used to increase the speed of developing and deploying e-business applications. This Redbook shows you how to use WebSphere ESB together with WebSphere Message Broker to implement an ESB within an SOA. Includes scenario to demonstrate design, development, and deployment.
- WebSphere Integration Developer developer resources page
Technical resources to help you use the WebSphere Integration Developer IDE to render your existing IT assets as service components, encouraging reuse and efficiency as you build SOA-based integration solutions across WebSphere Process Server, WebSphere ESB, and WebSphere Adapters.
- WebSphere Integration Developer product page
Product descriptions, product news, training information, support information, and more.
- WebSphere Integration Developer information center
A single Web portal to all WebSphere Integration Developer documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Integration Developer environment.
- WebSphere Integration Developer information roadmap
Roadmap of articles and resources to help you with installation, migration, administration, development, troubleshooting, and understanding the underlying technology.
- WebSphere Integration Developer documentation library
WebSphere Integration Developer product manuals.
- WebSphere Integration Developer support
A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- WebSphere SOA solutions developer resources page
Get technical resources for WebSphere SOA solutions.
- developerWorks SOA and Web services zone
Technical resources for evaluating, planning, designing, and implementing solutions that involve SOA and Web services.
- developerWorks WebSphere application connectivity zone
Access to WebSphere application connectivity (formerly WebSphere business integration) how-to articles, downloads, tutorials, education, product info, and more.
- developerWorks WebSphere business process management zone
Access to WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
- WebSphere business process management products page
For both business and technical users, a handy overview of all business process management products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
- Technical books from IBM Press
Convenient online ordering through Barnes & Noble.
- developerWorks technical events and Webcasts
Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.