WebSphere ESB endpoint selection based on the

WebSphere Service Registry and Repository

Governance Enablement Profile

Kevin Postreich (IBM)

Brian Hulse (IBM)

March 2011
Introduction
With the introduction of WebSphere Enterprise Service Bus v7.0 (WESB), there are
multiple ways to select dynamic endpoints within a mediation flow using SOAP
Action/PortType etc., using information stored in WebSphere Service Registry and
Repository (WSRR). Equally, any endpoints selected can be checked against any Service
Level Agreements (SLA) in WSRR. However, what cannot be done out of the box, as yet,
is endpoint selection based on general Governance Enablement Profile (GEP) objects in
WSRR; this paper shows you how to do this. This paper serves as a step by step account
of how to create a Service Gateway Mediation Flow in WESB which will allow for endpoint
selection based upon an active SLA between a particular consumer and an agreed
endpoint. Moreover, it shows how to define the meta-data objects in WSRR and govern
them so that the whole scenario, from governance master to ESB accessed run-time is
successfully implemented.

This paper makes use of WebSphere Enterprise Service Bus v7.0 (WESB) and
WebSphere Service Registry and Repository v7.0 (WSRR).

The paper is divided into two main sections, covering activities in the two products, WESB
and WSRR. The first part deals with the construction of a WESB mediation flow which will
allow for endpoint selection based on a service consumer->service provider relationship
via a Service Level Agreement (SLA). The second deals with the governance story;
defining the service consumer, the service provider and all of the artifacts associated with
them.

Part1: Introducing the WESB artifacts

If you use WESB to integrate your enterprise and model your business in WSRR using its
Governance Enablement Profile (GEP), it is likely that you would want to select on
dynamic endpoints based on a number of factors modelled in that profile. For example:

* Whether the Consumer of the endpoint has a valid SLA for the endpoint
* Whether the particular SLA is active
* Whether the endpoint is on-line
* Whether the endpoint has a certain desired classification; whether it is Production or
Development for example.

This is a much more business-centric view of the world, rather than a more IT-centric view.
For example in the GEP there are a number of key objects; considering the following
Figure.
Figure 1. Governance Enablement Profile objects

• A Consumer wishes to use a particular Service

• This relationship is described by the dependency between a Consumer Version and a
Service Version
• More particularly, this relationship is typified by an operational dependency between a
Service Level Agreement and a Service Level Definition

Looking at the scenario overall, the consumer makes a request via a specific WESB
Mediation which is acting as a Service Gateway for all requests requiring validation via the
WSRR GEP. The Mediation consults the registry to check on the inter-relationships shown,
moreover, some of the objects have to be in the correct states and have the correct
classifications for the endpoint selection to be successful. However, if all of these checks
pass, the Mediation knows the final target for the consumer, and routes the request
accordingly. This paper explores, in a step by step fashion, this scenario in detail.

Figure 2 illustrates the meta-data, in their appropriate life-cycle states, that must be
contained in the Service Registry.

1. Service Consumer (Consumer Version)

2. Service Level Agreement (SLA)
3. Service Level Definition (SLD)
4. Service Provider (Business Service Version)
5. Service Provider Endpoint
Figure 2. GEP Service Gateway Mediation
Strategy
The solution has three basic parts to it:

Table 1. Solution elements

Element Description Usage
Service Gateway This will feature a Custom Mediation Primitive to contain the Installed as a WESB
Mediation java code described below. This code will extract information Mediation Flow
relevant to an endpoint lookup, call WSRR to extract the
target address of a suitable endpoint and load that into the
WESB Service Message Object (SMO) so that WESB can
dynamically route the request.
Named Query Since WSRR's GEP is customisable, it is unwise to have any Installed as a Named
knowledge of its structure inside the Mediation itself. With this Query on WSRR
in mind, we make use of WSRR's Named Query capability.
This allows for a pre-defined set of parameters to be passed
to a pre-constructed query on WSRR itself.
Handling of In order for the named query to work, the consumer ID,
named query context ID and endpoint classification need to be known. How
parameters these are obtained is up to your own environment, but we
present two solutions here, one using a SOAP Header and
one using HTTP authentication header.
(a) SOAP Header
The Custom Mediation requires certain parameters to call the
Named Query relating to the GEP being queried. However,
these may not be architected as part of the incoming request
message. In fact, in the case of a Service Gateway pattern,
this is very unlikely as it could service many different request
types. There are many patterns of behaviour that can be used
to overcome this, but in this particular example, we will insert
this meta-data into a SOAP Header, leaving the request
message body in tact. Consequently, we will need a handler
to be activated by the consumer; in our case we are using a
JAX-RPC handler. This is shown in Figure 3(a).
(b) HTTP Header
In this solution we extract these values from the client's HTTP
Authentication Header which then seeds the SOAP header to
be read in a routing mediation. This is shown in Figure 3(b).

In Figure 3(a) there is a single Custom Mediation Primitive, called Route Message, which
extracts the information from the SOAP Header, having previously been seeded by the
JAX-RPC handler and uses this information to query WSRR to find where to route the
request. Alternatively, when using the HTTP Header, in Figure 3(b) there are two Custom
Mediation Primitives, the first extracts information from the HTTP authentication header
and places it in the SOAP header; this code is explained later in Listing 4. The second
uses this information to query WSRR to find where to route the request.
Figure 3(a). Elements for endpoint selection using SOAP Header

Figure 3(b). Elements for endpoint selection using HTTP Header

In our example, the service provider will be a temperature conversion service, the
consumer will be a weather service which makes used of this temperature conversion
service. This is illustrated by Figure 4. The mediation shown throughout this scenario is
actually much more powerful since it is a Service Gateway pattern, so any type of endpoint
can be requested; the services shown are concrete examples of usage.

Figure 4. Temperature Converter

In this particular example there are two endpoints for the same provider of the temperature
converter service, where one endpoint (the internal one) is proxied by gateway mediation
whose endpoint is the exposed endpoint.

Figure 5. Temperature Converter States

Now we will examine each of the three elements in the solution in detail.

Named Query
As stated earlier, the Named Query is going to look for those endpoints which have an
active SLA in play for the particular consumer and that the particular endpoint(s) conform
to some required set of classifications, which in this example could be PRODUCTION and
INTERNAL. Additionally, the endpoint is required to be ONLINE.
The Named Query gathers three pieces of information in order to perform this look-up:

Table 2. Query Parameters

Parameter Description
Consumer This is a unique identifier which typifies the consumer; it is a field in the Consumer
Identifier Version.
Context This is a unique identifier which typifies the interactions in this relationship; it is a field in
Identifier the Service Level Agreement.
Endpoint This is an additional search constraint associated with the endpoint; it is a classification
Classification of the Service Endpoint
How these identifiers are used and defined is entirely specific to your own
installation/enterprise, but an understanding of how these are used in this named query
should inform your naming strategy. Additional search criteria can easily be added if these
are needed for your particular installation.
The WSRR query which will be activated in the Named Query using these parameters:

Figure 6. WSRR Query

In this query we have:

* %1 Which is the Consumer Identifier

