Using WebSphere Service Registry and Repository primitives in WebSphere Enterprise Service Bus mediation flows

As IBM has enhanced WebSphere ESB, it has provided new mediation primitives to enable you to perform interactions with WebSphere Service Registry and Repository. You can use these primitives to perform dynamic endpoint selection, along with governing and enforcing service level agreements (SLAs) between service providers and consumers. Examples in this article show you how to develop WebSphere ESB mediation flows that interact with WebSphere Service Registry and Repository.

Share:

Brian Venn (vennb@uk.ibm.com), Software Engineer, IBM

Photo of Brian VennBrian Venn is the System Verification Test Team Lead for WebSphere Process Server, WebSphere ESB, and IBM BPM on z/OS. He has 15 years of experience in the software industry and has worked at IBM Hursley Lab in the United Kingdom since 2000. He is an IBM Certified Solution Designer for SOA Solutions and an IBM Certified Deployment Professional, and he has participated in the authoring of four WebSphere Process Server and WebSphere ESB certification exams. Brian earned a Bachelors degree in Astrophysics from Southampton University in the United Kingdom.


developerWorks Contributing author
        level

14 December 2011

Also available in Chinese

Introduction

IBM® WebSphere® Enterprise Service Bus V7 (hereafter called WebSphere ESB) and its associated tooling, IBM Integration Designer, enable you to improve connectivity between systems. IBM Integration Designer enables you to develop mediation flows to process incoming messages, perform operations such as modifying and logging data, and route them to destination services. While you can set the address of these destination services directly within the mediation flow, doing so can cause problems if the address of the service changes.

A better approach is to have the mediation flow resolve the destination address of the service dynamically at runtime, using WebSphere Service Registry and Repository (hereafter called Service Registry). WebSphere ESB can query Service Registry at runtime and obtain the address of the endpoint service, and can tailor the search based on further information, such as Service Level Agreements (SLAs).

To fully benefit from this article, you should have some experience with WebSphere ESB, Integration Designer, and the Service Registry administrative console. Product versions used in this article: WebSphere ESB V7.5, Integration Designer V7.5, and Service Registry V7.5.

Overview of primitives

SLA Check mediation primitive

SLA Check mediation primitive

The SLA Check mediation primitive is used to perform SLA checks. Messages flowing through a mediation can be routed to target services, but you may need to check whether an SLA exists for the destination service, which the SLA Check primitive can do by communicating with Service Registry.

The SLA Check mediation primitive has three terminals. Match is fired when Service Registry confirms that an SLA is in place, noMatch is fired when no SLA is in place, and fail is fired when there is an error, such as failure to connect to the Service Registry server. The match performed in Service Registry is based on three parameters:

Endpoint
Defines the target endpoint that the mediation flow wants to invoke (mandatory field).
Consumer Identifier
Defines the consumer of the target endpoint (optional).
Context Identifier
Defines the context of the invocation of the target endpoint (optional).

SLA Endpoint Lookup primitive

SLA Endpoint Lookup primitive

The SLA Endpoint Lookup primitive has more functionality than the SLA Check primitive. In addition to determining whether the consumer has a valid SLA for the endpoint, you can use it to determine additional information, such as:

  • If the SLA is active
  • If the endpoint is online
  • If the endpoint has a classification associated with it, such as Development or Production

The SLA Endpoint Lookup has the same match, reject, and fail terminals as described above for the SLA Check mediation primitive.

Gateway Endpoint Lookup mediation primitive

Gateway Endpoint Lookup mediation primitive

The Gateway Endpoint Lookup mediation primitive is used to route service requests in a service gateway. It has the same match, reject, and fail terminals as described for the SLA Check and SLA Gateway Endpoint Lookup primitives.

The Gateway Endpoint Lookup mediation primitive uses three different modes: URL, XPath, and Action. The Action mode is used to resolve SOAP Actions or WS-Addressing actions within Service Registry. This article only describes the Action mode. For descriptions of the URL and XPath modes, see Gateway Endpoint Lookup mediation primitive properties in the WebSphere ESB V7.5 information center.

Creating a service

In order for the mediation primitives described in this article to be used effectively, you must first populate Service Registry with information that the mediation flow will use in order to perform dynamic routing. The starting point for this article assumes that the following products are available:

  • IBM Integration Designer V7.5.
  • A WebSphere ESB V7.5 test server configured for use with IBM integration Designer and with a connection to the WebSphere Service Registry and Repository.
  • WebSphere Service Registry and Repository V7.5.

