Policy promotion with WebSphere Service Registry and Repository

The use of run-time policies associated with objects stored in WebSphere Service Registry and Repository (hereafter called Service Registry) has become more valuable to customers as Service Registry has extended its integration with other products, such as WebSphere DataPower and WebSphere Message Broker. The Service Registry promotion feature makes these policies available to different test and production environments, and this article provides guidance and recommendations to dispel the complexity of some of these scenarios. The article uses several examples to show you how to promote policies attached to various objects stored in Service Registry, such as Web Service Definition Language (WSDL) logical objects, Service Level Agreements (SLAs), and Service Level Definitions (SLDs).

Jerry Stevens (jerry_stevens@uk.ibm.com), Software Developer, WebSphere Service Registry and Repository Development team, IBM

Photo of Jerry StevensJerry Stevens leads the WebSphere Service Registry and Repository (WSRR) Performance team at the IBM Software Lab in Hursley Park, United Kingdom. He joined IBM UK Global Services in 1997 as an IBM AIX Consultant, then transferred to WebSphere MQ Development and Performance Analysis in 2001, and to WSRR Development in 2009. He took on the WSRR Performance team role in 2011. Prior to joining IBM, Jerry worked for Shell UK as a Senior Systems Engineer, where he undertook a range of technical consultancy and development roles and worked with a variety of open systems platforms and architectures. He graduated from Exeter University with an Honours Degree in Mathematics.



18 May 2011

Introduction

To benefit from this article, you should have a working knowledge of IBM® WebSphere® Service Registry and Repository (hereafter called Service Registry). For introductory information about Service Registry, see the Service Registry information portal or the Service Registry information centre.

Service Registry lets you distinguish between different runtime environments within an organization, enabling you to maintain appropriate Web services and metadata for different target runtime environments. For example, you can use one registry for building and developing Web services, another for testing those services internally, and a third when those services are deployed in production and used by customers. The registry in which services are first discovered, developed, and governed is termed the governance registry, while an interim registry used for testing is called a runtime staging registry, and a registry to which the final production version of services are deployed is called a runtime production registry.

The Service Registry mechanism for propagating service data and metadata from a governance registry to different target runtime registries is called promotion. Data is always promoted from the governance registry to each runtime registry and not from runtime registry to runtime registry, as shown in Figure 1:

Figure 1. Promotion overview
Promotion overview

A topology for governance, staging, and production registries is entirely configurable within your Service Registry configuration profile, and optimum topology depends on your environment. The Governance Enablement Profile (GEP) provides a reference profile that you can adapt as needed. The GEP has been loaded and activated in all of the scenarios described in this article. For more information on target registry environments, see the developerWorks article WebSphere Service Registry and Repository topologies explained.

When service data is promoted, Service Registry can either package the data to be promoted as a zip file on the governance registry for you to manually copy and import on the target runtime registry, or it may be sent synchronously from the governance registry to the runtime registry. The next section takes you through a set of typical promotion scenarios and shows how to apply the guidelines to each one.

Summary of Service Registry promotion

When populating your governance registry, one of the steps is to import the actual WSDL files into Service Registry, which parses the files and through a process known as shredding, separates them into a number of component logical objects such as the Port Type, Service Binding, and Service Interface. A number of additional correlated objects are created and used to group together various different logical objects. For example the ServicePort correlated object connects the WSDLPort to the name, namespace, and version of the service from which the port is derived.

To promote this WSDL from one registry to another, you should manage it with a Service Version object, as described in the Service Registry information centre. It groups together all objects related to the WSDL into a single governed collection that becomes a single defined version of the service.

Triggering promotion

You can then manage the Service Version object through various life cycle states defined in your profile. At the desired stage in the life cycle, the service and the objects governed with it are automatically promoted to another registry, such as a test runtime registry, by transitioning the Service Version to the specific life cycle state that has been pre-defined to trigger the promotion, such as the ApproveForStagingDeployment transition. When the promotion is complete, the target runtime registry will have been populated with the objects managed by the Service Version, as shown in Figure 2:

Figure 2. Promotion process
Promotion process

The definition of the transition that triggers the promotion and the details of the promotion itself, such as whether it is manual or synchronous, are defined in the Service Registry promotion properties configuration, as shown below in Listing 4. Example transition promotion configuration.

Synchronous and manual promotion styles

Asynchronous promotion

Service Registry used to provide a third promotion option called asynchronous promotion, which let you set up promotion to occur at a specific date and time using a scheduled task. Asynchronous promotion has been deprecated for several releases and manual promotion is recommended instead, and therefore asynchronous promotion is not described in this article.

In addition to knowing how to trigger a promotion, you should also know about the two ways to deliver promoted data to a target registry:

Synchronous promotion
After the Service Version has been successfully transitioned to the appropriate state,Service Registry automatically populates the target runtime registry with the objects governed by the service collection. If there is an error during the promotion process, then the Service Version is not transitioned.
Manual promotion
Transitioning the Service Version generates a zip file on the system hosting the governance registry. The location and name of this zip file is configurable in the promotion properties. As soon as this zip file has been created, the Service Version is transitioned to the promoted state. However, the promotion on the target runtime is not completed until the zip file has been manually copied to the runtime registry and then imported through the Service Registry user interface.