* %2 Which is the Context Identifier
* %3 Which is the Endpoint Classification
This query needs to be wrapped in some xml before it can be imported into WSRR as a
Named Query, more specifically:

Figure 7. Named Query

The actual query string needs to be placed inside of the xpath tags. The query depth for
our named query SLAEndpontLookup is set to a depth of 0, which means that the
endpoints would be returned with just properties and classifications; no relationships would
be populated. For this example we are only concerned with the endpointAddress, so a
depth of 0 will result in a much quicker query. The non-zero queryDepth may be needed
for different scenarios.

The updated Named Query file should be saved as SLAEndpointLookup.xml.

This needs to be imported into WSRR:

• Change to the Configuration perspective on the WSRR console.

• Select Named Queries from the Active Profile menu item.
• Load the SLAEndpointLookup.xml file using the Load Named Query Configuration
• button supplying SLAEndpointLookup as the name of the query.
Figure 8. Loading the Named Query

It is also important to note here that the Named Query stated here assumes that the GEP
supplied with WSRR has not been customised in any way. If the GEP has been
customised, the query will need to be modified accordingly. Isolating the query into a
Named Query gives much greater flexibility when it comes to customising models in
WSRR.

Mediation
The next part of the solution is the WESB Mediation; this is developed using WebSphere
Integration Developer (WID).

Service Gateway Pattern

From the Business Integration perspective select the Open Patterns Explorer and then
create a new instance of a Dynamic Service Gateway.

Figure 9. Dynamic Service Gateway

In the Configure Pattern Parameters window, for the Routing Option select Write my own
logic; for all other values accept the default values.

Figure 10. Service Gateway Configuration

This will create a service gateway mediation flow with a single custom mediation primitive
to contain the routing logic. We will, however, have to change this for one of the two
alternative patterns, namely, the HTTP Header variant.
Figure 11. Mediation Flow

Update the Build Path

We are going to add in calls to WSRR in the routing custom mediation primitive using
WESB's proxy interface, as supplied in WESB 7.0. However, there is a known bug in the
build configuration, so an extra jar file needs to be added into the build path for our
gateway project. The proxy interface was first available in WESB 7.0, and as of WESB
7.0.0.2 still exist, however, a fix should be available in future releases; documentation for
your current release should be consulted to make sure that this step is needed. However,
for WESB releases without a fix:

1. Right click on the gateway project and select Properties

2. Select Java Build Path and then the Libraries tab
3. Select Add External JARs ...
4. Locate the plugins directory for your WPS/WESB installation
5. Select the com.ibm.sibx.runtime_6.1.0.jar file

Before we can update the java code in the custom mediation primitive, we must do the
following:

* Change the terminals of the custom mediation primitive

* Add in user properties for the custom mediation primitive
Modify the RouteMessage Custom Mediation Primitive
Open the custom mediation primitive and select the Properties tab and then the Properties
section. Add in a new user property called registryName. Select the Promotable
Properties section and promote this property. This allows which registry is being used to
be controlled via administration control. You will notice that the value for the
registryName is blank. This informs WESB that it should use the default WSRR
definition for the application server. How this WSRR definition is set up, and how it is
secured in covered later in this paper. For now, all we need to know is that WESB uses the
default registry.

Figure 12. User Properties

Now select the Terminal section, change name of the first out terminal to found. Next add
in a new out terminal called, notFound.

Figure 13. Terminals

The notFound terminal will be used when there is no matching SLA found; the fault
conditions for the flow should really match your local installation policies for fault handling,
but for this example, we simply wire the notFound terminal to the Input Response, and the
fail terminal to the Input Fault.
Figure 14. Updated Mediation Flow

Adding the Java code

Now select the Java Imports section and add in the following:

Listing 1. Java Imports

import com.ibm.wsspi.sibx.mediation.wsrr.client.ServiceRegistryProxy;
import com.ibm.wsspi.sibx.mediation.wsrr.client.ServiceRegistryProxyFactory;
import com.ibm.wsspi.sibx.mediation.wsrr.client.data.ServiceRegistryDataGraphList;
import com.ibm.wsspi.sibx.mediation.wsrr.client.exception.ServiceRegistryProxyException;
import com.ibm.wsspi.sibx.mediation.wsrr.client.jaxrpc.types.DataGraphType;
import com.ibm.wsspi.sibx.mediation.wsrr.client.jaxrpc.BaseObject;
import java.util.List;

Now select the Details section and add in the following:

Listing 2. RouteMessage custom mediation Java code

String namedQuery = "SLAEndpointLookup";
String consumerID = "";
String contextID = "";
String endpointClassification = "";
if (smo.get("/headers/SOAPHeader[name='GEPGatewayHeader']/value/consumerID")!=null) {
consumerID = smo.getString(
"/headers/SOAPHeader[name='GEPGatewayHeader']/value/consumerID");
}
if (smo.get("/headers/SOAPHeader[name='GEPGatewayHeader']/value/contextID")!=null) {
contextID = smo.getString(
"/headers/SOAPHeader[name='GEPGatewayHeader']/value/contextID");
}
if (smo.get(
"/headers/SOAPHeader[name='GEPGatewayHeader']/value/endpointClassification")!=null) {
endpointClassification = smo.getString(
"/headers/SOAPHeader[name='GEPGatewayHeader']/value/endpointClassification");
}
boolean isFound = false;
try {
ServiceRegistryProxy srProxy = null;
if ((registryName == null) || (registryName == "")) {
srProxy =
ServiceRegistryProxyFactory.getInstance().getDefaultServiceRegistryProxy();
} else {
srProxy =
ServiceRegistryProxyFactory.getInstance().getServiceRegistryProxy(registryName);
}
String params[] = new String[3];
params[0] = consumerID;
params[1] = contextID;
params[2] = endpointClassification;
ServiceRegistryDataGraphList srList = srProxy.namedQuery(namedQuery, params);
if (srList.getDataGraphs() != null) {
isFound = true;
 List<DataGraphType> dgList = srList.getDataGraphs();
if (dgList.size() > 0) {
DataGraphType dg = dgList.get(0);
BaseObject[] topLevelObjects = dg.getWSRR().getArtefacts();
if (topLevelObjects.length > 0) {
BaseObject base = topLevelObjects[0];
// The name of the CapabilityVersion is the endpoint we need
String endpointAddress = base.getName();
smo.setString("headers/SMOHeader/Target/address", endpointAddress);
isFound = true;
}
}
}
} catch(ServiceRegistryProxyException e) {
e.printStackTrace();
}
if (isFound) {
found.fire(smo);
} else {
notFound.fire(smo);
}

The code performs the following function:

1. Extracts the three parameters for the Named Query from specific locations in the
SOAP Header. It is important to note that this should not be seen as prescriptive, this
information can be transmitted and extracted in whatever method suits your enterprise; in
this example, the location matches what is set up with the Handler, described in the next
section.
2. Uses these three parameters to call the named query SLAEndpointLookup. These are
loaded into the call in the same order as that expected by the named query we have
already loaded into WSRR. It should also be noted that the name of the query is the same
as it was loaded into WSRR in the previous section.
3. Checks the return from the named query, if there is an object returned, it assumes it is
a Service Endpoint, which has a name which is the target endpoint required.
4. If the target has been found, it is loaded into the correct part of the SMO to activate
the dynamic routing, and the found terminal is fired.
5. If the named query does not return an object, the notFound terminal is fired.
Adding the schema for the SOAP Headers
In order for the service gateway to be able to parse the headers in the request message,
the schema for those headers needs to be available at run-time; we must define the
Business Object. Under the gateway project in the Business Perspective select the Data
Types section. Now right click and select New and then Business Object. A new business
object has to be created with the correct namespace and the correct parameters to
represent the SOAP header.

Figure 15. SOAP Header Business Object

We must now look at the two alternative ways of extracting the information needed in the
named query which map to the fields in the GEPGatewayHeader.
Alternative 1: Using a JAX-RPC Handler
The final part of the picture is the piece of code which will add in the SOAP Header at the
client/consumer site. In this example, we have implemented this as a JAX-RPC handler,
but as was stated earlier, this can be done in whatever way suits your enterprise
installation with whatever bindings you have implemented.

Listing 3. JAX-RPC Handler

package com.ibm.sample;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPHeader;

public class GEPGatewayRPCHandler extends GenericHandler {

public static final String PROP_CONSUMER_ID =
"com.ibm.wsrr.ws.client.jaxrpc.consumerid";
public static final String PROP_CONTEXT_ID =
"com.ibm.wsrr.ws.client.jaxrpc.contextid";
public static final String PROP_ENDPOINT_CLASSIFICATION =
"com.ibm.wsrr.ws.client.jaxrpc.endpointclassification";

private String consumerID;

private String contextID;
private String endpointClassification;

public void init(HandlerInfo hi) {

consumerID =
(String)hi.getHandlerConfig().get(PROP_CONSUMER_ID);
contextID =
(String)hi.getHandlerConfig().get(PROP_CONTEXT_ID);
endpointClassification =
(String)hi.getHandlerConfig().get(PROP_ENDPOINT_CLASSIFICATION);
}

public boolean handleRequest(MessageContext messagecontext) {

try {
if (messagecontext instanceof SOAPMessageContext) {
SOAPMessageContext smc = (SOAPMessageContext)messagecontext;
SOAPBody body = smc.getMessage().getSOAPBody();
SOAPEnvelope envelope = smc.getMessage().getSOAPPart().getEnvelope();
SOAPHeader header = envelope.getHeader();
SOAPFactory sFactory = SOAPFactory.newInstance();

SOAPElement headerElement =
sFactory.createElement("GEPGatewayHeader",
"gep",
"http://com.ibm.sample.gepgateway");

SOAPElement contextElement =
sFactory.createElement("contextID",
"gep",
"http://com.ibm.sample.gepgateway");
contextElement.addTextNode(contextID);
headerElement.addChildElement(contextElement);

SOAPElement consumerElement =
sFactory.createElement("consumerID",
"gep",
"http://com.ibm.sample.gepgateway");
consumerElement.addTextNode(consumerID);
headerElement.addChildElement(consumerElement);

SOAPElement endpointClassificationElement =
sFactory.createElement("endpointClassification",
"gep",
"http://com.ibm.sample.gepgateway");
 endpointClassificationElement.addTextNode(endpointClassification);
headerElement.addChildElement(endpointClassificationElement);

header.addChildElement(headerElement);
}
} catch (SOAPException soapEx) {
throw new RuntimeException(soapEx.toString());
}
return true;
}
}

The code performs the following function:

1. Initialises the handler with the values for the three parameters to be used in the
named query called from the mediation. In a JAX-RPC handler these are supplied as part
of the deployment file, so can be tied specifically to the particular cient/consumer. The xml
for this example is shown below.
2. Creates an element in the SOAP Header which represents the business object we
defined previously in the mediation flow. The namespace and name should match the
previously defined business object, which in our case are
http://com.ibm.sample.gepgateway and GEPGatewayHeader.
3. Populates this element with three text elements containing the three named
parameters, which in our case are:
▪ consumerID
▪ contextID
▪ endpointClassification

Figure 16. JAX-RPC Handler configuration

We now have the three major elements in play, the Handler at the client/consumer site
which populates a SOAP Header so when the request message arrives at the WESB
service gateway, the parameters can be extracted by the Routing Mediation Primitive, and
used to call a Named Query on WSRR to extract the relevant Service Endpoint; allowing
WESB to dynamically route to that endpoint.
Looking at a WESB trace with this configuration in play we can see the SOAP Header
which will be interpreted by the custom mediation code.

Figure 17. SOAP Header in WESB trace

Alternative 2: Using HTTP Headers
All of the mediation discussion so far as been about the configuration shown in Figure
3(a), namely, using SOAP Headers from the client application to contain the values of
consumer ID and context ID. The process to produce the configuration in 3(b) is very
similar in terms of creating a Service Gateway Mediation, it just requires the addition of a
couple of mediation primitives. Figure 15 shows these mediation primitives in order.

Figure 18. Mediation Flow for use with HTTP Headers

The mediation primitives perform the following:

• The CreateGEPHeader creates the GEPGatewayHeader using the standard SOAP
Header Setter mediation primitive ready for use by PopulateGEPHeader.
• The PopulateGEPHeader custom mediation primitive populates the
GEPGatewayHeader by extracting information from the HTTP authentication header.
• The RouteMessage custom mediation primitive uses the information in
GEPGatewayHeader to call the Named Query to find a suitable endpoint and route to
it.

The RouteMessage mediation primitive has already covered in Listing 2. What we now
need to cover is the code for PopulateGEPHeader .

Consumer ID
The Consumer ID is obtained from the clients HTTP Authentication Header.

Listing 4. Handling the Consumer ID in PopulateGEPHeader

if (smo.get("/headers/HTTPHeader/header[name='Authorization']")!=null) {
/**
* Getting the ConsumerId passed in HTTP Basic Auth as the Username
* Finding the Authorization Tag which is where the Username:Password resides
*/
String consumerID = smo.getString("/headers/HTTPHeader/header[name='Authorization']/value");

/**
* This string appears as "Basic 64BitEncryptedUserIdAndPassword"
*/
consumerID = consumerID.substring(6);

/**
* Decode the Base64 encoded ID.
* Set the GEPGatewayHeader with the consumer ID
*/
String decodedText=new String(Base64.decodeBase64(consumerID.getBytes()));
int myInt = decodedText.indexOf(":");
decodedText = decodedText.substring(0, myInt);
System.out.println("###" + decodedText + "###");
smo.setString("/headers/SOAPHeader[name='GEPGatewayHeader']/value/consumerID", decodedText);
} else {
smo.setString("/headers/SOAPHeader[name='GEPGatewayHeader']/value/consumerID",
"Consumer ID not provided");
}
The code performs the following function:

• Checks for the existence of the HTTP Basic Auth Header

• Set the ConsumerID variable with the value of the HTTP Basic Auth header
• Decode the Base64 encoded Auth header value
• Set the GEPGatewayHeader with the USER portion of the Auth Header value
• If the HTTP Basic Auth Header does not exist, return an error to the consumer.