To start, you need to develop a back-end service that can be deployed to the test server. The details that this service will provide are then configured in Service Registry so that other services can locate and use it. If you prefer, you can download a working version of this application at the bottom of the article, and then skip to the section Publish the WSDL to Service Registry.

Create the project

  1. Select File => New Integration Solution.
  2. Enter the solutions name WESB75Primatives.
  3. Tick the box to Create a library and then click Finish.
  4. Select File => New Mediation Module.
  5. Name the module GoldEndpointService and then click Next.
  6. Tick the box to Include the module in the library.
  7. Click Next, and then click Finish.

Create the business object

  1. In the Project Explorer, expand the Library and right-click on Data.
  2. Select New => Business Object. Name the business object customerBO and then click Finish.
  3. The Business Object Editor should now be open in IBM Integration Designer.
  4. Click Add Field and add four string fields with the following names: firstName, LastName, postCode, servicelevel.
  5. Click Save and close the Business Object Editor.

Create the interfaces

  1. In the Project Explorer, on the Library, right-click on Interfaces and select New => Interface.
  2. Name the interface customerDataInterface and then click Finish. The Interface Editor will open. Click the Add request response operation button.
  3. Name the operation operationPopulateCustomerData.
  4. Change the input and output names to inputCustomer and outputCustomer respectively, and then change their types to customerBO.
  5. In the Interface Editor, click Save and Close.
  6. Return to the assembly diagram for the GoldEndpoint Service. Click on the mediation and select Add Interface.
  7. Select the customerDataInterface, click OK, and then click Save.

Create the mediation flow

  1. Double-click on the Mediation flow and click Yes at the prompt. When prompted for a folder, click OK.
  2. The Overview will open. Click on the operation PopulateCustomerData and select Blank mediation flow.
  3. The Mediation Flow Editor will now open. Drop a Message Element Setter primitive onto the editor. Select the primitive and click the Properties tab. Click the Details tab and then click Add.
  4. Ensure that the action is Set. Click the Browser button for Target. Use the XPath Expression Builder to browse down to /body/operationPopulateCustomerData/inputCustomer/firstName and then click OK.
  5. For a value, enter a firstName of your choosing.
  6. Repeat for the remaining values of the customerBO. Set the serviceLevel value to gold.
  7. Drag the output terminal of the Message Element Setter primitive to the Input Response.
  8. At the prompt, select Transform using an XSLT primitive. Double-click on the XSLT primitive. At the New XML Map prompt, click Finish.
  9. The XSLT Editor will now be open. Wire the inputCustomer to the outputCustomer. It should be a simple move operation. Click Save all.
  10. Deploy and test this application, which should produce a business object with the data entered in Steps 6 and 7.

Make the service available via a Web service interface

  1. Return to the assembly diagram. From the palette, expand Inbound exports. Drag a Web service onto the assembly diagram.
  2. When prompted for an interface, select customerDataInterface, and then click Next.
  3. Ensure that the binding is set to SOAP1.1/HTTP. Click Next, and then click Finish.
  4. Refactor the WSExport1 name to WSExportForGoldService.
  5. Wire the Web service to the Mediation Flow interface, and then click Save all.

Publish the WSDL to Service Registry

The WSDL file for this service is now ready to be published:

  1. In the Project Explorer, expand the Library, then expand the Web Service Ports.
  2. Double-click on WSExportForGoldService_customerDataInterfaceHttpPort. A graphic representation of the WSDL will be displayed.
  3. The default value for the endpoint will contain localhost:9080. Update this to the values for the server where the GoldServiceApp will be published.
  4. After saving, right-click on WSExportForGoldService_customerDataInterfaceHttpPort in the Project Explorer and select Export.
  5. In the Export dialog box, Expand Business Integration and select WSDL and XSD.
  6. Ensure that both the Merge dependant XSD resources and Merge dependent WSDL resources into the parent WSDL file boxes are checked.
  7. Select a target directory and then click Finish.

The WSDL for the back-end service is now ready to be installed into Service Registry:

  1. Log in to the Service Registry admin console.
  2. Go to View => Service Documents => WSDL Documents.
  3. Click Load Documents. The Load Documents page is displayed.
  4. Click Browse to find the WSDL file that you want to load.
  5. Enter the document description and a Version of 1.0.
  6. Click OK. A tree showing the WSDL and prerequisite files is displayed.
  7. Click Finish.

Configuring the service in Service Registry