The examples in this article use manual promotion to make the different promotion steps as clear as possible.

For more information on how to use the GEP to promote a simple service, see GEP tutorials in the Service Registry information centre.

Service Registry promotion with policies

This section describes some important concepts that you should understand before promoting policies.

External or embedded policies

From a Service Registry point of view, policies can either be external to a WSDL document or else defined and embedded within one. External policies can be attached to service elements defined across multiple WSDLs, either by use of the Policy Attachment Editor or by handcrafting a policy attachment document and loading it into Service Registry.

On the other hand, the Policy Attachment Editor only lets you attach embedded policies to service elements defined in the same WSDL -- you cannot use it to attach embedded policies to service elements in other WSDLs. If you try to do so, you will find that embedded policies from other WSDLs are not in the search list for policies to be attached to another WSDL. You can attach embedded policies across WSDLs by handcrafting a policy attachment, but it is not recommended, because if you attach a policy embedded in one WSDL to another, then when the target WSDL is promoted, the whole of the policy's WSDL will also be promoted, causing services being imported onto the target registry that are not suitable for that runtime. Therefore, if you use embedded policies, use them only on service elements defined in the same WSDL.

Two ways to specify policy attachments

There are two notations for attaching policies to Service Registry objects: WSDL identifiers, and XPath expressions. For both, the attachment can be defined either in the same file as the policy, or in a separate policy attachment document. The recommended practice is to always have the policy and policy attachment defined in separate documents, which is done in this article. Here are the two different notations:

WSDL identifiers

A WSDL identifier policy attachment is specified with the following type of XML structure:

Listing 1. Policy attachment by WSDL identifier
<wsp:PolicyAttachment>
  <wsp:AppliesTo>
    <wsp15:URI>
    http://example.org/TicketAgent.wsdl11#wsdl11.binding(TicketAgentSoap)
    </wsp15:URI>
  </wsp:AppliesTo>
  <wsp:PolicyReference URI="MySecurityPolicy" />
</wsp:PolicyAttachment>

Defining attachments using WSDL identifiers is endorsed by a World Wide Web Consortium standards document. As you can see in Listing 1, the attachment contains an AppliesTo element that specifies the WSDL attachment point for the policy. It also contains a policy reference to the policy being attached. The attachment point is specified as a domain expression that is used to identify endpoints, messages, or resources to which the policy is attached. The domain expression can also be expressed in the more extensible URI-based form, based on the namespace of the WSDL document that contains the subject of the policy, together with the type and name of the specific subject. The URI element of the attachment conforms to the WSDL 1.1 element identifier specification. Policy attachments defined outside of Service Registry are normally of the WSDL identifier form.

There are two limitations on using WSDL Identifiers with Service Registry policy promotion:

  • WSDL identifier based policy attachments can be applied only to other WSDL objects and cannot, for example, be applied to Service Registry specific objects such as SLDs and SLAs.
  • The Service Registry Policy Attachment Editor does not create policy attachments based on WSDL identifiers. You can, however, create policy documents containing WSDL-identifier-based attachments outside of Service Registry and then load and use them.

XPath expressions

The second way to attach policies to Service Registry objects is to use an XPath search expression, again, configured within an XML structure. An XPath policy attachment can be either 1:1 (applies to a single object only), or 1:n (applies to multiple objects across the registry). Listing 2 shows a 1:n policy attachment that applies to every WSDL Port defined in the registry:

Listing 2. Policy attachment by XPath expression
<wsp:PolicyAttachment>
  <wsp:AppliesTo>
    <wsrr:PolicySubjectQuery wsrr:xpath="//WSDLPort" />
  <wsp:AppliesTo>
  <wsp:PolicyReference URI="testPolicy" bsrURI="03fc9a03-29b0-40ee.b127.6128fd612761" />
</wsp:PolicyAttachment>

In this case, the attachment again contains an AppliesTo element, but this time the target subjects to which the policy is to be attached are specified by an XPath expression. A policy reference is again included in the element that specifies the policy being attached to the subjects.

The XPath-based notation for policy attachments is specific to Service Registry and is not normally used by other products. Using an XPath expression rather than a WSDL identifier lets you attach policies to SLA and SLD objects as well as to WSDL objects. The XPath notation also makes it easier to test the XPath-based attachments map to the right set of subjects, compared to using WSDL-identifier-based attachments.

Policy life cycles

When governing a policy, it is important to choose a life cycle appropriate for your environment. A basic choice of life cycle, for example, is the policy life cycle provided with the GEP. You may want to develop your own profile with custom life cycles for your own policies in order to:

  • Permit policy promotion to occur at the point in the life cycle most appropriate for your enterprise.
  • Provide the option to re-promote policies at the points in the life cycle most appropriate for your enterprise

Scenarios overview