Context ID
The Context ID is obtained from the message payload; specifically, the target namespace
of the service being invoked. This process requires parsing of the message payload as
illustrated in Listing 4.

Listing 5. Handling the Context ID in PopulateGEPHeader

if (smo.get("/body/message/value")!= null) {

String message = smo.getString("/body/message/value");

String namespacePrefix = message.substring(1, message.indexOf(":"));

String ns = "xmlns:"+namespacePrefix+"=";
int nsLength = ns.length();

message = message.substring(message.indexOf("xmlns:"+namespacePrefix+"=") + nsLength + 1);

int quote = message.indexOf("\"");

message = message.substring(0, quote);

smo.setString("/headers/SOAPHeader[name='GEPGatewayHeader']/value/contextID", message);
} else {
smo.setString("/headers/SOAPHeader[name='GEPGatewayHeader']/value/contextID",
"Context ID not provided");
}
out.fire(smo);

The code performs the following function:

◦ Checks for the existence of a message body
◦ Obtain the message body into the ‘message’ variable
▪ This is an example request body:
<v1:retrieveCustomerRemarks
xmlns:v1="http://www.huntington.com/esb/interface/CustomerInqService/v1_3">
<v11:RetrieveCustomerRemarksIn
xmlns:v11="http://www.huntington.com/esb/data_type/RetrieveCustomerRemarks/v1_0">
<v11:CustPermId>26974394</v11:CustPermId>
</v11:RetrieveCustomerRemarksIn>
</v1:retrieveCustomerRemarks>

◦ Obtain the namespace ‘prefix’

▪ This is an example namespace prefix:
v1

◦ Obtain the namespace which matches the namespace prefix

▪ This is an example namespace prefix

http://www.huntington.com/esb/interface/CustomerInqService/v1_3

◦ Set the GEPGatewayHeader with the matching target namespace

WESB Summary

The first part of this paper showed how to create a service gateway in WESB which
extracts an endpoint to dynamically route to, based on a query of GEP objects defined in
WSRR. The solution consists of three major elements:

* A WSRR Named Query

* A WESB Mediation to extract information used in the Named Query
* Additionally a JAX-RPC Handler to seed this information

It showed a simple temperature conversion WebService, accessed via the WESB service
gateway, showing how the SOAP header was populated and then interpreted by a WESB
Mediation so that WESB could route to the correct endpoint for that service, based on pre-
selected GEP criteria.
Part 2: Configuring the environments and Governing
the Service meta-data
Figure 2 illustrated the meta-data required in the Service Registry for this scenario. This
part of the paper looks at how these objects get created and how they are transitioned into
the correct states in a governed fashion.

This part of the paper is organized into two primary sections:

1. How to configure the WESB server (WebSphere Application Server)
• SSL configuration to connect to a secured WSRR environment
• WSRR definition and connection configuration
2. How to populate and govern the meta-data in WSRR for dynamic endpoint look-up
• Load and activate the Governance Enablement Profile
• Populate and govern a Service provider and associated endpoints
• Populate and govern a Service consumer and its associated SLA

Obtain the WSRR server security certificate

WSRR runs as a secure J2EE application on WebSphere application server. As such,

clients that connect to the Service Registry are required to do so via an SSL connection.
The SSL connection requires that the WSRR server’s public key be stored in the client's
Trust Store. In this case, the client's Trust Store is the WebSphere environment hosting
WESB.

This section describes how to use the WebSphere administrative console hosting WESB
to import the WSRR public certificate. This step is required when WESB is connecting to a
secure WSRR configuration, and WSRR / WESB are NOT running in the same
WebSphere ND cell. This is the most typical configuration found in customer
environments.
(1) As an ‘administrator’ ID, login to the WebSphere administrative console in the WESB
environment.
(2) Navigate to Security à SSL Certificates and key management à Key stores and
certificates

Figure 19. SSL certificate and key management

(3) Select ‘NodeDefaultTrustStore’ or your custom trust store if one was created.

Figure 20. NodeDefaultTrustStore

(4) Under the ‘Additional Properties’ on the right side of the pane, section, select
‘Signer certificates’. Here, you will see a list of the client certificates that have been
imported into your trust store.

Figure 21. Signer certificates

The next step is to import the WSRR signer certificate into the WESB trust store.
(5) Click on the button labeled ‘Retrieve from port’.

• Provide the correct Host and SSL port of the WSRR server.

TIP: A connection will be attempted, so if there is a firewall between the servers.

You will have to modify the firewall rules, or manually export / import the certificates.

• Provide an ‘Alias’ name for the certificate. The example here uses ‘wsrr_70’.

• Click the button labeled ‘Retrieve signer information’

Figure 22. Retrieve from port

NOTE: As shown below, if the connection information you entered was correct, the signer
information will be displayed.
Figure 23. Retrieve signer information

(6) Click the button labeled ‘OK’ to add the certificate to the trust store.

The ‘wsrr_70’ signer certificate is now saved in the WESB server’s trust store.

Figure 24. Signed certificates view

Setup a default WSRR Definition

Once the signer certificate from the WSRR server is saved in the WESB trust store, we are
able to configure the WSRR connection information.

The Java Custom Mediation Primitive on WESB leverages the

ServiceRegistryProxyFactory API to obtain a WSRR server connection.

The benefits of using the ServiceRegistryProxyFactory are that it obtains the WSRR
connection information saved in the WebSphere configuration. Therefore hard coded
connections are not required in the Java code. The configuration definition in WebSphere
also provides for time based caching capabilities. As such the data returned from the
Custom Mediation Primitive is cached in a WebSphere managed cache.

The following code snippet from the Custom Mediation Primitive will return the ‘DEFAULT’
WSRR definition defined in the WebSphere Administrative console of the WESB server.
srProxy = ServiceRegistryProxyFactory.getInstance().getDefaultServiceRegistryProxy();

It is possible to have multiple WSRR connections defined in WebSphere, and the custom
Java mediation can use any of them, as illustrated in the code snippet below.
srProxy = ServiceRegistryProxyFactory.getInstance().getServiceRegistryProxy(registryName);

These are shown in the code snippet tagged as Listing 2 and since the registryName
User property is blank in our example, the Custom Mediation Primitive will use the default
registry. In order that this to be successful, we must define this default registry definition to
the WebSphere environment.
This step describes how to configure a default WSRR registry connection in the
WebSphere environment hosting WESB.

(1) As an administrator user, login into the WebSphere Administrative console (WESB
server)
(2) Navigate to Service Integration à WSRR Definitions

Figure 25. WSRR Definitions

(3) Click the button labeled ‘New’ to create a new WSRR definition.

Provide the following information on the form:

◦ WSRR Definition Name: I specified ITSO_WSRR

◦ Default WSRR Definition: Yes
◦ Timeout of Cache: For testing purposes, I reduced the cache timeout to a very low
value. In a real implementation, the timeout value will likely be much larger.
◦ Connection Type: Web Service

NOTE: The timeout is specified in seconds based on the time of the last server restart.
Figure 26. WSRR Definition details

(4) Click the ‘Apply’ button.

