IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 3

Adding Web services and promoting properties

After discussing key WebSphere ESB features and describing message exchanges across JMS in the previous articles of our series, we will now further expand the set of technologies we are leveraging in IBM® WebSphere® ESB by adding a Web services scenario to the mix. Moreover, we will show two new features that were introduced with the release of Version 6.0.2 of both WebSphere ESB and WebSphere Integration Developer.

Rachel Reinitz (, Senior Consulting IT Specialist, IBM

Rachel ReinitzRachel Reinitz is an IBM Distinguished Engineer with IBM Software Services for WebSphere and a member of the IBM Academy of Technology. She has built much of IBM’s internal and external intellectual capital and education on SOA, Enterprise Service Bus, and Web services. Rachel focuses on how to get started with SOA and ESB best practices. She consults with clients and ISVs on how SOA and ESB can be used to achieve their business and technical objectives. She is a frequent conference presenter and written many developerWorks articles on ESB and Web services. Rachel lives in the Bay Area in California, and enjoys hiking, socializing, and international travel.

Andre Tost, Senior Technical Staff Member, IBM

Andre TostAndre Tost works as a Senior Technical Staff Member in the Software Group's Enterprise Integration Solutions organization, where he helps IBM's customers establishing Service-Oriented Architectures. His special focus is on Web services technology. Before his current assignment, he spent ten years in various partner enablement, development and architecture roles in IBM software development, most recently for the WebSphere Business Development group. Originally from Germany, he now lives and works in Rochester, Minnesota. In his spare time, he likes to spend time with his family and play and watch soccer whenever possible.

24 January 2006

Also available in Chinese Russian

From the IBM WebSphere Developer Technical Journal.


Our scenario included a one-way message being sent to a back-end application via JMS, indicating that a package had been delivered to the customer. We mapped this into a "one-way" operation of a service (meaning the operation has a request, but no response), and we gave it JMS bindings. Next, we will cover a synchronous interaction between service requester and provider through a "request-response" operation (meaning that there is a response for every request). Our service will use SOAP/HTTP bindings as its protocol. As in the previous case, we will route each message through the Enterprise Service Bus, implemented by WebSphere ESB V6.0.2 to decouple the service requester and provider. The service requester and provider are not aware the messages are flowing through the ESB and know nothing about the routing or logging in the ESB.

You will also see how to configure the runtime to route messages to a different endpoint address, and how to change which details of the message are logged, both without redeploying the mediation. This configuration can be made directly in the admin console of WebSphere ESB. This functionality is new in the 6.0.2 release of the product, which was released since Part 2 was published. We will use this new version of the product for the remainder of this series beginning with this installment.

The scenario evolves

The business background for our scenario is the need for Posts-R-Us to enable customers and employees to retrieve the status of a package delivery. To make this function as accessible as possible, with a variety of client platforms, it was decided to offer a Web service that takes the tracking number of a package as its input parameter and returns an XML document containing the status of the package, including the estimated (or actual) delivery date.

Each request to this new service is routed through the ESB, represented by a WebSphere ESB mediation module. The mediation module logs each request and each response message, and routes the requests to one of two implementations of the actual service logic. To increase the flexibility of the overall system, two implementations of the service exist, with one serving as the backup. Note that in our example, we are not talking about a clustered environment with an application server instance serving as the automatic backup system in case of a failure, but rather a second instance of the service, at a different endpoint address. We will show you how to reconfigure the mediation module's import bindings to switch to the backup service at runtime, using the WebSphere ESB administrative console.

As usual, the mediation flow component communicates with its clients and the actual service provider via an export and import, respectively. Figure 1 shows what the architecture of the system looks like.

Figure 1. Architecture for the sample scenario
Figure 1. Architecture for the sample scenario

The service provider

Here and in later sections, we won't describe step-by-step instructions, but rather invite you to import the predefined EAR files included in the download section. We will highlight the important parts of each application as we build the entire sample scenario.

For our example, we need to implement a service provider that takes a trackingNumber variable as input and returns a packageStatus structure with information about the package.

  1. For one of the later tests we will take you through in this article, you must ensure the test server is configured appropriately. Double-click on the WebSphere ESB Server v6.0 in the Servers view and make sure Run server with resources on Server is selected (Figure 2). This must be done before you start the server and before you deploy any of the EAR application archives from this article to it.

    Figure 2. Test server configuration
    Figure 2. Test server configuration
  2. You can find the sample service provider in the PackageSatusServiceEAR.ear file, included with in the download materials with this article. Import this file into WebSphere Integration Developer V6.0.2 and select WebSphere ESB Server v6.0 for the Target server. You are just using the same WebSphere Application Server instance that WebSphere ESB is installed in to run the services; in an actual environment the services would most likely be running on a separate server.

  3. In the J2EE perspective, you will see a new Web project called PackageStatusService. Note that it contains a WSDL file called PackageTrackingService.wsdl with the service definition in it. If you open this WSDL file in the Interface Editor of the tool, you can see that it has a request-response operation defined, named getPackageStatus, as shown in Figure 3.

    Figure 3. PackageTrackingService interface
    Figure 3. PackageTrackingService interface
  4. Next, move on to the actual implementation class, called in the postsrus.service package. If you open this class in the Java editor of the tool, you can see that two tracking numbers are handled in our example, namely "123" and "456". All other numbers lead to an exception. We will use this knowledge later when testing the scenario.

  5. The other interesting class, located in the same package, is,,containing the data structure that is returned as a result of a service operation invocation, which consists of four properties:

    package postrus.service;
    public class PackageStatus  {
        private java.util.Calendar actualDeliveryDate;
        private java.lang.String location;
        private java.util.Calendar projectedDeliveryDate;
        private java.lang.String status;
        public PackageStatus() {

    Note how the time and date of delivery is represented by properties of type java.util.Calendar. You will see later how that maps to an element of type <xsd:dateTime> in our XML schema.

  6. You can now briefly test this service to make sure it is deployed properly and operational. For that, start the WebSphere ESB 6.0.2 test server in the tool, then use the Add and remove projects... menu option to deploy the PackageStatusServiceEAR application to the server.

  7. Once the application has been deployed and started, you will want to use the WebSphere Integration Developer Web services testing tool. Enable the Web services capability in WebSphere Integration Developer by expanding Workbench => Capabilities under Preferences, and checking Web Service Developer. Now, right-click on PackageStatusService.wsdl and then select Web Services => Test with Web Service Explorer, as shown in Figure 4.

    Figure 4. Selecting the Web Services Explorer option
    Figure 4. Selecting the Web Services Explorer option

    This will open the Web Service Explorer view, which enables you to test the Web service, without actually generating a test client application.

  8. Click on the getPackageStatus operation link, enter 123 as the tracking number, and then click Go. Port assignments on test servers vary, so if you get a connection error, select PackageTrackingServiceSoapBinding in the Web Services Explorer and you can add another endpoint. Try setting the port to be 9081 or look at your test server settings to determine the correct port. You should see a printout in the server console indicating that the service was called, and a PackageStatus object is returned (Figure 5).

    Figure 5. Web Services Explorer
    Figure 5. Web Services Explorer
  9. Next, go ahead and import the PackageStatusServiceBackupEAR.ear file into WebSphere Integration Developer and select WebSphere ESB as the target server . Change the endpoint port if needed. This project contains an identical set of Java classes and other artifacts, and also has a Web service defined in it that has a getPackageStatus operation. In other words, it is an exact copy of the service we just looked at; the only difference is that it is deployed under a different endpoint address and has a different System.out statement specifying the "backup service" has been called.

  10. You can now add this project to the WebSphere ESB server and test it with the Web Services Explorer. Make sure that this time, you right-click the WSDL file in the PackageStatusBackupService project. After running the test, you should see this line in the server console, indicating that indeed the backup service was called:

    [1/22/07 10:52:59:422 CST] 00000048 SystemOut     O Package status 
    request in backup service for tracking number 456

The mediation module

Next, let's look at the mediation module that will go between the service provider we just installed and any client that uses this service.

  1. We stored the module as a Project Interchange file, called After you have imported the file, switch to the Business Integration perspective in WebSphere Integration Developer. In the PackageStatusModule module, you should see the PackageStatusService file under Interfaces. This is the same WSDL file we already used in the service provider. In other words, the mediation module will expose the same interface as the original service, so no transformation is required in the ESB. Under Data Types, notice the PackageStatus definition with the fields that are returned from the service.

  2. Now, open the assembly diagram for the module in the Assembly editor. There is nothing too exciting about this assembly; it shows the mediation flow component, an export and an import (Figure 6).

    Figure 6. Assembly diagram
    Figure 6. Assembly diagram
  3. Select the PackageStatusServiceImport and look at the associated properties view. In the Binding tab, you can see that it points to the endpoint address of the service implementation that you deployed earlier. Note that the port number is set to 9082. If your test server uses port number 9081, you can update it right here in the properties view. Similarly, if you select the PackageStatusExport, you will notice that is has a Web service binding on it, with a new endpoint address. This address is what you will use in the Web Services Explorer later when testing the complete solution.

  4. Double-click the PackageStatusMediation to open the Mediation Flow editor. Since you have built a mediation flow component before, there are no big surprises here: each request and response message is routed through a MessageLogger mediation primitive, so that it is logged in the default database.

    Figure 7. Mediation flow component
    Figure 7. Mediation flow component

    You may remember that in the properties for the MessageLogger primitive, you can define an XPath statement that indicates which part of the message is actually getting logged. You can change this in the Details tab of the Properties view. The default value of the Root property is "/body", meaning that the entire body of the message is logged. For our example, we have changed this property to "/body/getTrackingStatus/trackingNumber", meaning that only the actual number is logged.

Promoted properties

Here we will start using a feature that is new in Version 6.0.2 of WebSphere ESB, called promoted properties. In earlier releases, the only way to change a property like the Root property of the MessageLogger primitive was to load the module into WebSphere Integration Developer, change the property, and redeploy the entire module to the server. With Version 6.0.2, properties that have been "promoted" can also be changed via the admin console at runtime. There is a new Promoted Properties tab in the Properties view that lets you select which properties, specific to the mediation primitive, you want to make changeable. Each mediation primitive has a specific set of properties which can be promoted.

In our scenario, you want to promote the property that lets you define which part of a message is logged. This way, you can adjust at run time how much of a message is logged, without ever having to redeploy the module. Assume, for example, that you have a service with a rather large message payload. You might decide only to log a small part of that message to save storage. Later on, you may want to run an extended analysis of certain messages, for which you need the entire message load. This can now be done simply via the admin console.

  1. Open the Properties view for the RequestMessageLogger primitive in the mediation flow and select the Promoted Properties view (Figure 8).

    Figure 8. Promoted properties
    Figure 8. Promoted properties

    Notice how each promoted property is given an alias name. This way, if there are multiple properties in the same module with the same name, you can distinguish between them in the admin console. In this case, we called the property RequestMessageLogger.root. If you check the message logger primitive in the response queue, you will notice that we promoted the same property there, but with a different alias, namely ResponseMessageLogger.root. Promoted properties with the same alias name will all share the same value.

Finishing the solution

You are now ready to deploy the mediation module and run a test.

  1. Go ahead and add the PackageStatusModuleApp to your test server. Once the application has started, switch to the J2EE perspective, and find the file named PackageStatusExport_PackageTrackingServiceHttp_Service.wsdl in the PackageStatusModule project under Other Projects. This file was generated as part of creating Web services bindings for the mediation module's export. Right click on the file and select Web services => Test with Web Services Explorer.

  2. Test the ESB service invocation with the tracking number 123. The result should be the same as before, just this time you should see more printouts in the server console because of the logger primitive that is being invoked. By default, the primitive logs messages in a Cloudscape® database. We will check it later to see what entries have been logged.

  3. But first, open the admin console for the test server, by right-clicking on it in the Servers view and selecting Run administrative console. In the admin console, navigate to the SCA Modules page, as shown in Figure 9.

    Figure 9. SCA Modules page
    Figure 9. SCA Modules page
  4. Click on the PackageStatusModule module link. On the following page, click on Module Properties under Additional Properties, and on the next page notice how it shows the two properties we promoted earlier, and their values:

    Figure 10. Module properties
    Figure 10. Module properties
  5. Change the RequestMessageLogger.root property to "/body". Click OK and save your changes. Log out of and close the admin console window.

  6. Now, run the same test as before in the Web Services Explorer. This time, though, use "456" as the tracking number. This will help you distinguish between the logged messages.

  7. Stop the server after you have run the test so that the lock on the logger database is released, enabling you to examine the logged messages. Use the cview utility, which is located in the [WebSphere Integration Developer install directory]\runtimes\bi_v6\cloudscape\bin\embedded directory. Start the utility, select the File => Open menu option, and find the EsbLogMedDB database located in the [WebSphere Integration Developer install directory]\pf\esb\databases directory. Open the MSGLOG table and examine its content using the Data tab. The window should look similar to Figure 11.

    Figure 11. cview utility
    Figure 11. cview utility

Stopping the server to view the logged messages is only necessary because we are using Cloudscape as the database. An actual production environment would utilize a production-level database, such as DB2®, and so stopping the server would not be required.

Changing the endpoint address

Above, you deployed two actual service provider instances, one primary PackageStatusService, and the additional service called PackageStatusBackupService. There are many situations in which you want to be able to easily switch the endpoint of the service being called; one is as you move from a development environment to a test environment. So how do you route messages to the backup service without changing the module in WebSphere Integration Developer, which would require a redeploy? There are two methods, one of which we will cover here.

  1. You can dynamically route a message to a new endpoint address by inserting an additional primitive (that is, the MessageElementSetter primitive) into the flow. This primitive can update the context header, causing the message to go to a different address than what it configured in the bindings of the import. It can optionally combine this with a lookup in a registry, like WebSphere Registry and Repository (for which there is an additional new primitive in Version 6.0.2 of WebSphere ESB and WebSphere Integration Developer). The details of this method are beyond the scope of this article, but you can find more information, together with a detailed scenario, in Dynamic routing improvements in WebSphere Enterprise Service Bus V6.0.2.

  2. You can change the endpoint address of an SCA module in the server's admin console. If you stopped the server, restart it, then run the administrative console, and open the SCA Modules page, just as before. Select the PackageStatusModule module and expand the Imports node under Module components (Figure 12).

    Figure 12. The Module components
    Figure 12. The Module components

    Click on the Binding link open a page that lets you override the endpoint URL that is used by this import. Change it to the endpoint URL of the backup service, which is http://localhost:9082/PackageStatusServiceBackup/services/PackageTrackingService. As before, we assume that your test server is using port 9082. If that is not the case, you will also need to update the URL to use the correct port .

    Finally, click on OK and save your changes. After that, run the test again; you should see the printout for the backup service in the server console.


In this article, you started using Web services (SOAP/HTTP) for your service interactions with WebSphere ESB. You deployed two identical Web services, under different endpoint addresses, both returning status information for a package. The mediation flow component established between the service requester and the service provider is straightforward and simply logs all messages that come across to a database.

You then learned how the support for promoted properties in WebSphere ESB V6.0.2 enables you to change properties for mediation primitives at runtime, via the admin console. In this example, you changed the level of detail of a message that is logged.

Finally, you saw how you can use the admin console to change the endpoint address used by an import with Web services bindings, which lets you reroute requests from one service provider to another -- again without the need to reload the module into the development tool and to redeploy it.

More in this series


Code samplepart3-downloads.zip52 KB



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 Business process management on developerWorks

Zone=Business process management, WebSphere, Architecture
ArticleTitle=IBM WebSphere Developer Technical Journal: Building an Enterprise Service Bus using WebSphere ESB, Part 3