Skip to main content

What's new in WebSphere Enterprise Service Bus V6.2, Part 3: Mediation policy

Brian Hulse (brian_hulse@uk.ibm.com), Software Engineer, IBM
Brian Hulse photo
Brian Hulse is a Senior Software Engineer on the WebSphere ESB team at the IBM Hursley Software Lab in the UK. He has worked in software development at Hursley for 20 years, the last five of which have been in the SOA arena. You can contact Brian at brian_hulse@uk.ibm.com.

Summary:  This article series describes new and enhanced features in WebSphere ESB V6.2 and its associated tooling, WebSphere Integration Developer, including transport protocol bindings, data binding capabilities, mediation primitives, and declarative flow control. Part 3 describes the creation, storage, and use of a mediation policy to dynamically configure a mediation flow. The mediation policy in the example in this article uses the dynamic loading of an XSL file stored in WebSphere Service Registry and Repository.

Date:  17 Jun 2009
Level:  Intermediate
Activity:  2374 views

Introduction

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.

Policy domain

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: http://www.ibm.com/wbi/mediation/200812/<GroupName>, where:

<GroupName> is the name of the promoted property group.

Policy assertion

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
Mapping file promoted property

Figure 2: Mediation policy representation
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: http://www.ibm.com/wbi/mediation/200812/AddressServices.

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 propertySets, 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
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.

Gate Conditions

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
Request message business object

Figure 5: Response message business object
Request 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
Mediation flow for address services

Looking at the promoted properties for the formatAddress primitive:


Figure 7: XSLTransform promoted properties
XSLTransform promoted properties

There is a single promoted property with a group of AddressServices and an alias of XSLFile. 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
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
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
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 XSLTransform primitive called formatAddress.
  • 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 France.
  • Select input and output types for the transformation:

Figure 11: New XML Mapping
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
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
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:


Figure 14: bsrURI of the XSL file
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 AddressServices, 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: http://<server>:<port>/WSRR/6.2/Content/<bsrURI>, where:

  • <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
Policy document

Remember to give the mediation policy an identifier, in this example it is PostalFrance:


Figure 16: Policy Identifier
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
Editing Policy Attachments

The Search dialog lets you select the newly created Policy, which in the example is in a document called AddressFrance. In fact, what appears in the list are the identifiers of the policies, so you will actually see PostalFrance.

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 AddressServices module with the mediation policy PostalFrance. Open this document and select Edit Properties => Add Property:


Figure 18: Mediation gate condition name
Mediation gate condition name

All mediation gate condition names must start with the characters medGate_. 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
Mediation gate condition value

Setup is now complete so the runtime processing goes as follows:

  1. Message arrives with /body/dispatch/input/Country = France.
  2. Policy Resolution primitive finds that mediation policy PostalFrance applies.
  3. Policy Resolution primitive loads the dynamicPropertyContext with the new configuration: XSLFile = http://<server>:<port>/WSRR/6.2/Content/<bsrURI> in a group labeled AddressServices.
  4. XSLTransform primitive formatAddress recognizes the field XSLFile in group AddressServices and uses the value to override its associated promoted property.
  5. XSLTransform primitive sends an HTTP request to WebSphere Service Registry and Repository to extract this XSL File, referenced as the bsrURI.
  6. Message is transformed according to this XSL file.

If the Country is not France, and no other mediation policies apply, the mediation flow will default to the value of XSLFile.

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.

Conclusion

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.


Resources

About the author

Brian Hulse photo

Brian Hulse is a Senior Software Engineer on the WebSphere ESB team at the IBM Hursley Software Lab in the UK. He has worked in software development at Hursley for 20 years, the last five of which have been in the SOA arena. You can contact Brian at brian_hulse@uk.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=398122
ArticleTitle=What's new in WebSphere Enterprise Service Bus V6.2, Part 3: Mediation policy
publish-date=06172009
author1-email=brian_hulse@uk.ibm.com
author1-email-cc=

Table of contents

Next steps from IBM

My developerWorks community

Interact, share, and communicate with developers worldwide.

My developerWorks overview

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).

My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

 

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Rate a product. Write a review.

Write a review for Rational products today!

Special offers

Rate and Review Rational products

WebSphere Application Server Hypervisor trial

SOA Tutorials IBM Book + DVD 35% off: IBM0402

More offers