This article describes three different ways that policies can be attached to Service Registry objects:

  • Attaching a policy to a WSDL logical object, such as a port type, message, or service definition.
  • Attaching a policy to a Service Registry SLD object.
  • Attaching a policy to a Service Registry SLA object.

You will first see a simple scenario in which a single policy is attached to a single WSDL logical object. This scenario will lead to a set of policy promotion guidelines that form the core of this article. Based on these guidelines, you will then see some more complex scenarios with multiple policies attached to WSDL logical objects, and with policies attached to an SLD and an SLA. The scenarios are based on XPath-type policy attachment documents, because:

  • Using XPath policy attachments is consistent with the Service Registry Policy Attachment Editor.
  • XPath policy attachments support the attachment of policies to SLA and SLD objects, whereas WSDL-identifier-based attachments do not.

For an example of policy promotion with a WSDL-identifier-based policy attachment, see Scenario 3 below.

For clarity, the scenarios are based on attachments defined in separate policy documents rather than being embedded within a WSDL. For completeness, Scenario 2 below is based on an embedded policy attachment.

Scenario 1. Policy attached to a WSDL port

This section shows you how to attach a policy to a WSDL object and then promote it. It starts from the point where the WSDL has been loaded into Service Registry and set up with a Service Version. For details on how to create and configure this Service Version, see GEP tutorials in the Service Registry information centre. This scenario assumes the use of a single WSDL file that contains the port type, port, and associated binding all in one file. Such a WSDL is called a monolithic WSDL.

After loading the WSDL and setting up the Service Version for it, load the policy into Service Registry as a policy document. Here is an example of the contents of a policy document:

Listing 3. A trivial policy
<?xml version="1.0"?>
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" 
   xmlns:wsu=
      "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
   wsu:Id="testPolicy" Name="testPolicy">
   <sp:EncryptedParts 
      xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512">
 	<sp:Body/>
   </sp:EncryptedParts>
</wsp:Policy>

The policy document is parsed by Service Registry into a series of Policy Expressions. You then have to attach the policy expressions in the Policy Document to the target objects, in this case the WSDL Port for the service managed by the Service Version. There are several options for creating the definition of the attachment:

  • You can define the attachment either within the policy document itself or externally in a separate policy attachment document.
  • If you use a separate policy attachment document, it can be built either with the Service Registry Policy Attachment Editor or manually and externally from Service Registry.
  • You can define the mapping with either an XPath expression or with a WSDL identifier.

In Service Registry, the mapping between the policy attachment and the WSDL port is defined by an instance of an appliesTo relationship, as shown in Figure 3:

Figure 3. Simple policy promotion
Simple policy promotion

You can see that the appliesTo relationship flows from the policy attachment to the WSDL Port object. Members of a collection to be promoted are determined by the outward relationships from the root document. So in the case of the Service Version, the root document is the Service Version object and the members of the collection of objects that will be promoted are shown in green. These are all objects that flow from the Service Version object outwards. Because the appliesTo relationship flows into the Port object, the policy attachment is not included when the Service Version is promoted.

To ensure that the policy attachment is promoted, make the policy attachment a separately governed entity, as shown in blue in Figure 3 above. The policy life cycle from the GEP is an obvious life cycle to choose for this collection, which means that the policy attachment and Service Version can be promoted in two separate stages.

Although not essential, it is also recommended that a relationship, called ppRelationship in this example, is created from the Service Version to the policy attachment, as shown in Figure 3 in red. If this relationship is created between the Service Version and every policy attachment that applies within that service, it is easier to review all policies that have been attached to that Service Version, as shown in the section Using the ppRelationship relationship to review policies attached to a service below.

It may seem that an easier way to set up policy promotion is to rely on ppRelationship to include the policy attachment in the governed collection belonging to the Service Version. However, consider the case where the same policy has been attached to several different WSDL logical objects. For example, it might be applied to all ports of all WSDLs that have been given a particular classification. If the policy is then attached to our Service Version, then when that is promoted, all the other WSDLs to which the policy is attached would also be promoted, which may not be what you want and there is no option for fine tuning. This solution is therefore not extensible and not recommended. The policy attachment should be governed before the ppRelationship is created, because otherwise you cannot turn the policy attachment into a separately governed collection.

But the story is not yet finished. If you now promote the policy attachment, then it will also bring associated correlated objects from the WSDL with it, because the appliesTo relationship will be followed from the policy attachment to include these objects. Therefore if the policy and WSDL are promoted separately, the target registry will be left with redundant objects from the WSDL that could adversely affect the registry's integrity. A workaround is to disable the correlator modifier plug-in, as described in Activating the configurable modifier plug-in in the Service Registry information centre. While this workaround does work, it is recommended that you set the appliesTo relationship to be ignored on promotion, by modifying the promotion properties files so that the relationship is excluded. Here is an example of a transition portion of a policy promotion configuration that stipulates that both the ppRelationship and appliesTo relationships are ignored on promotion:

