WebSphere Enterprise Service Bus for z/OS, Version 6.2.0 Operating Systems: z/OS



< Previous


Click here to show all collapsed sections.Show all details | Click here to hide all collapsed sections.Hide all details



Tutorial: Creating mediation policies in WSRR

You can use mediation policies to control message flows between service requesters and service providers. This tutorial shows you how to load an SCA module (and associated mediation policies) into WebSphere® Service Registry and Repository (WSRR); also, how to attach a mediation policy to your SCA module.

This tutorial shows you how to configure WSRR, so you can use mediation policies to control your message flows. The tutorial is broken into smaller chunks of information called (education) modules, and each module has one or more lessons.
Note: This tutorial shows you how to create your own mediation policies and make them conditional and, therefore, you can use this tutorial if you want to implement the mediation policy pattern Mutually exclusive gate conditions. If you want to use the simplest mediation policy pattern, Default mediation policies only, you need only do modules one, two, and four. You need only read the governance module if you want to make use of WSRR governance.

Introduction

Mediation policies are associated with SCA modules, and let you control the dynamic properties of mediations.

Expand or collapse Show details Hide details

When you use WebSphere Integration Developer to create SCA modules that contain mediation flows, any module property that you choose to promote (make visible to the run time) is also a dynamic property. Dynamic properties can be overridden, at run time, using mediation policies in a registry.

When you export your SCA module, WebSphere Integration Developer generates a default mediation policy for each property group in your SCA module. The default mediation policies represent the values given to all dynamic properties, at development time. Although WebSphere Integration Developer generates default mediation policies it does not attach them to the SCA module.

Generally, you should use default mediation policies without any associated conditions, and create your own mediation policies if you want to have conditional mediation policies.

Learning objectives

  • Understand how SCA modules and mediation policies relate to each other.
  • Learn how to load SCA modules (and system-defined mediation policies) into WSRR.
  • Learn how to create a mediation policy.
  • Learn how to attach a mediation policy to an SCA module.
  • Learn how to create gate conditions for a mediation policy.
This tutorial takes approximately 1 hour to finish. If you explore other concepts related to this tutorial, it could take longer to complete.

Skill level

Intermediate.

Audience

Integration Developers.

Administrators.

System requirements

  • WebSphere Integration Developer, Version 6.2.
  • WebSphere Enterprise Service Bus, Version 6.2 or WebSphere Process Server, Version 6.2.
  • WebSphere Service Registry and Repository, Version 6.2.0.2.

Prerequisites

Read the mediation policies scenario which explains the overview, and also explains how the developer, the runtime administrator, and the WSRR administrator must work together.



Module 1: Loading an SCA module and associated mediation policies

Mediation policy control is achieved at the level of the SCA module. This module shows you how to load an SCA module into WSRR, so you can attach a mediation policy to it.

Expand or collapse Show details Hide details
Learn how to load an SCA module into WSRR.
5 minutes.

Lesson : Loading an SCA module

Load an SCA module, in an EAR file, from the local file system. If the EAR file contains mediation policies, these are also loaded.

  1. Optional: If you have a versioned SCA module that you need to deploy to clusters, you must run CreateVersionedSCAModule to create a new EAR file that contains a unique instance of a versioned SCA module. You must create one instance of the module for every cluster you want to deploy to, and you must load your versioned SCA modules into WSRR from the new EAR files.
  2. Logon to the WSRR Web user interface.
When you load the EAR file containing your SCA module, WSRR creates an SCA module document. WSRR also loads any system-generated mediation policies.
Procedure
  1. Click Service Documents > SCA Integration Modules, in the navigation pane of the WSRR Web user interface. The SCA Integration Modules page is displayed, in the content pane.
  2. Click Load Documents, in the content pane. The Load Documents page is displayed with the Document type set to SCA integration module.
  3. Click Browse, to find the SCA integration module that you want to load.
  4. Select the EAR file containing the SCA module that you want to load. The path to the EAR file is displayed.
  5. Enter the document description.
  6. Optional: Enter the version. The version referred to on this panel is the WSRR document version, not the SCA module version (every WSRR document can have a version identifier). If you load a versioned SCA module, the runtime registry query will need to find the correctly versioned SCA module (the WSRR document version is not relevant, in this context). If you want, you can keep the SCA module version the same as the WSRR document version. To keep the version identifiers the same you must manually enter the SCA module number. For example, if your EAR file is called CreditHistory_v1_0_0App.ear and your SCA module is called CreditHistory_v1_0_0 you should enter the version number: v1_0_0.
    Note: You cannot change the WSRR version identifier after you have loaded your SCA module.
  7. Click OK.
WSRR creates an SCA module document.