(5) Under the section labeled ‘Additional Properties’, select ‘Connection Properties’.
(6) Complete the form by specifying the following properties:

◦ Modify the Registry URL by specifying the correct hostname and port number of
the WSRR server.
TIP: Only change the host and port number in the registry URL.
◦ SSL Configuration: Select NodeDefaultSSLSettings (This is the same SSL
configuration that we added the WSRR signer certificate).

(7) Click the button labeled ‘Apply’ to save the current configuration.
We must first setup a JAAS J2C authentication alias before we can select set the
Authentication Alias property.

Figure 27. WSRR Definition connection properties

(8) Under the ‘Related Items’ section, select ’JAAS – J2C Authentication data’.

Here, we will configure a user ID and password used to connect to the WSRR registry.

Your secured WSRR configuration should already be configured with specified users
which are mapped to the Administrator or Users J2EE role. By default, these are
configured to ALL AUTHENTICATED USERS. In other words, any valid user ID in the
security server configured for WSRR is authenticated to login and accesses the repository
data.

If your WSRR server is configured with LDAP, then specify a valid user ID in the LDAP
server. Otherwise, you may have configured a federated repository and specified local
user IDs in a file based repository (For testing purposes).
Figure 28. WSRR Definition authentication data

(9) Click the ‘New’ button to create a new Alias.

◦ Complete the form with VALID user ID credentials that will be used to connect to
WSRR.

NOTE: The Alias field can be any unique value. However the User ID and Password must
be valid in your security server.
(10) Click the ‘OK’ button to save the authentication alias.

Figure 29. WSRR Definition authentication data details

(11)Save the configuration changes to the master configuration.

Figure 30. WSRR Definition save

(12) Use the bread crumb trail at the top of the page to navigate back to the Web
Services of the WSRR definition

WSRR definitions à ITSO_WSRR à Web Services

(13) Select the new Authentication Alias (WSRRAlias).

Figure 31. WSRR Definition selection

(14) Click the ‘OK’ button’ to save the changes, then select ‘save’ to save the changes to
the master configuration.

(15) Test the WSRR connection

Select the ITSO_WSRR WSRR definition, and click the ‘Test Connection’ button.

Figure 32. WSRR Definition test

Assuming the configuration is correct, the test connection should pass the test.
Figure 33. WSRR Definition test result

Troubleshooting connection issues

If errors occur, consult the SystemOut.log on the WebSphere server hosting WESB.

Possible reasons for connection failures:

• SSL configuration is incomplete or incorrect

• The User ID or Password in the JAAS alias is incorrect
• Firewall issues between the WESB server and the WSRR server.
• Incorrect Host or Port number specified in the connection URL
https://localhost:9451/WSRRCoreSDO/services/WSRRCoreSDOPort

TIP:
(1) Go to a Web Browser on the WSRR server, and paste the connection URL you
specified in the WSRR definition into a web browser to verify a web service port is active.

You should get a security warning about the certificate, Click ‘Continue to this Web Site’
Figure 34. Certificate Error
(2) Enter your valid security credentials to the WSRR server.

This should be the same as defined in our JAAS Alias.

Figure 35. Security Credentials

(3) Finally, the response from the Web Service Engine stating that you hit a valid web
service port.

Figure 36. Web Service check

The Governance Model
The governance model below illustrates the service consumer and service provider meta-
data that is required to be entered into the registry to support the governance process.
This governed data is the basis for providing access to services through the ESB and our
dynamic service gateway. Without following the enterprise governance (approval) process
to model valid consumer / provider relationship, the ESB will reject a potential consumers
request to invoke the service provider endpoint.

Figure 37. WSRR Governance Model

All of the activity in this section will be performed from the WSRR Web UI. If you have
defined security roles in WSRR and mapped to specific security server groups, you will be
required to login to the WSRR web UI as a member of the group specified for the activity.

However, if you have the WSRR roles mapped to ‘ALL AUTHENTICATED USERS’, then
you will not be required to login as different users, but may need to select the appropriate
perspective in the Web UI to perform the task.

Note: The purpose of the Web UI perspectives is to define a collection of views and tasks
that the specific role should be allowed to perform when logged into WSRR.
Governing the Service Provider in WSRR
The WESB dynamic service gateway will route the service request to the service
provider’s endpoint based on the results of the WSRR named query. As stated earlier, the
query expects to find specific objects the registry, moreover, these objects must be in the
correct governance state in order for the query to succeed.

The rest of this paper describes how to load the appropriate meta-data, and navigate the
governance process to achieve the desired state. In the end, the TemperatureConverter
service will be invoked, but only when we provide the adequate governed data in the
registry.

The high- level process is:

1. Load and activate the Governance Enablement Profile.

2. This is the out-of-the box governance process, and is completely documented in the
WSRR info Center and IBM redbook.
3. Govern an existing service
4. Govern a service consumer

Load and activate the Governance Enablement Profile (GEP)

Configuration profiles are loaded into WSRR from a configuration profile compressed file.
WSRR provides the following profiles:

Profile name File name

Basic profile DefaultProfile_v7.0.zip

GovernanceEnablementProfile_v7.0.zip
Governance
enablement profile

They are located in the <WAS_INSTALL_ROOT>\WSRR\config directory.

Note: When the governance enablement profile is loaded and WSRR security is enabled,
you must ensure that the user ID that is assigned to the Administrator RunAs role, for the
ServiceRegistry application in WebSphere® Application Server, is also assigned to the
WSRRAdmin role.
Load the Governance Enablement Profile

1. Use the web UI to perform the following actions:

◦ Switch to the Configuration perspective if necessary, by selecting Configuration in
the Perspective.
◦ Navigate to Manage Profiles > Configuration Profiles > Load Configuration Profile
◦ Specify the location of the configuration profile compressed file and click the OK
button.

Note: The status of the newly loaded profile will be set to "Archived".

Activate the Governance Enablement Profile

1.Use the web UI to perform the following actions:

◦ Switch to the Configuration perspective if necessary, by selecting Configuration in
the Perspective.
◦ Navigate to Manage Profiles > Configuration Profiles
◦ Select the configuration profile that you want to make active
◦ Click the ‘Make Active’ button.

Note: The status of the newly activated profile changes to "Active", and the status of
the previously active profile changes to "Archived".
Figure 38. Configuration perspective with GEP loaded and activated
Govern an existing service
In this section, we will use the governance enablement profile to govern an existing
service, and control its visibility and use across the organization.
This process includes the following activities:
• Register an existing service and endpoint in WSRR.
• Identify and define the business capability that the service provides.
• Provide scoping and planning information to support this version of the service.
• Provide a complete specification of this service version, including the service level
definition that can be consumed by other services.
• Complete the service life cycle, to ensure that the service endpoints are visible and
enabled in the various environments.

Register the WSDL for the Service (Temperature Converter)

The first step in registering a new service is to load the WSDL that defines the service,
and associate it with a service version that is used to govern that service.