Listing 4. Example transition promotion configuration
<transition
   name="http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle
        /v6r3/LifecycleDefinition#ApproveStagingDeployment">
   <target-environments>
      <name>
       http://www.ibm.com/xmlns/prod/serviceregistry/6/1/GovernanceProfileTaxonomy#Staging
      </name>
   </target-environments>
   <ignore-relationships>
      <name>Deployed_On_Application_Server</name>
      <name>Runs_On_Computer_System</name>
      <name>appliesTo</name>
      <name>ppRelationship</name>
   </ignore-relationships>
</transition>

So now when you promote the policy and the WSDL Service version, the two will promote with no duplicate objects. But you also have to ensure that the policy connects to the WSDL on the target registry, which is further complicated by the fact that the policy attachment could be generic, in the sense that it applies to multiple WSDLs. So not only do you have to ensure that it gets connected to the first WSDL, you also have to ensure that it gets connected to any other WSDL objects that it may apply to and which are promoted subsequently. To activate this auto-reconnection on the target registry, enable a feature on Service Registry called policy re-evaluation, which causes every policy expression to be re-evaluated on any Service Registry operation that is not read-only and ensures that the appliesTo relationship is always correctly maintained. For information on how to configure policy re-evaluation, see Updating policy subjects automatically in the Service Registry information centre.

Policy re-evaluation only works with policies that are attached using an XPath expression in the policy attachment document. Re-evaluation does not currently work with policy attachments defined with WSDL identifiers. If you must use WSDL-identifier-based policy attachments, see Scenario 3 below.

Policy promotion guidelines

The guidelines introduced in Scenario 1 are summarised as follows:

Configuration

  1. Enable policy re-evaluation on target registries, as described in Updating policy subjects automatically. With this option, policies are re-evaluated only on create, update, delete, and transition operations and not on read-only operations. Enabling policy re-evaluation should therefore have little impact on run-time registries.
  2. Ensure that the target registries have disableOnImport set on the correlator modifier properties, as described in Activating the correlator modifier plug-in.

Policies

  1. All new policies that are being targeted for promotion should be created as separate policy documents referenced from the WSDL, rather than being embedded within the WSDL, which makes it easier for policies to be applied to multiple services.
  2. If embedded polices are being used, perhaps because they are defined in existing services, do not attach them to service elements defined in another WSDL. For more information, see Service Registry promotion with policies above.

Policy attachments

  1. Make each policy attachment document being targeted for promotion a separately governed entity.
  2. Create a relationship from Service Versions to all policy attachment documents that contain policies attached to objects governed as part of that Service Version. The name of this relationship does not matter, but you should use a common name across your source registry. This article uses the name ppRelationship.
  3. If you need to attach policies to SLAs or SLDs, use XPath notation to define the attachments. For more information, see Service Registry promotion with policies above.
  4. If you need to use policy attachment documents that have been created by a product other than Service Registry, it is likely the attachment will be defined using the WSDL identifier style notation, and such policy attachments cannot be applied to SLAs or SLDs.
  5. Do not mix XPath and WSDL policy attachment notation within the same policy attachment document.

Promotion

  1. Manual versus synchronous promotion -- The scenarios in this article all use manual promotion to make things as clear as possible, but in general you can use either manual or synchronous. Because policies should be promoted separately from the entities to which they are attached, you may need to do a large number of different promotions, in which case you may find that manual promotion is easier. If you do use synchronous promotion, ensure that the promotions are all performed in the same order as described in the article -- policy attachments are promoted before Service Versions.
  2. If a WSDL is likely to be used with promotion filtering, split it up into component parts before first loading it into Service Registry. For more information, see Scenario 8. Promotion filtering below.
  3. Configure the promotion properties so that the ppRelationship relationship is ignored upon promotion.
  4. Configure the promotion properties so that the appliesTo relationship is ignored when promoting policy attachments
  5. When manual promotion is performed, rename the resultant zip files to something appropriate to the type of object, so that it is easier to import them in the correct order on the target registry.
  6. Promote policy attachments before Service Versions unless using a WSDL-identifier-based WSDL attachment document, in order to minimise the risk of a service becoming available before any policies associated with it. If you are using WSDL-identifier-defined attachments, see Scenario 3 below.

These guidelines form the core of this article and can be used in most policy promotion scenarios. The article now presents several more complex policy promotion scenarios and uses the same guidelines to illustrate the policy promotion process.

Scenario 2. Embedded policy attached to a WSDL port

In this scenario, a policy that is embedded within a WSDL is attached to a port element defined in the same WSDL. Figure 3 above depicts this scenario. The only difference from Scenario 1 is that the policy expression and policy document are defined within the WSDL itself:

Figure 4. Embedded policy attached to a WSDL port
Embedded policy attached to a WSDL port

As noted above, you can use the Policy Attachment Editor to attach the embedded policy to the port that is defined in the same WSDL. Alternatively a policy attachment document can be created by hand. Here are the guidelines applied to this scenario:

  1. Govern the policy attachment using the Policy life cycle.
  2. Create a relationship ppRelationship from the Service Version to the policy attachment. This relationship is shown in red in Figure 4.
  3. Configure the promotion properties to ignore the ppRelationship relationship and to exclude all appliesTo relationships for the specific transitions against which the policy will be promoted.
  4. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  5. Ensure policy re-evaluation is enabled on the target registry.
  6. Promote the policy attachment
  7. Promote the Service Version