WSRR also loads any default mediation policies that were generated by WebSphere Integration Developer. If you want to provide a dynamic override for every dynamic property in your module, you can simply attach all the default (system-generated) mediation policies to your SCA module.

Example: Loading an SCA integration module

This figure shows a Load Documents page with the document type filled in for an SCA integration module.



Module 2: Viewing a mediation policy

When you load an SCA integration module into WSRR, any system-generated (default) mediation policies are loaded along with the SCA module. This module shows you how to view mediation policies in general, and how to identify the default mediation policies.

Expand or collapse Show details Hide details
Learn how to view a mediation policy, and how to identify mediation policies that have been generated by WebSphere Integration Developer.
5 minutes.
Load the SCA module containing the default mediation policies.

Lesson : Viewing a default mediation policy

View the default mediation policies, generated for your SCA module.

An SCA integration module that contains a Policy Resolution mediation primitive, generally contains one or more default mediation policies generated by WebSphere Integration Developer (one mediation policy for each property group). However, system-generated mediation policies are not automatically attached to the associated SCA module. You must decide which dynamic properties you want to override and, therefore, which mediation policies you want to attach to your SCA module.
Note: Any dynamic properties in the SCA module appear as mediation policy assertions, in the mediation policy document created by WSRR.

A mediation policy has a namespace, which is made up of the property's group name appended to: http://www.ibm.com/wbi/mediation/200812/. The integration developer can specify the property group and the administrative console displays module properties in their property groups. The namespace is displayed by WSRR as an additional property of the mediation policy document, called xmlns_sibx.

Procedure
  1. Click Service Documents > Policy Documents, in the navigation pane of the WSRR Web user interface. The Policy Documents page is displayed in the content pane.
  2. Click a mediation policy document. Generally, mediation policy documents that have been system-generated have a name of the format: application-group. For example, if the EAR file were called SimpleApp.ear and the groups were called groupA and groupB, the mediation policy documents might be called SimpleApp-groupA.xml and SimpleApp-groupB.xml.
  3. Click the Policy tab.

You can now see the contents of the mediation policy document. For default mediation policies, each assertion relates to a dynamic property. When a mediation policy is made use of, at run time, its assertion values override any dynamic properties in the mediation flow.

Example: Viewing a mediation policy for an SCA module

The following figure shows a mediation policy document with three properties for groupA. The property names are: propA1, propA2, and propA3.
Figure 1. Mediation policy document for groupA of SimpleAppThis figure shows a mediation policy document with three assertions. One for propA1, one for propA2, and one for propA3.



Module 3: Creating your own mediation policy, for an SCA module

If you want to do more than override all the dynamic properties of an SCA module, you can create your own mediation policies, in WSRR. This module shows you how to create a mediation policy.

Expand or collapse Show details Hide details
Learn how to create a mediation policy.
15 minutes.

Lesson : Creating a mediation policy

Create your own mediation policy.

If you want to override specific dynamic properties of an SCA module you can create your own mediation policy. (Generally, you would create your own mediation policy if you wanted to apply mediation policies conditionally; according to gate conditions.)
Procedure
  1. Click Service Documents > Policy Documents, in the navigation pane of the WSRR Web user interface. The Policy Documents page is displayed, in the content pane.
  2. Click New.
  3. Select WS Policy Framework 1.5.
  4. Click Next.
  5. Enter the name of the mediation policy.
  6. Enter the description.
  7. Click Policy.
  8. Click Add Property. The Optional Properties should say Policy Identifier.
  9. Click Add.
  10. Enter a unique identifier. The identifier should be unique for this instance of WSRR. Add the identifier after the urn:, for example urn:UniqueIdentifier.
  11. Click Select Policy Domain. The policy domains are listed. All mediation policy domains have the form: Mediation Domain [xxx], where xxx is the domain name. For example, Mediation Domain [groupA].
  12. Select the policy domain for your mediation policies.
  13. Click Apply.
  14. Click Select Policy Type. The policy type relates to the property group you defined in WebSphere Integration Developer.
  15. Click Select.
  16. Click Add Assertion.
  17. Select a mediation policy assertion, for a property you want to override. Each assertion relates to a dynamic property in a particular property group. Therefore, you can select an assertion for any dynamic property in a particular property group.
  18. Click Add.
  19. Enter a value for the assertion.
  20. Add any other assertions and values that you want to have in your mediation policy.
    Note: You do not have to give values to all assertions, you just give values to the properties you want to override.
  21. Click Publish.

WSRR creates a mediation policy that contains the property overrides you specified. Before the overrides can be used, you must attach the mediation policy to your SCA module.

Example: User-generated mediation policy for an SCA module

