Working with the policy authoring tool

This tutorial shows you how to use the policy authoring tool in the WebSphere® Service Registry and Repository web UI to create a policy conforming to the WS-Policy specification, and attach it to a WSDL element.

What you should be able to do

At the end of this tutorial, you should be able to:
  • Create a new policy document based on a specified policy framework.
  • Define a policy based on a specified policy domain, and add assertions to the policy.
  • Attach the policy to a binding in a WSDL document.

This tutorial uses the WSRR Web UI. You can also manage policies in the dashboard, see Managing policies in the dashboard.

Introduction

The WebSphere Service Registry and Repository web UI provides a policy authoring tool that you can use to create and maintain policies, and apply those policies to entities stored in the registry.

In this tutorial, you will create a policy that asserts that a web service must use the Web Services Reliable Messaging Protocol (WS-ReliableMessaging) protocol when exchanging messages, and that specifies the values of the WS-ReliableMessaging parameters that are to be used during message exchange.

The WS-ReliableMessaging specification describes a protocol that allows messages to be delivered reliably between distributed applications in the presence of software component, system, or network failures.

To define the required policy, you must create the necessary rules specifying the WS-ReliableMessaging policy requirements, in a WS-Policy framework; the Web Services Reliable Messaging Policy Assertion (WS-RM Policy) specification defines how this is done. The WebSphere Service Registry and Repository web UI provides a policy authoring tool with which you can quickly and easily create policies conforming to WS-RM Policy, and attach those policies to one or more entities.

The WS-RM Policy defines the following parameters:
  • Inactivity timeout: the period of time after which the message exchange can be considered to be ended if no messages have been received.
  • Base retransmission interval: the period of time after which a message is retransmitted if no acknowledgment has been received.
  • Backoff: the retransmission interval is adjusted using an exponential backoff algorithm.
  • acknowledgment interval: the period of time after which an acknowledgment of message receipt must be sent.
You will create a policy that incorporates all these parameters.

Although this tutorial focuses on WS-RM Policy as an example, the tool supports a wide range of other policy domains.

Part 1: Creating a policy

To create a policy, you must first create a policy document. You then define a policy in the policy document. When you save the policy document, a separate policy entity is created; this can then be attached to one or more entities stored in the registry. In this tutorial, you will use the web UI policy authoring tool to create a new policy document from scratch. However, you can also load a WS-Policy compliant policy document into the registry; in this case, WSRR parses the document and creates separate policy entities for each of the policies defined in the policy document.

  1. Create a new policy document.
    1. Open the WebSphere Service Registry and Repository web UI.
    2. Switch to the Administrator perspective if necessary, by selecting Administrator from the Perspective list.
    3. Click View > Service Documents > Policy Documents to display the policy document collection, then click New.
    4. Select WS Policy Framework 1.5 and click Next.
    5. Enter the following values in the fields in the Details subtab:
      • Name: RMPolicy
      • Version: 1.0
  2. Select the policy domain.
    Now that you created the new policy document, you can begin to define the policy. The first step is to select the policy domain. The domain represents the area of policy to which the policy definition applies. Examples of policy domains are as follows:
    • Security
    • Atomic transactions
    • Message transmission optimization

    In this tutorial, you will create a policy in the reliable messaging policy domain.

    1. Click Select Policy Domain alongside the Policy element in the Policy Contents pane.
    2. Select Web Services Reliable Messaging Policy 1.0 from the Policy Domains list and click Apply.
  3. Select the policy type.

    The policy type identifies the specific type of policy in the policy domain. For example, the security policy domain contains policy types relating to signature and encryption.

    1. Click Select Policy Type alongside the Policy element in the Policy Contents pane.
    2. Select Reliable Messaging 1.0 Policy from the Policy Types list and click Select.
    3. Click Add Property, select Policy Identifier from the Optional Properties list, and click Add.
    4. Enter RMPolicy01 in the Policy Identifier field.
  4. Add assertions to the policy.
    Assertions define the specific policy rules that you want to apply. You will add assertions that define the following policy rules:
    • The inactivity time out will be 5 minutes.
    • The base retransmission interval will be 2 seconds.
    • The exponential backoff algorithm will be used.
    • The acknowledgment interval will be one-tenth of a second.
    1. Click Add Assertion alongside the RMAssertion element in the Policy Contents pane.
    2. Select InactivityTimeout from the Assertion Options list and click Add.
    3. Enter 300000 in the Milliseconds field.
    4. Repeat steps a. to c. to add the following assertions:
      • BaseRetransmissionInterval, Milliseconds=2000
      • ExponentialBackoff
      • acknowledgmentInterval, Milliseconds=100
  5. Save the policy document.

    You have now completed the creation of the policy document and are ready to save it by publishing it to the registry. When you publish the policy document, WSRR will create a separate policy containing the assertions that you have defined.

    1. Click Publish. The policy documents collection is displayed. Your new policy document is displayed in the list.
  6. Verify that the policy has been created.
    1. Click View > Service Metadata > Policy > Policies.
    2. Verify that your policy is displayed in the list. The entry in the Name column is RMPolicy01, the value you specified for the policy identifier.

    It is this policy that you attach to entities in the registry, to apply the policy rules that you have defined.

Part 2: Attaching a policy to a WSDL element

You will now attach the policy to a WSDL element to apply the policy to message interactions.
  1. Load the WSDL document containing the element to which the policy will be attached.
    1. Download the file MonolithicStockQuote_ProductionEnvironment.wsdl to a location in your local file system.
    2. Click View > Service Documents > Load Documents.
    3. Click Browse and navigate to the location to which you downloaded the MonolithicStockQuote_ProductionEnvironment.wsdl file.
    4. Select MonolithicStockQuote_ProductionEnvironment.wsdl and click Open.
    5. Click OK and then click Finish.
  2. Attach the policy to a binding defined in the WSDL document.
    1. On the Documents Loaded Successfully page, click MonolithicStockQuote_ProductionEnvironment.wsdl to display the details of the WSDL document.
    2. Select the Policy tab and click Edit Policy Attachments.
    3. Click Attach Policy alongside the Binding name = "MonolithicStockQuoteSoapBinding" element in the WSDL Document Policy Attachments pane.
    4. Leave the Search field blank and click Search. This initiates a search for all policies stored in the registry, on completion of which a list of all policies is displayed.
    5. Select the check box alongside RMPolicy01 and click Attach Selected Policy. The WSDL Document Policy Attachments pane is redisplayed and the policy attachment is displayed below the binding.
    6. Click Finish to save your changes.
  3. Verify that the policy attachment has been created.
    1. You will see a message telling you that a policy document with policy attachments has been created. Click the policy document file name (which begins MonolithicStockQuote_). The policy document details page is displayed.
    2. The Attachments entry under Relationships lists the name of the newly created policy attachment. Click the attachment name to open the policy attachment details.
    3. The Policy Subjects entry under Relationships shows that the subject of the policy attachment (that is, the entity to which the policy applies) is MonolithicStockQuoteSoapBinding, the binding to which you attached the policy in the previous step.

What you did in this tutorial

In this tutorial, you used the policy authoring tool provided in the WebSphere Service Registry and Repository web UI. You created a new policy document based on WS Policy Framework 1.5, and defined a policy, based on the reliable messaging policy domain, consisting of assertions that specified rules for message exchange. You then applied the policy to a WSDL binding.

Parent topic: Tutorials
Related information:
Web Services Reliable Messaging