To load a WSDL document by using the web UI, perform the following actions:
1. Switch to the Development perspective
2. Click Actions > Load Documents in the menu bar.
3. Identify the file to load by performing one of the two following options:
o Select Local file system and browse to find the WSDL file to load.
o Select Remote file location and enter the URI from where the WSDL file
can be downloaded.
4. Select WSDL for the Document type.
5. Optional: Enter a document description in the supplied field.
6. Enter 1.0 for the version.
7. Press the ‘OK’ button.
This will take to you the summary page of documents to be loaded.
8. On the ‘Documents to be loaded’ page, click on the ‘Finish’ button to load the
WSDL.

Note: If the WSDL has dependencies, the dependent file will also need to be loaded.
Our Temperature Converter WSDL contains no dependencies
Figure 39. Load Temperature Converter WSDL

The new WSDL document will be loaded into the registry. At this time, the WSDL is parsed
into many logical objects, including a SOAP service endpoint, which will be referenced
later in the governance process.
Figure 40. WSDL document successfully loaded
Identifying the business capability provided by a service
An important part of scoping a service is to identify how it adds value to the business.
WSRR uses business capabilities to define the business view of a service.
(1) Create a business service.
◦ Switch to the Business perspective, if necessary, by selecting Business from the
Perspective list.
◦ Click Actions > Create > Business Service.
◦ Enter ‘Temperature Converter’ in the Name field
◦ Enter a Description for the business service.
◦ Click Finish.

NOTE: The details page for the new business service is displayed, and the governance
state, visible under Governance State, is Business Capability Identified.

Figure 41. Create a new Business Service

(2) Define the scope of the Temperature Converter business service by loading a
charter.
◦ Click Edit Relationships.
◦ Click Add Other Document alongside the Charter relationship.
◦ Click Load Document.
◦ Click Browse and navigate to the directory to which contains a sample charter
document. This can be any document of any type.
◦ Select your document, click Open, and then click OK.
◦ Click Finish to load the charter document. The charter document is added as a
target of the Charter relationship.

Figure 42. Load the charter

Figure 43: Business service – adding charter document relationship
(3) Assign an owning organization to the business service
◦ Click Add Organization alongside the Owning Organization relationship.
◦ Under the ‘Add target’ section, click the ‘Create’ button to create a new sample
Organization object.
◦ Enter ‘SampleOrganization’ in the Name field.
◦ Click OK to save your changes
◦ The Temperature Converter business service should now have a related owning
organization
◦ Click Finish to save your changes.

Figure 44: Business service with charter and owning organization

(4) Approve Business Service
Move the Temperature Converter service through its life cycle to the Approved state, by
clicking the appropriate button, and observing the new state in the Governance State
section.
◦ Click Propose for Charter Review. The business service enters the Charter
Review state.
◦ Click Approve Capability. The business service enters Business Capability
Approved state

Figure 45: Approved Business Service

(5) Realize the Business Service
Identify that the Temperature Converter service is a version or realization of this capability,
by referencing the Temperature Converter service version from the Temperature Converter
Business service.

◦ Click the New Capability Version button located on the Business Service Details
Page. This action triggered a modifier to execute which created a new Service
Version, an generated a relationship between the business service and the new
service version.
◦ The Web UI remains at the business service details page. Under the
Relationships section, the Versions relationship contains the new version that
was automatically created.

Figure 46: Business service with relationship to the new service version
 ◦ Click the Temperature Converter link located under the Relationships section.
◦ Click the Edit Properties link on the service version details page.
◦ Set the Name, version, and description fields as shown in the figure below.
◦ Click the OK button to save the changes. The button is located at the bottom of the
page.

Figure 47: Service Version properties – Temperature converter (1.0)

(6) View the Temperature Converter business service
◦ From the Service version details page (Which is where you should be viewing
now), select ‘Temperature Converter’ from the bread crumb trail
◦ Under the Links section, Click Graphical View.
◦ Examine the structure of the Temperature Converter business service, and its
relationship to the Temperature Converter (1.0) service version, as it is now stored
in WSRR.

Figure 48: Graphical view of Temperature Converter Business Service

Providing scoping and planning information for the service

After defining and approving a business service, and relating it to a service version, we
must identify other planning and governance information for the service version.

(1) Define and agree the Temperature Converter service version scope.

This process ensures that the specific functional requirements and ownership for this
version of the service are documented. With proper WSRR security roles defined and
mapped, this section will require switching of UI roles and perspectives in order to perform
the tasks.

Note: The following steps assume that WSRR security roles are mapped to specific
groups. Therefore you must be logged into WSRR in an appropriate role to perform the
tasks. If security roles are mapped to ALL AUTHENTICATED, switching users is not
required, but you may still want to switch to the appropriate perspective identified.

◦ Switch to the Development perspective

◦ Navigate to View > Technical Governance > Capability Versions > Service
Versions.
◦ Click Temperature Converter (1.0) service to display the service version details
page.
◦ Click Propose Scope, and note that the new governance state is Scope Review.
◦ Switch to the SOA Governance perspective, and navigate back to the service
version detail page
◦ Click Approve Scope, and note that the new governance state is Scoped.

(2) Define and approve the Temperature Converter service version planning
information.

This process ensures that any dependencies are agreed, and availability and costing
information is provided.

◦ Switch to the Development perspective and navigate back to the service version
detail page
◦ Click Edit Properties.
◦ Change the Version Availability Date field to today's date, and the Version
Termination Date field to one year from now.
◦ Click OK to save your changes.
◦ Click Propose Plan, and note that the new governance state is Plan Review.
◦ Switch to the SOA Governance perspective and navigate back to the service
version detail page
◦ Click Approve Plan, and note that the new governance state is Planned.
Figure 49: Service version in Planned state

At this stage of the life cycle, the detailed consumption specification of the service starts.
Providing a specification and service level definition for the service

(1) Create the SLD for the Temperature Converter service version.
This encapsulates the endpoints, protocols and interfaces that consumers can use to
access the service.
◦ Switch to the Development perspective
◦ Navigate to View > Technical Governance > Capability Versions > Service
Versions.
◦ Click Temperature Converter (1.0) service to display the service version details.
◦ Click the New SLD button. A new SLD is created called SLD – Temperature
Converter (1.0)
◦ The SLD is displayed as a link under the Provides relationship.

Figure 50: Service Version with new SLD

(2) Define the service interface, and hence the functional specification used to
interact with the SLD.
◦ Click the SLD – Temperature Converter (1.0) link to display the SLD details.
◦ Click Edit Relationships.
◦ Click Add Service Interface alongside the Service Interface relationship.
◦ Enter Temp* in the Name field, and click Search.
◦ Select the radio button alongside TemperatureConverter interface, and click
Apply Selected Targets.
◦ Click Finish to save your changes.

Figure 51: SLD with the Service Interface relationship defined

(3) Scope the SLD
This provides the opportunity to define specific requirements or features that must be met.
Customized SLDs might have many properties that must be set at this point

◦ Switch to the Development perspective, if necessary.

◦ Click Propose Scope, and note the new governance state is SLD Scope Review
◦ Switch to the SOA Governance perspective
◦ Click Approve Scope, and note that the new governance state is SLD Scoped.