Create a service version

  1. In the Service Registry admin console, switch to the SOA Governance perspective.
  2. Go to View => Technical Governance => Capability Versions => Service Versions.
  3. Click New.
  4. Specify a name for the service version: DVWorksGoldServiceVersion.
  5. Specify a Consumer Identifier: DVWorksGoldConsumerCI.
  6. Click Finish. The Service Registry admin console should look like Figure 1 below. The Consumes and Provides fields listed in the relationships view should display the SLAs and service level definitions (SLDs) created above.
    Figure 1. Service Registry admin console showing a correctly configured service version
    Service Registry admin console showing a correctly configured service version

Next, an SLD is required.

Create an SLD

  1. Select View => SOA Governance => Service Level Definitions.
  2. Click New SLD.
  3. Specify a name for the SLD: DVWorksGoldServiceLevelDefinition.
  4. Click Add Service Endpoint.
  5. In the Search for Existing Entity Name field, enter * and click Search to see a list of service endpoints. Leave Entity Type as the default, which is Service Endpoint.
  6. Locate the entry that ends with GoldEndpointServiceWeb/sca/WSExportForGoldService. Select the checkbox next to it and click Apply Selected Targets.
  7. Click Add Service Interface.
  8. In the Search for Existing Entity Name field, enter * and click Search to see a list of service interfaces. Leave Entity Type as the default, which is Service Interface.
  9. Locate the service customerDataInterface, select it, and click Apply Selected Targets.
  10. Click Add Service Port.
  11. In the Search for Existing Entity Name field, enter * and click Search to see a list of service ports. Leave Entity Type as the default, which is Service Port.
  12. Select the target for WSExportForGoldService_customerDataInterfaceHttpPort. Select it and click Apply Selected Targets.
  13. Click Finish. A confirmation message will say that the object was successfully created.
  14. Use the following steps to make the SLD active.
  15. Click Propose Scope. The Governance State is now Scope Review.
  16. Click Approve Scope. The Governance State becomes Scoped.
  17. Click Propose Specification. The Governance State is now Review.
  18. Click Approve Specification. The Governance State becomes Subscribable and the SLD is now ready to use.

Create a Service Level Agreement

  1. Go to View => SOA Governance => Service Level Agreements.
  2. Click New SLA.
  3. Give a name to the SLA: DVWorksGoldServiceSLA.
  4. Specify a Context Identifier of DVWorksGoldContextId.
  5. Click Add Service Level Definition.
  6. Select DVWorksGoldServiceDefinition, click Apply Selected Targets, and then click Finish.
  7. The SLA must move through a number of states to become active.
  8. Click Request SLA. The Governance State of the SLA is now Requested.
  9. Click Approve SLA Request. The Governance State of the SLA becomes Inactive.
  10. Click Activate SLA. The Governance State of the SLA is now Active and it is ready to use.

Associate the SLD and SLA with the service version

  1. Go to Service Versions.
  2. Select the service version created in the section Create a service version.
  3. Click the Edit Relationships link.
  4. Click Add Service Level Definition.
  5. In the Search for Existing Entity Name field, enter * and click Search.
  6. Select DVWorksGoldServiceLevelDefinitionand click Apply Selected Targets. The SLD name is displayed in the Provides field.
  7. Select Add Service Level Agreement. In the Search for Existing Entity Name field, enter * and click Search.
  8. Select DVWorksGoldServiceSLAand click Apply Selected Targets. The SLA name is displayed in the Consumes field.
  9. Click Finish.

Make the service endpoint available for use

  1. Go to View => SOA Governance => SOAP Service Endpoints.
  2. Select the endpoint to activate (it will end with GoldEndpointServiceWeb/sca/WSExportForGoldService).
  3. Select Edit Classifications.
  4. In the Classifications menu, expand Governance Profile Taxonomy. A list of options is displayed.
  5. Expand Environment.
  6. Select the tick box next to an environment. Select Production and click Add.
  7. Click OK.
  8. The classification of the endpoint is currently Offline. Select Approve For Use.
  9. The classification becomes Online and the endpoint is now ready for use.

The Service Registry configuration service is now complete. The next step is to build the mediation flows to interact with Service Registry.

Implementing a flow with an SLA mediation primitive

