Converting WebSphere ESB resources for use in IBM Integration Bus: Part 1

This two-part article series shows you how to convert WebSphere Enterprise Service Bus (WebSphere ESB) resources so that they can be used by the new IBM Integration Bus product. Part 1 describes a simple mediation scenario, highlights the architectural differences between WebSphere ESB and IBM Integration Bus, and shows you how to use the conversion tool.


Ben Thompson (, Consulting IT Specialist, IBM

Photo of Ben ThompsonBen Thompson is the Lead Architect for Industry Integration Packs on the IBM Integration Bus Development team at the IBM Software Lab in Hursley Park, United Kingdom. He joined IBM in 2000 and has worked with WebSphere Message Broker since Version 2. For many years, he worked as a consultant with IBM Software Services for WebSphere, designing and implementing WebSphere solutions for IBM customers worldwide. You can contact Ben at

14 August 2013

Also available in Chinese


IBM® Integration Bus is IBM's new strategic connectivity and integration product. It combines the capabilities of WebSphere Message Broker and WebSphere ESB, and its new name signifies its functional and operational growth to support WebSphere ESB use cases, whilst also building upon its recognized position as the industry-leading middleware product for universal connectivity. The IBM Integration Bus V9 Integration Toolkit provides tooling to speed the conversion of resources that were created for deployment to a WebSphere ESB runtime (using the WebSphere Integration Developer toolkit or the IBM Integration Designer toolkit) so that they can be used with IBM Integration Bus.

This article shows you how to convert resources for a WebSphere ESB mediation that implements a web service to convert temperatures between Fahrenheit and Celsius. A Project Interchange file is provided which contains the relevant WebSphere ESB resources.

Generally, it is more common for a WebSphere ESB mediation to transform and route data between a web service consumer and a web service provider, rather than from the web service provider implementation itself. However, the sample WebSphere ESB mediation in this article lets you focus on how to use the conversion tool, and on the differences between IBM Integration Bus and WebSphere ESB in regard to interfaces, subflows, maps, inputs, and outputs. The web service in this scenario provides two operations, both consisting of a Request-Response message exchange pattern. The FahrenheitToCelsius operation converts a temperature from Fahrenheit to Celsius, while the CelsiusToFahrenheit operation converts a temperature from Celsius to Fahrenheit (for simplicity, only whole number temperatures are used).

Figure 1. WebSphere ESB mediation module TemperatureTranslate
Figure 01

Figure 1 shows the TemperatureTranslate mediation module project displayed in the Business Integration perspective in IBM Integration Designer. In this example, a single project has been used to contain the Export, Mediation Flow, Interface, and Transformation data maps. The next section of this article steps through the conversion process, which is followed by an analysis of the similarities and differences between the resources in WebSphere ESB and IBM Integration Bus.

IBM Integration Designer export process

The IBM Integration Bus V9 conversion tool accepts build-time resources which were originally created for deployment to WebSphere ESB runtime servers. All versions of WebSphere ESB (6.2 and all later versions), which are currently in service are supported by the conversion tool.

  1. Begin by exporting a Project Interchange file from the IBM Integration Designer (or WebSphere Integration Developer if you are running the older version of the WebSphere ESB development tooling). Select File => Export to invoke the export wizard, and then from the Business Integration category, select Integration modules and libraries as shown in Figure 2, before clicking Next:
    Figure 2. IBM Integration Designer Export Dialog
    Figure 02
  2. On the next page of the dialog select the radio button which specifies that the exported content should be a Project interchange for sharing between workspaces, select the TemperatureTranslate mediation module, and click Next:
    Figure 3. IBM Integration Designer selection of projects for export
    Figure 03
  3. On the last page of the dialog, provide a Target file for the Project Interchange. Use the name This project interchange zip file is attached to the end of the article, so if you do not have access to an IBM Integration Designer tooling and would like to explore the conversion tool in the IBM Integration Bus Integration Toolkit, you can simply start from the import instructions in the next section of the article.

IBM Integration Toolkit Conversion Process

Now that we have exported a valid project interchange file from IBM Integration Designer, we can import its contents into the IBM Integration Bus V9 Integration Toolkit, and use them to drive the conversion tool.

Be careful when selecting the import option

Do not choose the Standard Project Interchange option. The WebSphere ESB Project Interchange import process is specifically designed to prepare the WebSphere ESB projects for conversion. When imported, they are given a setting for their project nature that causes them to be displayed with familiar icons in a specific category in the Integration Development perspective. Importing them in this way also avoids undesirable side effects related to accidental launch of the Workspace Migration wizard. If you accidentally encounter this situation and see the Workspace Migration dialog, see the IBM Integration Bus information center for an explanation and workaround.

  1. Begin by importing the WESB Project Interchange file: Invoke the Import wizard by selecting File => Import and then from the Other category, select WebSphere ESB Project Interchange and then click Next.
  2. On the next page of the dialog, navigate to the and select the TemperatureTranslate mediation module and click Finish. By default, the option to Launch WebSphere ESB conversion after import is selected. If you untick this selection, you can always launch the conversion tool later by right-clicking a project in the WebSphere ESB Projects category and selecting the menu option Convert to Integration Bus resources.
  3. Whichever method you use to launch the WebSphere ESB conversion tool, a dialog opens and requires you to specify a Project and a Conversion session filename (such as ConversionSession01). The choices made during the conversion process are stored in this file in addition to a record of the conversion results. For simplicity, keep the default option of using a project named WESB_Conversions for this purpose. When you have provided these details, click Finish.
  4. The conversion session file is created and opened with its editor as shown below in Figure 4. The editor contains five numbered steps which walk the user through the conversion process. The first of these steps requires the user to specify which WebSphere ESB Source projects should be converted as part of this conversion session. You can convert as many projects together at the same time as you like. Typically it is likely to be easiest to convert projects which share the same referenced WebSphere ESB projects at the same time as part of the same conversion session. The current scenario involves a single WebSphere ESB Source project – the mediation module named TemperatureTranslate. Each WebSphere ESB source project will have a corresponding Integration Bus target project created. By default the name of the target project will be the same as the WebSphere ESB project. but prefixed with IBM Integration Bus_. If you wish to change it you can do so by clicking on the name in the table. Keep the default settings and hit the Next link in the bottom right of the editor.
    Figure 4. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 1
    Figure 04
  5. Step 2 (shown below in Figure 5) of the conversion tool displays a summary of the resources selected for conversion, with conversion notes explaining what will happen when the conversion is started. You can select different levels in the tree view on the left side of the editor and the relevant notes are displayed on the right. The notes include links to documentation in the IBM Integration Bus information center, which explain some of the concepts in greater detail. Figure 6 shows the XML Maps level of the hierarchy selected. Here you will see a list of the XML maps which will be converted. Any maps that the tool has located that are actually referenced from an XSL Transformation primitive in a mediation flow will be selected by default and cannot be unticked. Keep the default settings and click Next at bottom right.
    Figure 5. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 2 (TemperatureTranslate conversion notes)
    Figure 05
    Figure 6. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 2 (XML Maps conversion notes)
    Figure 06
  6. Step 3 (shown below in Figure 7) of the conversion tool provides global conversion options which describe how IBM Integration Bus will convert particular mediation primitives, and particular Import and Export bindings. These options are referred to as global because they will apply to all instances of the primitives which are encountered throughout the mediation flows being converted. Most primitives are handled by a Built-in Converter class. This means that the conversion tool has capability out of the box which handles these primitives. Some primitives are not yet handled by the conversion tool, and by default the conversion tool will introduce a subflow at the relevant point in the generated target IBM Integration Bus message flows. This approach lets the conversion tool maintain the wiring of a mediation flow component, and essentially converts the primitive into an IBM Integration Bus Passthrough message flow node. As its name suggests, this node does not process the message in any way and is used for documentation purposes only. The message that it propagates to its Out terminal is the same message that it receives on its In terminal.
    Figure 7. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 3
    Figure 07
  7. Step 4 (shown below in Figure 8) of the conversion tool provides a summary of the options chosen in the previous steps of the Editor and provides a button to Start conversion. Review the summary and click the button. Depending on the number of resources being converted, the conversion can take a minute or two, with a progress window showing what is happening whilst the conversion is being run:
    Figure 8. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 4
    Figure 08
  8. Step 5 (shown below in Figure 9) of the conversion tool is the last step in the process and shows a summary of what has been converted. If follow-up manual actions are required, they are listed on this last panel. The summary shows the original WebSphere ESB files and their closest equivalents in IBM Integration Bus:
    Figure 9. IBM Integration Bus V9 Integration Toolkit Conversion Tool Step 5
    Figure 09

Comparison of WebSphere ESB and IBM Integration Bus transformation concepts

The Assembly Diagram shown below in Figure 10 depicts the relationship between the Export component (Export1) and the Mediation Flow component (TemperatureTranslate):

Figure 10. WebSphere ESB TemperatureTranslate assembly diagram
Figure 10

WebSphere ESB uses exports to define how an SCA (Service Component Architecture) module can be accessed by a web service requester. In our example, Export1 has a SOAP/HTTP web service binding. For integration developers who are familiar with the WebSphere Message Broker, the Assembly Diagram can be confusing as there is no directly equivalent view in the WebSphere Message Broker Toolkit. In particular, note that the WebSphere ESB Assembly Diagram is specifically not equivalent to a message flow diagram in WebSphere Message Broker. The purpose of the assembly diagram is to express service composition relationships between SCA components. The wires between the boxes symbolize which components access which other components. The wires do not symbolize a direction of travel, nor do they imply that messages flow across the wires. The TemperatureTranslate assembly diagram has a wire from Export1 to TemperatureTranslate identifying that the TemperatureTranslate mediation flow component provides the service to the export. Note that an export can have only one wire leading out of it.

The closest equivalent offered by IBM Integration Bus and WebSphere Message Broker to the role of a WebSphere ESB Export, is that of an input node in a message flow. The IBM Integration Bus conversion tool creates integration services from mediations, which are driven by exports that have a SOAP/HTTP web service binding. IBM Integration Bus integration services are specializations of IBM Integration Bus applications. IBM Integration Bus applications are deployable containers or groupings of related resources (such as message flows, subflows, and message models) that are required to create an integration solution. Typically, an IBM Integration Bus application contains several message flows that an integration developer would like to administer as a single unit – in other words, deployed together, started together, and stopped together. As a specialization of IBM Integration Bus applications, IBM Integration Bus integration services have a defined interface (defined using WSDL) and structure and they act as a container for a Web Services solution. The structure of an IBM Integration Bus integration service includes:

  • One main message flow containing the SOAPInput and SOAPReply nodes which parse and write the input and output data.
  • One subflow for each operation defined by the Integration Service's WSDL.

Given this background, when the conversion tool creates IBM Integration Bus resources from WebSphere ESB resources, it maps the concept of the WebSphere ESB Export to the SOAPInput node of the main message flow within the IBM Integration Bus Integration Service. In the IBM Integration Designer, the Export of TemperatureTranslate is wired to the mediation flow component itself, which is shown below in Figure11:

Figure 11. WebSphere ESB Overview of the TemperatureTranslate mediation flow component
Figure 11

The mediation flow component's overview shows the interface for the TemperatureTranslate web service. The interface is named TemperatureTranslateType (this is the name of the portType in the WSDL) and it shows the two operations, FahrenheitToCelsius and CelsiusToFahrenheit. When you open the Integration Service in the IBM Integration Bus Toolkit created as the result of running the conversion tool, you can view the equivalent information on its Service tab (as shown below in Figure12:

Figure 12. IBM Integration Bus Integration Service, Service tab view
Figure 12

In IBM Integration Designer you can navigate to the mediation flow representing a particular operation by clicking its hyperlink (as shown above in Figure 11). In the same style, in the IBM Integration Toolkit, you can navigate to the subflow representing a particular operation by clicking its hyperlink (as shown above in Figure 12).

Figure 13. WebSphere ESB TemperatureTranslate Mediation Flow, FahrenheitToCelsius operation
Figure 13
Figure 14. IBM Integration Bus TemperatureTranslate FahrenheitToCelsius operation subflow
Figure 14

As shown above in Figures 13 and 14, the display adopted by WebSphere ESB and IBM Integration Bus are very similar in concept. Note that in the IBM Integration Bus Toolkit, if a service includes a callout to another service, then both the Request and Response portions of the flow are displayed on the same tab, where as in IBM Integration Designer they are separated on to different tabs.


IBM Integration Bus V9 is IBM's new strategic integration product (built upon the same architecture as WebSphere Message Broker). The Integration Bus Toolkit provides the first capability for converting build-time resources which were originally created to support WebSphere Enterprise Service Bus use cases. This article has demonstrated using the tool to convert a simple mediation and also discussed some of the architectural differences between the two products. The second article in this series involves a more complex scenario based on the WebSphere Enterprise Service Bus StockQuote sample which shows a wider range of mediation primitives being converted and also discusses the conversion tool's extension points.


Code samplePI_WESB_TemperatureTranslate.zip15 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 WebSphere on developerWorks

ArticleTitle=Converting WebSphere ESB resources for use in IBM Integration Bus: Part 1