(4) Define the bound web service port, and hence the binding protocol used to
access the SLD.
We are still updating the SLD, so remain in the development perspective.
◦ Click Edit Relationships on the SLD.
◦ Click Add Service Port alongside the Bound Web Service Port relationship.
◦ Enter Temp* in the Name field, and click the Search button.
◦ Select the radio button alongside TemperatureConverter, and click Apply
Selected Targets.

Figure 52: SLD with Bound Web Service Port referenced

(5) Define the available endpoint that is currently deployed, and that can be reached
for this SLD.
◦ Click Add Service Endpoint alongside the Available Endpoints relationship.
◦ Enter * in the Name field, and click Search.
◦ Select the check box alongside
http://localhost:9080/TemperatureConverterRouterWeb/services/TemperatureConverter

and click Apply Selected Targets.

◦ Click Finish to save your changes.

Figure 53: SLD with related endpoint and bound web service port
(6) Complete the SLD specification.
Remain in the Development perspective
◦ Click Propose Specification, and note the new governance state is SLD Review.
◦ Switch to the SOA Governance perspective, and navigate back to the SLD.
◦ Click Approve Specification, and note the new governance state is SLD
Subscribable.

Note: The SLD is subscribable, meaning that service level agreements can now be
requested against it. Service Level Agreements are created by service consumers to show
their intent on consuming the service.

Figure 54: SLD in Subscribable state

(7) Apply The Web Service relationship to the Temperature Converter (1.0) service
version.
◦ Switch to the Development perspective
◦ Navigate to View > Technical Governance > Capability Versions > Service
Versions.
◦ Click Temperature Converter (1.0) service version to display the service version
details page
◦ Click the Edit Relationships link
◦ Click Add Service alongside the Provided Web Service relationship.
◦ Enter Temp* in the Name field, and click the Search button.
◦ Select the radio button alongside TemperatureConverter, and click Apply
Selected Targets.
◦ Click Finish to save the changes.

Figure 55: Service Version with the Provided Web Service referenced
(8) Complete the Temperature Converter (1.0) service version specification
◦ Click Propose Specification, and note the new governance state is
Specification Review.
◦ Switch to the SOA Governance perspective, and navigate back to the
Temperature Converter (1.0) service version
◦ Click Approve Specification, and note the new governance state is Specified.

Figure 56: Service version in Specified state