The following figure shows an assertion being added to a new mediation policy document. The mediation policy contains a groupA property (propA1) whose value is set to All.
Figure 2. Mediation policy for groupA of SimpleAppThis figure shows a mediation policy for a single property group of an SCA module.
The following figure shows the same three properties, for groupA, seen from the administrative console. You can adjust the values from the administrative console. However, if the appropriate mediation policy is attached, and made use of, the mediation policy values take precedence.
Figure 3. Properties for SCA module SimpleAppThis figure shows the SCA module properties for SimpleApp. The property groups and names can be seen in the mediation policies.



Module 4: Attaching a mediation policy to an SCA module

In order to use mediation policies, they must be attached to an SCA module. This module shows you how to attach a mediation policy to an SCA module.

Expand or collapse Show details Hide details
Learn how to attach a mediation policy to an SCA module, in WSRR.
10 minutes.

Lesson : Attaching a mediation policy

Attach a mediation policy to an SCA module.

When you load an SCA integration module into WSRR, any default mediation policies are loaded, along with the SCA module. However, the default mediation policies are not attached to the SCA module. It is up to you to decide which mediation policies you use.
Procedure
  1. Click Service Documents > SCA Integration Modules > SCA Module Documents, in the navigation pane of the WSRR Web user interface. The SCA Module Documents page is displayed, in the content pane.
  2. Select your SCA module document. The details of the SCA module document are displayed.
  3. Select your module (under Relationships > Modules). The module details are now displayed.
  4. Click Policy. You can now see the mediation policy details.
  5. Click Edit Policy Attachments.
  6. Click Attach Policy. You can now see the Add Policy Attachment information.
  7. Click Search.
  8. Select the mediation policy you want to attach to your SCA module.
  9. Click Apply.
  10. Click Finish.
WSRR creates a policy attachment document, that attaches the selected mediation policy to your SCA module.

Example: Mediation policy attachments

The following figure shows one mediation policy attachment for the SCA module SimpleApp.
Figure 4. Mediation policy attachment for SimpleAppThis figure shows a mediation policy attachment for a user-defined mediation policy.



Module 5: Creating a conditional mediation policy

You can create gate conditions for your own mediation policies, in WSRR. This module shows you how to create a gate condition on a mediation policy attachment (a mediation policy attachment attaches a mediation policy to an SCA module).

Expand or collapse Show details Hide details
Learn how to create a condition for a mediation policy attachment, in WSRR.
10 minutes.

Lesson : Creating a condition for a mediation policy

Create a gate condition for your mediation policy. The gate condition is created on the mediation policy attachment, in WSRR.

  1. In WebSphere Integration Developer, create conditions on the Policy Resolution mediation primitive.
  2. In WSRR, create your own mediation policy.
After attaching a mediation policy to your SCA module, you can create a gate condition on the mediation policy attachment that WSRR has generated.

You create gate conditions by adding user properties to the mediation policy attachment. The run time interprets some of the user properties as necessary conditions (gate conditions): the conditions must be met before the mediation policy can be used. Only user properties that begin with the string medGate_ are used as gate conditions for mediation policies.

Generally, you should only create gate conditions on mediation policies that you create yourself, not on system-generated mediation policies.

Procedure
  1. Click Service Documents > Policy Documents > Documents with Policy Attachments, in the navigation pane of the WSRR Web user interface. The Documents with Policy Attachments page is displayed in the content pane.
  2. Select the mediation policy attachment document you want to update. The details of the attachment document are displayed.
  3. Under Relationships > Attachments, select your attachment.
  4. Click Edit Properties.
  5. Click Add Property. You can now add a property name.
  6. Enter the gate condition name. Gate condition names must start with medGate_ followed by a user-defined string, for example, medGate_Condition1.
  7. Click Add.
  8. Enter the gate condition value. The syntax of the gate condition is: <policy condition name><operation><gate value>. The <policy condition name> must be specified in the Policy Resolution mediation primitive and the <operation> must be one of the following: = , != , > , < , <= or >= . The <gate value> is the value being compared; if this value is a string, it should be delimited using single or double quotes. For example, serviceLevel = "Gold" or age > 59. In this example, serviceLevel and age must both be specified as a Policy condition name in the Policy Resolution mediation primitive.
  9. Click Apply.
WSRR creates the condition for your mediation policy.

In the mediation policy processing model, mediation policies with gate conditions have the highest precedence. Therefore, property values defined by these mediation policies have the highest precedence. Mediation policies without gate conditions have a lower precedence. Therefore, property values defined by these mediation policies have a lower precedence. Administrative console values are used if there is no suitable property in a mediation policy.

Example: Gate condition on a mediation policy attachment

The following figure shows the additional properties of a mediation policy attachment, after a gate condition has been added (but before the change has been applied). The gate condition is called medGate_Condition1 and has a value of age > 59.
Figure 5. Gate condition on a mediation policy attachment
This figure shows one gate condition for a mediation policy.