Scenario 3. Policy attached to a WSDL port with a WSDL-identifier-based attachment document

As stated Two ways to specify policy attachments above, policy attachment documents can define attachments using either XPath expressions or WSDL identifiers. This article concentrates on the use of XPath-based policy attachments in the scenarios for the reasons mentioned earlier. This scenario shows how to use a WSDL-identifier-based policy attachment. It is based on Scenario 1 with a single policy attachment to a specific WSDL port.

There are two main differences between this scenario and those using XPath-based attachment documents. First, policy attachment documents must be created outside of Service Registry. Second, the Service Version should be promoted before the policy attachment document, because policy re-evaluation is not currently supported with WSDL-identifier-based policy attachments, and so if the policy attachment was promoted first, it would not connect properly to the service when that is promoted. Promoting in this order creates a risk that the service will be activated on the target runtime registry before the policy is promoted. You can minimise this risk by promoting the policy attachment as soon as possible after the Service Version. Here are the steps to set up this environment for policy promotion:

  1. Create the policy attachment document. Service Registry only creates policy attachment documents based on XPath expressions, so you must create the document manually, for example with a text editor.
  2. Make the policy attachment a separately governable entity.
  3. Create a relationship ppRelationship from the Service Version to the policy attachment.
  4. Configure the promotion properties to ignore the ppRelationship relationship and to exclude all appliesTo relationships for the specific transitions against which the policy will be promoted.
  5. Promote the Service Version.
  6. Promote the policy attachment

Here is the WSDL-identifier-based policy attachment document used in this scenario:

Listing 5. Example WSDL-identifier-based policy attachment document
<?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy 
  xmlns:wsp="http://www.w3.org/2006/07/ws-policy"
  xmlns:wsp15="http://www.w3.org/2006/07/ws-policy">
  <wsp:PolicyAttachment 
    xmlns:wsrr="http://schemas.xmlsoap.org/ws/2004/09/wsrr/policy">
    <wsp:AppliesTo>
      <wsp15:URI>
        http://example.ibm.com#wsdl11.port(PendingOrderQueryService/PendingOrderQuery)
      </wsp15:URI>
    </wsp:AppliesTo>
  <wsp:PolicyReference URI="testPolicy" />
  </wsp:PolicyAttachment>
</wsp:Policy>

Service Registry in general supports policy attachment documents that contain both WSDL identifier and XPath type policy attachment documents. Because the way that these two types of attachments are recommended to be processed with policy promotion are different, documents combining the two notations should be split, with WSDL-identifier-based attachments in one and XPath in another. The XPath attachment document should then be promoted before the Service Version, and the WSDL-identifier-based attachment after. You do not need to enable policy re-evaluation on the target when promoting WSDL-identifier policy attachment documents, but if the same target runtime is to import XPath-based attachment documents, then there is no need to deactivate it when processing WSDL identifier attachments.

Scenario 4. Policy attached to a WSDL port and a WSDL binding in the same WSDL

This scenario builds on Scenario 1 and attaches the policy to two different logical objects within the same WSDL, as shown in Figure 5:

Figure 5. Promotion with a policy attached to two objects in the same WSDL
Promotion with a policy attached to two objects in the same WSDL

Two policy attachment documents are created using the Service Registry Policy Attachment Editor, one for each logical object to which the policy is being attached, in this case the WSDL port and the WSDL binding. Here are examples of what the policy attachment documents look like after they are created:

Listing 6. Example policy attachment for a specific WSDL port
<?xml version="1.0"?>
<wsp:Policy
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsrr="http://www.ibm.com/xmlns/prod/serviceregistry/6/2/wspolicy">
  <wsp:PolicyAttachment>
    <wsp:AppliesTo>
      <wsrr:PolicySubjectQuery 
        wsrr:XPath="//WSDLPort[@bsrURI='a3e8d7a3-a99b-4b29.8834.b7cedcb734a0']" />
    </wsp:AppliesTo>
    <wsp:PolicyReference URI="testPolicy" bsrURI="03fc9a03-29b0-40ee.b127.6128fd612761" />
  </wsp:PolicyAttachment>
</wsp:Policy>
Listing 7. Example policy attachment for a specific WSDL binding
<?xml version="1.0"?>
<wsp:Policy
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsrr="http://www.ibm.com/xmlns/prod/serviceregistry/6/2/wspolicy">
  <wsp:PolicyAttachment>
    <wsp:AppliesTo>
      <wsrr:PolicySubjectQuery 
        wsrr:XPath="//WSDLBinding[@bsrURI='9fa7eb9f-7e8a-4a04.8cf1.abefd5abf170']" />
    </wsp:AppliesTo>
    <wsp:PolicyReference URI="testPolicy" bsrURI="03fc9a03-29b0-40ee.b127.6128fd612761" />
  </wsp:PolicyAttachment>
</wsp:Policy>