(9) Complete the Temperature Converter service realization.
Note: Because the service is already deployed, you would tie in any deployed or
installable assets during this next stage.
◦ Switch to the Development perspective and navigate back to the Temperature
Converter (1.0 Service version
◦ Click Propose Realization, and note the new governance state is Realization
Review.
◦ Switch to the SOA Governance perspective and navigate back to the Temperature
Converter (1.0 Service version
◦ Click Approve Realization, and note the new governance state is Realized.

Figure 57: Service version in Realized state

NOTE: At this point in the life cycle, we are ready to register the endpoints that are used in
any given environment, and to enable the endpoints as the service completes its life cycle.
Activating the Service Endpoint
After we have described the service in sufficient detail for it to be consumed and
programmed against, and have deployed an implementation of the service, we must
declare the endpoint in the registry so that it is promoted to, and therefore visible in, the
appropriate environments.
(1) Identify the endpoint for use in the staging environment
• Switch to the Operations perspective
• Navigate to View > Technical Governance > Capability Versions > Service Versions
• Click SLD – Temperature Converter (1.0) under the Provides relationship to display
the SLD details.
• Click http://localhost:9080/TemperatureConverterRouterWeb/services/TemperatureConverter
under the Available Endpoints relationship to display the endpoint details.

Figure 58: Temperature Converter endpoint details view

(2) Add the staging environment classification to the endpoint.
◦ Click Edit Classifications.
◦ Expand Governance Profile Taxonomy > Environment.
◦ Select the check box alongside Staging, and click Add. The Staging classification
is added to the Classification list.
◦ Click OK to assign the classification.

Figure 59: Adding the Staging environment classification to the endpoint

NOTE: At this stage, any other classifications that are needed by the endpoint can be
added. In the example named query we also added an extra environmental classification
indicating whether the endpoint is INTERNAL or EXTERNAL. This is entirely down to your
own enterprise and how endpoints are classified.
(3) Activate the endpoint
◦ Remain in the Operations perspective
◦ Click Approve for Use, and note that the endpoint governance state changes to
Online.

Figure 60: Endpoint is now activated in for the staging environment

(4) Promote the service to the staging environment
◦ Switch to the Development perspective
◦ Navigate to View > Technical Governance > Capability Versions > Service
Versions to display the service version details.
◦ Click Propose Staging Deployment, and note the new governance state is
Staging Review.

Note: The Operations team now has the opportunity to check that the information in the
governance registry is correct for deployment to the staging registry.

◦ Click Approve Staging Deployment, and note the new governance state is
Staged.

Figure 61: Service version is now staged

At this point, promotion, if configured, would respond to the Approve Staging
Deployment transition, and would promote the Temperature Converter (1.0) service, and
all of its dependencies, including the SLD, endpoint and WSDL, to the staging
environment. In the staging environment, testing of the Temperature Converter service is
carried out, to ensure that if it is made available in production it will meet all of its proposed
SLDs and SLAs.

Graphical view of the fully governed Business Service

Figure 62: Graph view of the Temperature Converter Business Service
Governing the Service Consumer in WSRR
As service consumers and service providers in WSRR are defined as a Business
Capability and Capability Version. Service providers can also be modeled in the registry as
service consumers. In this section, we need to model either a service, application, or
process as a consumer of the Temperature Converter service.

The primary difference in between an application and service as defined in WSRR, is that
an application does not have SLDs or endpoints. They are also not required to have
specifications. However, in the Governance Enablement profile, an application and service
share the same life cycle.

In this service consumer scenario, we will assume that we are developing and application
that will consume the temperature Converter service. As such, we will model an application
as the consumer. As mentioned above, the process of governing a service consumer is
very similar to governing a service provider. To avoid redundancy in this article, we will not
elaborate on the governance steps for the service consumers that are already described in
governing the service provider. We will note the steps that need to be performed, without
going into great detail.

Overview:
In this section, we will use the governance enablement profile to govern an application
(service consumer).
This process includes the following activities:
• Identify and define the business capability that the Business Application provides.
• Provide scoping and planning information to support this version of the
application.
• Define a DOU and SLA between the application (consumer) and the service
provider.
• Complete the application version life cycle, to ensure that the SLA is activated to
access the service provider endpoints in the various environments.
Identify and define the business capability that the
Business Application provides
(1) Create a Weather business application
◦ Switch to the Development perspective
◦ Navigate to Actions > Create > Business Application
◦ Specify a name and description for the weather application
◦ Click Finish to save the changes

Figure 63: Weather Business application

(2) Define the scope of the Weather business service by loading a charter.
◦ Assign an owning organization to the Weather business application.
◦ Move the Weather Application through its life cycle to the Approved state, by
clicking the appropriate button, and observing the new state in the Governance
State section.

Figure 64: Approved Weather Business Application

(3) Realize the Application Version
◦ Identify that the Weather Application version or realization of this capability, by
referencing the Weather Application version from the Weather Business
Application.

Figure 65: Weather Business application related to a new version (1.0) of the
application
Provide scoping and planning information to support this
version of the application
(1) Add a unique Consumer ID for the Application Version

The Application Version contains a property labeled Consumer Identifier. This property
should uniquely identify this specific application version in the registry. In this example, we
will use the combination of the Application version name and version number.

◦ Remain in the Development perspective

◦ Click the Edit Properties link on from the SLA details page.
◦ Enter WeatherApplication1.0 in the Consumer Identifier field.
◦ Click the OK button to save the changes

Figure 66: Application Version with its unique Consumer Identifier set
(2) Define and agree the Weather application version scope
◦ Propose Scope
◦ Approve Scope

(3) Define and approve the Weather application version planning information
◦ Propose Plan
◦ Approve Plan

Figure 67: Weather application version is in the Plan Approved state

Define a DOU and SLA between the application
(consumer) and the service provider
An important part of defining the specification for an application version is to identify all off
its dependent services. The Document of Understanding (DOU) and Service Level
Agreement (SLA) is used to define these runtime dependencies in the registry.
The new Weather application includes requirements to provide users the ability to convert
temperatures between Celsius and Fahrenheit. The development team has used the
registry and identified that an existing service (Temperature Converter) will provide the
required functionality. A subscription request (DOU) is created to formalize the reuse of the
Temperature Converter service.

(1) Create a DOU

◦ Switch to the Development perspective, if necessary, by selecting Development
from the Perspective list.
◦ Click Actions > Create > DOU.
◦ Enter ‘DOU - Temperature Converter’ in the Name field
◦ Enter a Description for the DOU.
◦ Click Add Organization alongside the Consumer relationship
◦ Under the Add target section, enter * (Asterisk) in the name field and select an
existing organization from the list.
◦ Click the Add button to add the organization to the DOU
◦ Click Add Capability Version alongside the Consumer relationship.
◦ Under the Add target section, enter Weather* in the name field and select
WeatherApplication (1.0) from the list.
◦ Click Add Capability Version alongside the Provider relationship.
◦ Under the Add target section, enter Temp* in the name field and select
Temperature Converter (1.0) from the list.
◦ Click the Finish button to save the changes
Figure 68: DOU with consumer and provider referenced

(2) Propose and Approve the DOU.

◦ Remain in the Development perspective
◦ If necessary, Navigate to View > Business Governance > DOUs to display the
DOUs
◦ Select DOU – Temperature Converter (1.0) from the list.
◦ Click the Propose button, and note the new governance state is Asset Scope
Review.
◦ Switch to the SOA Governance perspective
◦ Navigate to View > Business Governance > DOUs and select the DOU from the
list
◦ Click the Approve Proposal button, and note the new governance state is Asset
Scoped.
◦ Switch to the Development perspective
◦ Navigate to View > Business Governance > DOUs and select the DOU from the
list
◦ Click the Propose Asset Specification button, and note the new governance
state is Asset Specification Review.
◦ Switch to the SOA Governance perspective
◦ Navigate to View > Business Governance > DOUs and select the DOU from the
list
◦ Click the Approve Asset Specification button, and note the new governance
state is Asset Specified.
 ◦ Switch to the Development perspective
◦ Navigate to View > Business Governance > DOUs and select the DOU from the
list
◦ Click the Submit Asset for Approval button, and note the new governance state
is Asset Review.
• Switch to the SOA Governance perspective
• Navigate to View > Business Governance > DOUs and select the DOU from the list
• Click the Approve button, and note the new governance state is Asset Approved.

Figure 69: DOU approved

(3) Create a new SLA (Service Level Agreement) for the Weather application

Creating the service level agreement (SLA) is the responsibility of the development
organization of the service consumer.

◦ Switch to the Development perspective

◦ If necessary, Navigate to View > Business Governance > DOUs to display the
DOUs
◦ Select DOU – Temperature Converter (1.0) from the list.
◦ Click the New SLA button, and note a new SLA was created and referenced under
the Subscribed Service Level Agreements relationship.

Figure 70: DOU with a new SLA referenced

(4) Identify the target service version endpoint to be consumed by this SLA

The service version consumer (Weather Application) selects from the subscribable service
level definitions that the provider has made available.
The consumer then defines the specific quality of service and resource requirements for
the service subscription to use.
At this time, the provider can negotiate, and thus approve, reject, or refine the request.

◦ Switch to the Development perspective

◦ Navigate to View > Technical Governance à Capability Versions > Application
Versions and select the Weather Application version from the list.
◦ Select the SLA, SLA - DOU - Temperature Converter (1.0) from the Consumes
relationship on the application Version.
◦ Click the Edit Relationships link on from the SLA details page.
◦ Click Add Extended Service Level Agreement alongside the Agreed Endpoints
relationship.
◦ Enter SLD* in the Name field, and click the Search button.
◦ Select the radio button alongside SLD – TemperatureConverter (1.0), and click
Apply Selected Targets.
◦ Click the Finish button to save the changes

Figure 71: SLA with the reference to the Temperature Converter SLD (Agreed
Endpoint)
(5) Add a unique Context ID for the SLA

The SLA contains a property labeled Context ID. This property should uniquely identify the
specific service version that the application intends to consume. In this example, we will
set the value of the context ID to the target Namespace of the service version that is
consumed by this SLA.

◦ Remain in the Development perspective

◦ Click the Edit Properties link on from the SLA details page.
◦ Enter http://ad.ibm.com/2006/09/WSRR/enablement in the Context Identifier
field.
◦ Click the OK button to save the changes

Figure 72: SLA with the Context Identifier set

1.
(6) Request SLA Approval
◦ Remain in the Development perspective and ensure you are at the SLA details
page as shown in the figure above
◦ Click the Request SLA button from the SLA details page, and note the new
governance state is SLA Requested.
◦ Switch to the SOA Governance perspective
◦ Navigate to View > SOA Governance > Service Level Agreements and select the
SLA from the list
◦ Click the Approve SLA Request button, and note the new governance state is
SLA Inactive.

(7) Activate the Approved SLA

◦ Switch to the Operations perspective
◦ Navigate to Tasks > Service Level Agreement tasks > SLAs for Activation and
select the SLA from the list
◦ Click the Activate SLA button, and note the new governance state is SLA Active.

Figure 73: Activated SLA

Graphical View of the Service Consumer
The graph below shows the Application Version with its SLA referencing the Temperature
Converter (1.0) agreed endpoint (SLD).

Figure 74: Graph view of the application consumer and SLA

Summary
We now have a Service Consumer (Weather Application) which has an SLA with the SLD
of a Service Provider (Temperature Converter). Moreover, the SLA is in an ACTIVE state
and the SLD exposes an endpoint which is ON-LINE. This means that when the WESB
Service Gateway Mediation containing our Custom Mediation Primitive calls the named
query on WSRR it will find this exposed endpoint and will be able to route the request
appropriately.

The scenario demonstrates how WESB can make use of the Governance Enablement
Profile objects so that routing decisions are made on the governance states of the meta-
data objects that reflect the business.