Create the interfaces

  1. Return to IBM Integration Designer. In the Project Explorer, right-click and select New => Project-Mediation Module.
  2. Enter a module name of SLACheck and click Next.
  3. Ensure that the checkbox for the Library is ticked, and then click Next.
  4. Tick the box next to Include the project in the main integration solution and then click Finish.
  5. In the assembly diagram, right-click on the mediation module and then click Add Interface.
  6. Select the Customer Data Interface and then click OK.
  7. Right-click on the mediation module and then click Add Interface.
  8. Select the Customer Data Interface and then click OK.
  9. In the palette, expand Outbound imports and drop a Web service onto the assembly diagram.
  10. At the Select and Interface dialog, click Browse. Select the customerDataInterface, click OK, and then click Next.
  11. Ensure that Use an existing Web Service port is selected and then click Browse.
  12. Select the WSExportForGoldService port, click OK, and then click Next.
  13. Ensure that SOAP1.1/HTTP is selected and then click Finish.
  14. Back in the assembly diagram, wire the mediation flow to the service export.

Create the SLA mediation flow

  1. Double-click on the mediation flow. At the prompt, click Yes, and then click OK.
  2. In the Overview window, click on operationPopulateCustomerData. For the mediation flow template, click Service Integration.
  3. In the Integrate Services dialog, click Add. Select customerDataInterfacePartner and then click OK twice.
  4. The Mediation Flow Editor should now be open. Construct a mediation flow as shown below in Figure 2. You may want to add additional logging, tracing, and error handling as desired.
    Figure 2. SLA Check mediation flow
    SLA Check mediation flow
  5. In the Mediation Flow Editor, select the SLA Check mediation primitive. Select the Properties tab and then select Details.
  6. For the endpoint, enter the Web address for the service endpoint., which you can obtain from WSRR View => SOA Governance => Service Endpoints => SOAP Service endpoints. Do not include any extra spaces in the endpoint address.
  7. Enter a contextId and consumerIdentifer if one was entered in Step 6 of Creating a service version and Step 3 of Creating a service level agreement. Set the registry name (if required).
  8. In the response flow, wire the callout response directly to the input response. Add additional logging, tracing, and error handling as desired.
  9. Click Save all. The application is ready now to be deployed and tested.
  10. Deploy the application to the test server and use the Integration Test client to invoke the mediation flow. It should pass the SLA check and the back-end service should be invokes. Figure 3 shows the test client output from a successful run:
    Figure 3. Successful test run of the SLA Check mediation flow via the Integration Test Client
    Successful test run of the SLA Check mediation flow via the Integration Test Client

To experiment, and change the back-end endpoint to a slightly different address (for example, add ABC onto the end of the endpoint), redeploy the application, and rerun the test client. This time the SLA check will fail, Service Registry will report that there is no SLA in place for that endpoint, and the noMatch terminal of the SLA primitive will be fired.

Using the SLA Endpoint Lookup primitive

You can now modify the flow in order to use an SLA Endpoint Lookup primitive:

  1. Return to the Mediation Flow Editor. Select the SLA Check primitive and delete it.
  2. From the Palette, select an SLA Endpoint Lookup mediation primitive and drop it onto the Flow Editor.
  3. Wire up the SLA Endpoint Lookup primitive, as shown in Figure 4 below.
  4. Select the SLA Endpoint Lookup primitive and click the Properties tab..
  5. Enter the contextId and consumerId as entered in Step 6 of Creating a service version and Step 3 of Creating a service level agreement. Normally, these values are obtained from the incoming business object, but for the purposes of this article you can enter them by hand.
  6. Set the Endpoint Classification, which you can obtain in Service Registry in View => SOA Governance => Service Endpoints => SOAP Service Endpoints. Click the service name. Click Edit Classifications, and then click Classification (Production) in the classifications list. The required URI will appear in the Details section. Copy and paste this value into the Endpoint classification field, ensuring that there are no blank spaces at the end.
  7. The completed Details section should look like Figure 4 below. Click Save All:
    Figure 4. Configured SLA Endpoint lookup primitive in IBM Integration Designer
    Configured SLA Endpoint lookup primitive in IBM Integration Designer

The updated application is now ready to be deployed and tested. Deploy the application to the test server and use the Integration Test client to invoke the mediation flow. It should pass the SLA check and the back-end service should be invoked. The test client output should look like Figure 3 above. Modify the contextId, consumerId, or endpoint classification and rerun the tests. The SLA Endpoint Lookup should fail and the No Match terminal should be fired.

Implementing a flow with a Gateway Endpoint Lookup mediation primitive