Here are the guidelines applied to this scenario:

  1. Create a relationship from the Service Version to each of the two policy attachments. These relationships are shown in red in Figure 5. You can see that there are two ppRelationships from the Service Version, one that points to the port and one that points to the binding.
  2. Make each policy attachment separately governable entities.
  3. Configure the promotion properties to ignore the ppRelationship relationship and to exclude all appliesTo relationships for the transitions against which the policy will be promoted.
  4. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  5. Ensure policy re-evaluation is enabled on the target registry.
  6. Promote the first policy attachment
  7. Promote the second policy attachment
  8. Promote the Service Version

This scenario is specific to individual Service Registry objects -- a single WSDL port and a single WSDL binding. In practice, policies created outside of Service Registry may have generic XPath expressions that allow a policy to be attached to multiple Service Registry objects. You can handcraft a single policy attachment document outside of Service Registry that maps the policy to both the port and the binding from a single Policy Attachment document, but it is not recommended. Instead, either use the Policy Attachment Editor within Service Registry to create single policy attachment documents per target object or else load an existing policy document that was created from another runtime.

Scenario 5. Policy attached to two WSDL ports defined in two different WSDLs

In this scenario, a policy is applied to two different objects in two different WSDLs. Because there are two Service Versions, one for each WSDL, and two governed policy attachments, four separate promotions are required, as shown in Figure 6:

Figure 6. Promotion with a policy attached to two objects in different WSDLs
Promotion with a policy attached to two objects in different WSDLs

Two policy attachment documents are again created using the Service Registry Policy Attachment Editor, one for each logical object to which the policy is being attached, in this case the WSDL port from one WSDL and the WSDL port from the other WSDL. Here are examples of what the policy attachment documents look like after they are created:

Listing 8. Example policy attachment for two ports in different WSDLs
<?xml version="1.0"?>
<wsp:Policy
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsrr="http://www.ibm.com/xmlns/prod/serviceregistry/6/2/wspolicy">
  <wsp:PolicyAttachment>
    <wsp:AppliesTo>
      <wsrr:PolicySubjectQuery 
        wsrr:xpath="//WSDLPort[@bsrURI='a3e8d7a3-a99b-4b29.8834.b7cedcb734a0']" />
    </wsp:AppliesTo>
    <wsp:PolicyReference URI="testPolicy" bsrURI="9e426d9e-870a-4ace.a39c.6045ad609cd3" />
  </wsp:PolicyAttachment>
</wsp:Policy>
Listing 9. Example policy attachment for two ports in different WSDLs
<?xml version="1.0"?>
<wsp:Policy
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsrr="http://www.ibm.com/xmlns/prod/serviceregistry/6/2/wspolicy">
  <wsp:PolicyAttachment>
    <wsp:AppliesTo>
      <wsrr:PolicySubjectQuery 
        wsrr:xpath="//WSDLPort[@bsrURI='3076b530-0283-43b0.8203.3974bc3903d9']" />
    </wsp:AppliesTo>
    <wsp:PolicyReference URI="testPolicy" bsrURI="9e426d9e-870a-4ace.a39c.6045ad609cd3" />
  </wsp:PolicyAttachment>
</wsp:Policy>

Here are the guidelines applied to this scenario:

  1. Make the policy attachment a separately governable entity.
  2. Create relationships called ppRelationship from each Service Version to the policy attachment. These relationships are shown in red in Figure 6.
  3. Configure the promotion properties to ignore the ppRelationship relationships and to exclude all appliesTo relationships for the specific transitions against which the policy will be promoted.
  4. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  5. Ensure policy re-evaluation is enabled on the target registry.
  6. Promote the first policy attachment.
  7. Promote the second policy attachment.
  8. Promote Service Version 1.
  9. Promote Service Version 2.

This scenario is again specific to individual Service Registry objects -- a single WSDL port and a single WSDL binding. As noted in the previous scenario, policies created outside of Service Registry may have generic XPath expressions that allow a policy to be attached to multiple Service Registry objects. You can handcraft a single policy attachment document outside of Service Registry that maps the policy to the two ports,but it is not recommended. Instead, either use the Policy Attachment Editor within Service Registry to create single policy attachment documents per target object or else load an existing policy document that was created from another runtime.

Scenario 6. Policy attached to an SLA

In this scenario, you attach a policy to an SLA that forms part of a service, managed by Service Version 2, which consumes another service managed by Service Version 1. For the purpose of clarity, the WSDL and associated objects for Service Version 2 are not shown in the diagram. As described in Service Registry promotion with policies above, the policy attachment must be defined using XPath notation. The following example shows the policy attachment document specifying the policy attached to the target SLA object:

Listing 10. Example policy attachment for two ports in different WSDLs
<?xml version="1.0"?>
<wsp:PolicyAttachment 
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wsrr="http://www.ibm.com/xmlns/prod/serviceregistry/6/2/wspolicy">
  <wsp:AppliesTo>
    <wsrr:PolicySubjectQuery 
	   wsrr:xpath="//GenericObject[@bsrURI='e948cee9-8623-434b.bf7c.d72d7cd77ca9']" />
  </wsp:AppliesTo>
  <wsp:PolicyReference URI="testPolicy" bsrURI="80aa7480-4570-40bd.a2b3.e42f21e4b3d2" />
