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:
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
Each of the target services are described below:
Figure 2. HR Application Service interface
Figure 3. HR Employee Query interface
The referenced data types are:
Figure 4. 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
The queryID is built by the mediation flow by appending the dateTime field onto the employee's employeeID:
Figure 6. HRInput data type
Figure 7. 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
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
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
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
Table 1. Summary of request flow mediation primitives
|findEndpointByAction||This Gateway Endpoint Lookup mediation primitive extracts the target service information from WSRR based on the |
|getPolicy||This 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.|
|logMessage||This Message Logger mediation primitive logs the message under mediation policy control.|
|buildIdentifier||This XSLT mediation primitive constructs an identifier, used by the target service, from the message details. Which transform is used is controlled by mediation policy.|
|reassertMessageType||This 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.
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
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
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
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
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
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
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
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
soapActionannotations, so that the Gateway Endpoint Lookup can find them.
To do this you will need access to the WSRR administration console.
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:
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
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
|Export1_EmployeeHttpService||Service||Any mediation policies attached at this scope level apply to all invocations of this service.|
|Export1_EmployeeHttpPort||Endpoint||Any mediation policies attached at this scope level apply to all invocations of the specific endpoint.|
|askHR||Operation||Any mediation policies attached at this scope level apply to all invocations of the named operation.|
|addEmployee||Operation||Any 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
use a meaningful name for the attachment. Then click Create:
Figure 18. 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
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
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
The widget returns to the original panel and now shows the policy attachment that you just created:
Figure 22. 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
|Policy||Group||Assertion||Attachment 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:
registerApplicanton the Application service should have logging enabled
addEmployeeon Employee service should have logging enabled
getApplicantStatuson the Application service should have logging disabled
askHRon 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
Figure 23. Policy Attachment at Operation Scope
Table 4. Scenario for operation based mediation policies
|Policy||Group||Assertion||Attachment 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
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
The Message Element Setter simply copies the first part of the
Action field into
Operation field; both of these are in the
Figure 26. 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 sample||DummyWebServices_PI.zip||25 KB|
|Code sample||HR_Operation_PI.zip||127 KB|
|Code sample||HR_Service_PI.zip||125 KB|
- 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 V7 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.
- What's new in WebSphere ESB V6.2, Part 3: Mediation Policy
Part 3 in this article series 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.
- developerWorks WebSphere developer resources
Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
- developerWorks WebSphere application connectivity developer resources
How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
- developerWorks WebSphere business process management developer resources
WebSphere BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
- developerWorks WebSphere SOA and Web services developer resources
How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
- Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products.
- WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
- WebSphere on-demand demos
Download, watch, and learn what WebSphere products and WebSphere-related technologies can do for your company.
- developerWorks WebSphere weekly newsletter
The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
- WebSphere-related books from IBM Press
Convenient online ordering through Barnes & Noble.
- WebSphere-related events
Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
- developerWorks blogs
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks 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.
- developerWorks on Twitter
Check out recent Twitter messages and URLs.
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.