Rather than go through the creation of a new back-end service, a pre-built one is used this time. The flow of the service is similar to the one developed earlier for the SLA Checks.

  1. Download the MediationFlow_SilverService.zip Project Interchange (PI) file at the bottom of the article. Import the PI file into IBM Integration Designer.
  2. In the Project Explorer, expand the Web Service Ports. Right-click on WSExportForSilverService_silverCustomerInterface and select Open With => Text Editor.
  3. The WSDL file will now be open for editing. Locate the line <soap:operation soapAction=""/> and update it to <soap:operation soapAction="DVWorksSOAPAction"/>.
  4. Update the soap:address line:
    <soap:address location=
    "http://localhost:9080/SilverEndpointServiceWeb/sca/WSExportForSilverService"/>

    to the hostname and port number of the server that this service will be deployed to.
  5. Save and close the WSDL.

Publish the WSDL to Service Registry

  1. Log on to the Service Registry admin console.
  2. Select Actions => Load Documents.
  3. Import the WSDL generated in the previous steps. Add in a description and version if desired, and then click OK.
  4. Click Finish.

A mediation flow that will use the Gateway Endpoint Lookup primitive can now be developed to make use of this WSDL and the corresponding SOAP action.

Create the interfaces

  1. In IBM Integration Designer, right-click on Project Explorer and select New => Mediation Module.
  2. Name the module GatewayEndpointLookupExample and then click Next. Tick the checkbox to include the Library.
  3. Tick the checkbox to Include the module as part of the Integration Solution. Click Finish.
  4. Click on the mediation flow in the assembly diagram and add an interface. Select silverCustomerInterface and click OK.
  5. Expand the Outbound Imports and drag a Web service onto the assembly diagram.
  6. When prompted to select an interface, click Browse and select silverCustomerInterface. Click OK and then click Next.
  7. Select Use an existing Web service port and then click Browse.
  8. Select WSExportForGoldService_customerDataInterfaceHttpPort. Click OK and then click Next.
  9. Leave the Transport Protocol as SOAP1.1/HTTP and then click Finish.
  10. Refactor the WSImport1, and rename it to WSImportToSilverService.
  11. Wire the end of the mediation flow to the Web service, and at the prompt, click OK.
  12. Click Save All.

Create the gateway flow

  1. Double-click on the mediation flow. At the prompts, click Yes, then OK.
  2. In the overview, click on operationSilverCustomerData, then select Service Integration as the mediation flow template.
  3. At the Integrate services dialog box, click Add. There will be only one reference operation -- customerDataInterfacePartner. Click OK twice.
  4. The Mediation Flow Editor will now be open. From the palette, drop a Message Element Setter primitive, and wire it to the Input interface.
  5. Select the Message Element Setter primitive. In the Properties tab, click Add. Ensure that the Action is Set, and then click the Browse button next to Target.
  6. Use the XPath Expression Builder to select the value of ServiceMessageObject => Headers => SMO Header => Action, and then click OK.
  7. In the Value Text area, enter DVWorksSOAPAction. The dialog box should look like Figure 5. Click Finish:
    Figure 5. Message element setter dialog box showing correct details for Gateway Endpoint Lookup
    Message element setter dialog box showing correct details for Gateway Endpoint Lookup
  1. Drop a Gateway Endpoint Lookup primitive onto the Mediation Flow Editor. Wire the output terminal of the MessageElementSetter to the input terminal.
  2. Select the Gateway Endpoint Lookup primitive, click the Properties tab, and then click the Details tab. Change the lookup method to Action.
  3. Wire up a stop terminal to the Gateway primitive NoMatch terminal, and a fail primitive to the fail terminal.
  4. Wire the out terminal to the callout to the silverCustomerInterface partner. The completed flow should look like Figure 6 below.
  5. In the response flow, wire the callout response directly to the input response:
    Figure 6. Completed mediation flow using Gateway Endpoint Lookup primitive
    Completed mediation flow using Gateway Endpoint Lookup primitive

The application is now ready to be deployed and tested. Deploy the application to the test server and use the Integration Test client to invoke the mediation flow, which passes the GatewayEndpointLookup check, causing the back-end silver service to be invoked. Try modifying the SOAPAction contained in the MessageElementSetter primitive to a different value. The NoMatch terminal will be fired this time.

Conclusion

This article showed you how to configure Service Registry with content that can be used by WebSphere ESB mediation flows.


Download

DescriptionNameSize
Code sampleMediationFlowSamples.zip156 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=781443
ArticleTitle=Using WebSphere Service Registry and Repository primitives in WebSphere Enterprise Service Bus mediation flows
publish-date=12142011