</wsp:PolicyAttachment>

Again, you need three separate governed collections, one for each Service Version and one for the policy attachment.

Figure 7. Policy attached to an SLA
Policy attached to an SLA

Here are the guidelines applied to this scenario:

  1. Make the policy attachment a separately governable entity.
  2. Create a relationship ppRelationship from Service Version 2 to the policy attachment. This relationship is shown in red in Figure 7.
  3. Configure the promotion properties to ignore the ppRelationship relationships and to exclude all appliesTo relationships for the specific transitions against which the policy will be promoted.
  4. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  5. Ensure policy re-evaluation is enabled on the target registry.
  6. Promote the policy attachment.
  7. Promote Service Version 1.
  8. Promote Service Version 2.

In many scenarios like this, the first Service Version is likely to have been already put into production and promoted to the target runtime when creating a second Service that wants to use it. In this situation, you do not need to re-promote the first Service Version.

Scenario 7. Policies attached to a WSDL logical port, SLA, and SLD

This scenario is based on Scenario 6. Policy attached to an SLA, with a policy attached to the SLD associated with the first service. Also, a third policy is attached to a WSDL logical object as in Scenario 1. So you attach two policies to a service provider and one policy to another service that consumes the first.

Figure 8. A more complex scenario
A more complex scenario

Here are the guidelines applied to the first Service Version:

  1. Make the two policy attachments used with the first Service Version two separately governable entities.
  2. Create ppRelationship relationships from Service Version 1 to the policy attachment for the SLD and to the policy attachment for the WSDL logical object. These relationships are shown in red in Figure 8.
  3. Configure the promotion properties to ignore the ppRelationship relationships and to exclude all appliesTo relationships for the specific transitions against which all of the policy attachments will be promoted.
  4. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  5. Ensure policy re-evaluation is enabled on the target registry.
  6. Promote the two policy attachments for this Service Version. The order in which they have to be promoted is not important, but they should both be promoted before the Service Versions to prevent a service from being imported onto a target registry before any associated runtime policies.
  7. Promote the first Service Version.

Here are the guidelines applied to the second Service Version:

  1. Make the policy attachments used in the second Service Version separately governable entities.
  2. Create a ppRelationship relationship from Service Version 2 to the policy attachment for the SLA. This relationship is shown in red in Figure 8.
  3. Recheck that the promotion properties are set to ignore the ppRelationship relationship and exclude all appliesTo relationships for the transitions against which all of the policy attachments will be promoted.
  4. Recheck that disableOnImport is still set on the correlator modifier properties for the target registry.
  5. Recheck that policy re-evaluation is enabled on the target registry.
  6. Promote the policy attachments for the second Service Version before the Service Version, again, to prevent a service from being imported onto a target registry before any associated runtime policies.
  7. Promote the second Service Version.

The two Service Versions are dealt with separately, because in most situations, the first service must be put into production before the second service, which uses the first, is developed.

Scenario 8. Promotion filtering

You may have a requirement when promoting services that certain objects on the target registries are set up specifically for that registry. Two typical examples:

  • You may need to implement service endpoints on a production or test registry that are different from those on the development registry.
  • You may need different policy attachments on a production or test registry.

Promotion filtering lets you classify such objects for target registries. This scenario illustrates the use of promotion filtering to implement different endpoints on the two targets. It is based on the service used in Scenario 1.

Figure 9. Promotion with policies attached to different endpoints
Promotion with policies attached to different endpoints

The WSDLs used in the other scenarios were all monolithic -- in other words, the service details were defined completely in one XML file. However, WSDLs can be split and stored in Service Registry as several different constituent parts:

  • A service schema XSD file (common across endpoints)
  • A service interface WSDL (common across endpoints)
  • A specification endpoint WSDL
  • A development endpoint WSDL
  • A staging endpoint WSDL
  • A production endpoint WSDL

Promotion filtering works with either monolithic or split WSDL files, but if you are using a monolithic WSDL, you must copy and duplicate the entire WSDL for each different endpoint. Therefore the shared information in the WSDL is duplicated in several different files, which complicates maintenance. You should therefore split your WSDL into the above parts before loading it into Service Registry, but if this is not feasible then it will have to be duplicated as described. The set up here is based on Scenario 1, but with the WSDL split as described above. Two policies are then attached to two WSDL ports associated with the staging and production endpoints, resulting in five promotion zip files:

For the staging target registry:

  • The Service Version zip
  • The policy attachment zip for the staging environment
  • The policy attachment zip for the production environment

For the production target registry:

  • The Service Version zip
  • The policy attachment zip for the production environment

When promoting the policy attachment related to the production endpoint, the model required that a staging promotion be performed first, even though the policy attachment was for the production registry. This requirement is considered a restriction in the GEP model.