Module 6: Governing a mediation policy

Using WSRR classification systems (including life cycle classifications), you can filter the visibility of mediation policies. This module shows you how to govern mediation policies by using WSRR life cycle classifications.

Expand or collapse Show details Hide details
Learn how to govern mediation policies, in WSRR.
15 minutes.

Lesson 6.1: Discovering classification URIs

In order for a mediation policy to be visible at run time, any classifications you define at integration time must match classifications on the mediation policy at run time. You must use the classification URIs, shown in WSRR, when developing your SCA module.

  • Determine what governance states you need for your mediation policies, and whether you already have suitable life cycle states in WSRR. There is a default governance life cycle (set of life cycle classifications), but you can define your own life cycle and include the categories required by your organization.
WSRR supports many classification systems, including life cycle classifications that you can use to govern your mediation policies.

If you make your policy document governed, in WSRR, you can take advantage of the governance capabilities of WSRR. For example, when you make a policy document governed, the governance state is percolated to any associated policies. In addition to using classifications for WSRR governance, you might want to use other types of WSRR classifications, in which case you can add classifications directly to the relevant WSRR policies (rather than to the policy documents).

In WSRR, you must find the URI of any classification that you want to use. Then, in WebSphere Integration Developer, you must create a Policy Resolution Classification property using that URI.

In WSRR, you can find the URI of a classification in a number of ways. The following steps show you one way.

Procedure
  1. Click Service Documents > Policy Documents, in the navigation pane of the WSRR Web user interface. The Policy Documents page is displayed in the content pane.
  2. Click a mediation policy document.
  3. Click Edit Classifications. The Classifications page is displayed.
  4. Select the check box of the Life Cycle Classification state that you want to use. If your policy document already has the classification whose URI you want, this step is unnecessary.
  5. Click Add >>>. If your policy document already has the classification whose URI you want, this step is unnecessary.
  6. Select (highlight) the classification whose URI you want. The URI, of the classification, appears in the table at the bottom of the page.
  7. Click Cancel. Do not add governance classifications using the Edit Classifications method.
You can now reuse the URI in the Classification property of a Policy Resolution mediation primitive.

Example: URI for a life cycle state

The following figure shows the URI for a life cycle state. You must use this URI when you develop your SCA module.
Figure 6. Classification URI
This figure shows the URI for a Managed classification.

Lesson 6.2: Making a mediation policy governed in WSRR

If you want to use WSRR governance, you have to make your policy document governed and then move it from state to state.

  • Determine what governance states you need for your mediation policies, and whether you already have suitable life cycle states in WSRR. There is a default governance life cycle (set of classifications), but you can define your own life cycle and include the categories required by your organization.
Any mediation policy, default or user-generated, can be governed in WSRR.
Procedure
  1. Click Service Documents > Policy Documents, in the navigation pane of the WSRR Web user interface. The Policy Documents page is displayed in the content pane.
  2. Click a mediation policy document. Generally, default (system-generated) mediation policy documents have a name of the format: application-group. For example, if the EAR file were called SimpleApp.ear and the groups were called groupA and groupB, the mediation policy documents might be called SimpleApp-groupA.xml and SimpleApp-groupB.xml.
  3. Click the Governance tab.
  4. Click Govern. Having entities in a life cycle allows governance controls to be enforced (using the relevant classification).
    Note: A governed entity moves from one life cycle state to another, it does not have more than one life cycle state at a time.
  5. If you want to change the governance state, click Transition. If a policy document is governed and you move it to another life cycle state, any associated policies (relationship targets) have their life cycle classification state changed, as well (because they are in the same governed collection).
Your mediation policy is now governed, in WSRR.

Example: Governed mediation policy

The following figure shows a policy document after it has been made governed.
Figure 7. Governed mediation policy
This figure shows a governed policy document.


Tutorial summary

The mediation policy tutorial shows you how to create WSRR documents for SCA modules and mediation policies. In addition, it shows you how to create gate conditions for your mediation policies.

If you have not yet configured your runtime environment you should do so now. For example, ensure that you have a suitable WSRR definition for your SCA module.

After you have configured your runtime environment and completed this tutorial, you should be able to run the application associated with your SCA module. Depending on the message being processed, and on any gate conditions and classifications, the mediation flow can be adjusted by mediation policies.

< Previous


tutorial Tutorial topic


Terms of use | Feedback





Timestamp icon Last updated: 21 June 2010





http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.websphere.wesb620.zseries.doc/tasks/ttut_creatingpolicies.html

Copyright IBM Corporation 2005, 2010. All Rights Reserved.

This information center is powered by Eclipse technology (http://www.eclipse.org).