When promoting the policy attachment related to the staging endpoint, the GEP model requires a promotion for the production registry, even though the policy attachment is for the staging registry. Again, this requirement is considered a restriction in the GEP model. The above two issues mean that the GEP should be enhanced to facilitate this type of promotion, particularly if you need to use synchronous promotion.

Considering the policy promotion guidelines established above, the following steps were performed:

  1. Make the three policy attachments three separately governable entities.
  2. Set up two ppRelationship relationships from the Service Version to each policy attachment.
  3. Set the policy promotion configuration to ignore the ppRelationship relationship.
  4. Set the policy promotion configuration to ignore the appliesTo relationship.
  5. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  6. Ensure Policy re-evaluation is enabled on the two target registries.
  7. Promote the policy attachment for the staging registry.
  8. Promote the Service Version to the staging registry.
  9. Promote the policy attachment for the production registry.
  10. Promote the Service Version to the production registry.

This scenario shows that when using policy promotion with many services and policies, a large number of promotion zips are created, which take time to process. Because policy re-evaluation is being used however, it does not matter in what order these promotion zips are imported, except that policy attachment zips should be imported before Service Version zips.

If you use promotion filtering in this way to classify policy attachments for different runtimes, there may be warning messages in the WebSphere Application Server log file when promoting the service or policy. You can ignore these warnings, and they do not indicate any restriction in the use of the functionality.

Scenario 9. Re-promotion

On the first promotion of an object, all logical objects that flow away will be included in the set of objects being promoted. Objects are included down levels in the object hierarchy until there are no outward relationships from that object onwards. Re-promotion works differently, as it only works on objects that are in the governed collection for the object being promoted. Therefore it is important to ensure first that the metadata you want to change belongs to an object in the list of objects in the governance collection for the object being promoted. With a Service Version for example, complete the following steps:

  1. Open the Administrator perspective.
  2. Click Service Versions.
  3. Select the required service version to display its details.
  4. Select the Governance tab.
  5. In the Additional properties pane, click Governed Objects.

This displays the governed objects. For example:

Figure 10. Service Version governed objects
Service Version governed objects

You can see that the Service Binding correlated object is present in this list, but the WSDL Binding WSDL object is not. So on the first promotion of a Service Version to a target registry, the WSDL Binding and Service Binding objects are both created. But on subsequent re-promotions, any changes to the WSDL Binding are not reflected on the target, as the WSDL Binding object is not part of the governed collection. However, changes to the service binding are propagated to the target registry on re-promotion.

For a policy attachment document that has been made separately governable, only the policy attachment document itself is included in the list:

Figure 11. Policy attachment governed objects
Policy attachment governed objects

This section describes re-promotion with the simple scenario introduced above with one WSDL document and a single policy attachment. The guidelines are applied for the initial promotion and subsequent re-promotion as follows:

  1. Make the policy attachment document a separately governable entity.
  2. Set up a ppRelationship relationship from the Service Version to the policy attachment document.
  3. Ensure that the policy promotion configuration is set to ignore the ppRelationship relationship.
  4. Ensure that the policy promotion configuration is set to ignore the appliesTo relationship.
  5. Ensure that disableOnImport is set on the correlator modifier properties for the target registry.
  6. Ensure that policy re-evaluation is enabled on the two target registries.
  7. Perform the initial promotion of the policy attachment to the target registry. If it is done manually, make sure the promotion zip file is given an appropriate name that will help you identify it. It is also useful to include a timestamp within the filename. For example: StagingPromotion_PA_Firstpromotion_20110225162640906.zip.
  8. Perform the initial promotion of the Service Version to the target registry. Again make sure it is named appropriately. For example: StagingPromotion_SV_Firstpromotion_20110225162738203.zip.
  9. Change the metadata associated with the Service Version and PolicyAttachment document by adding a new property to these objects. These are both included in the respective governance collections as described above.
  10. Re-promote the policy attachment. If it is done manually, make sure the promotion zip file is given an appropriate name that will help you identify it. For example: StagingPromotion_PA_Repromotion_20110225163129218.zip.
  11. Re-promote the Service Version. Again make sure it is named appropriately. For example: StagingPromotion_SV_Repromotion_20110225163302875.zip.

Using the ppRelationship relationship to review policies attached to a service

Having the ppRelationship relationship from a Service Version to the policy attachments that apply to it makes it easy to see which policies are applied to a particular service. Just click on the Service Version of interest from Registry and inspect the list of policy attachments shown under ppRelationship, as shown below from the data used in Scenario 5:

Figure 12. Inspecting the list of policy attachments for a service
Inspecting the list of policy attachments for a service

The list of policy attachments is listed under ppRelationship in the Relationships pane as shown in the expanded selection below:

Figure 13. Expanding the list of policy attachments for a service
Expanding the list of policy attachments for a service

To display policy details, click on a specific policy attachment and then click on the Policy tab:

Figure 14. Individual policy details
Individual policy details

Download

DescriptionNameSize
Code samplePolicyPromotion.zip30 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=659519
ArticleTitle=Policy promotion with WebSphere Service Registry and Repository
publish-date=05182011