Developing a WebSphere Commerce Get Web service mediation in WebSphere Enterprise Service Bus, Part 1

Part 1 of this 2-part tutorial series provides a series of tasks to help you develop a basic mediation of an IBM® WebSphere® Commerce Web service in IBM WebSphere Enterprise Service Bus.

Asim Boruwa (asim.boruwa@in.ibm.com), Software Engineer, IBM

Author photo: Asim BoruwaAsim Boruwa is a Staff Software Engineer at the IBM India Software in Bangalore, India. He has been with the WebSphere Commerce development team for the last 4.5 years. He has worked in various areas of WebSphere Commerce. His areas of expertise in WebSphere Commerce are component services and SOA, external system integration, B2B, B2C, and the Management Center framework. He currently works as a Technical Consultant for IBM Software Services for WebSphere (ISSW) and consults WebSphere Commerce customers. He has published other articles on developerWorks WebSphere.



18 November 2009

Also available in Chinese

Before you start

Following service-oriented architecture (SOA), WebSphere Commerce uses Web services as the medium to integrate with backend systems like ERP, CRM, Yantra, or DOM. WebSphere Commerce has a Web services framework that has different business components containing both inbound and outbound Web services. This tutorial uses WebSphere Enterprise Service Bus (hereafter called WebSphere ESB) as the middleware for mediating outbound messages from WebSphere Commerce to a backend system.

In this tutorial, you will learn the basic tasks required to develop a mediation module for mediating messages from WebSphere Commerce to a backend system. WebSphere Commerce typically contains four Web services patterns: Get, Process, Sync, and Change. Part 1 will help you build mediation modules for Web services patterns Process, Sync, and Change. However, to develop a mediation module for a Web service Get pattern, certain additional tasks are required to perform, which are discussed in Part 2. If you have already used WebSphere ESB for mediation, then you may skip Part 1 and go to Part 2.

Objectives

Learn how to:

  • Create reusable libraries using resources from WebSphere Commerce and a backend system in WebSphere ESB.
  • Log data objects using the message logger to audit a message flow.
  • Use the XSL transformation and business object map to transform a business object.

Prerequisites

You need to be familiar with the basic concepts of SOA and Web services. You also need to be familiar with the use of WebSphere Integration Developer as the Integrated Development Environment for the development of applications that run on WebSphere ESB.

System requirements

To follow the examples in this tutorial, you need WebSphere Commerce V6.0 with Feature Pack 5 and WebSphere Integration Developer V6.1.2 with a Test Enterprise Service Bus V6.1 server profile.

Duration

3 hours


Introduction

WebSphere Commerce remains consistent in the message format for both the inbound and outbound Web services that it has to offer. It uses the OAGIS standard for the messages. A middleware like WebSphere ESB is used to mediate messages from WebSphere Commerce to backend system and vice-versa. In this tutorial, you will use a proxy backend system that provides inbound Web services interfaces for integration. In Part 1, you will learn how to create a basic mediation module in WebSphere ESB, importing the required assets from WebSphere Commerce and the backend system.

The tasks required for mediating WebSphere Commerce Web services patterns Process, Sync, and Change are similar to what you will see in Part 1. The parameters in the Web service request for these three patterns are set in the business object itself in the form of properties and attributes. Hence, message transformation usually involves assigning the value of the property or attribute from the business object in the WebSphere Commerce interface to the equivalent property or attribute in the backend interface.

Since the main objective of this tutorial is to explain mediating Get services, we will use an outbound GetInventoryAvailability service as an example through out this tutorial. You will learn the tasks required to develop the basic mediation of GetInventoryAvailability, which is common for all four patterns. In Part 2, you will learn the additional tasks specific for a Get pattern that are required to develop the mediation of GetInventoryAvailability.

You will use a proxy backend system named "MyBackend", which contains an Inventory service that has its own message format. SOAP/HTTP will be used as the transport for the Web services in this tutorial.


Setting up the environment

In the following sections, you will learn how to set up your development environment for developing the mediation module in WebSphere Integration Developer.

Installing the proxy backend

The proxy backend MyBackend is provided as an EAR file, MyBackend.ear, in the Download section.

  1. Login to the WebSphere ESB admin console of your test WebSphere ESB server and install MyBackend.ear. The MyBackend application has been kept simple and it does not need any additional configuration. Leave all the options to default and finish the installation.
  2. Make sure you save the settings to the Master Configuration so that you do not have to install MyBackend.ear every time.
  3. The newly installed applications do not start automatically so you need to manually start the application.

Verifying the installation of MyBackend

  1. The default URL to the Inventory service in MyBackend is http://localhost:9081/MyBackend/InventoryService. Since you have not overridden the default configuration during installation, the Web module of MyBackend gets bound to the default virtual host, default_host.
  2. Check the port numbers under the host aliases of default_host by logging in to the WebSphere ESB admin console. By default, it has port 9081, which is used for inbound Web service requests.
  3. Replace the port number in the default Inventory service URL and execute the URL from a browser.
  4. If you get a response like "Hi there, this is a Web service!", then it means that the Inventory Web Service is running.

Testing the Inventory service in MyBackend

  1. Use a test utility, like Web Services Explorer, available in WebSphere Integration Developer to post the SOAP request to the Inventory service using the URL http://localhost:9081/MyBackend/InventoryService. The sample zip file Sample_Messages_Part_1.zip contains a sample SOAP request CheckMaterialAvailability.xml and a sample SOAP response ShowMaterialAvailability.xml.
  2. Verify that you get the sample response for the sample request.

Creating the libraries

Creating libraries with the specific resources from WebSphere Commerce and backend are necessary. A single library can be shared by multiple mediation modules. It is easier to organize and maintain the end-systems specific resources in a library. You can create a new library from File -> New -> Library. In this tutorial, you are dealing with two end-systems - WebSphere Commerce and MyBackend. The following sections will demonstrate how you can create libraries containing the specific resources from WebSphere Commerce and MyBackend.

Creating the MyBackend library - MyBackend-Lib

To follow the scenarios in this tutorial, the only resource required from MyBackend is the WSDL file for the Inventory service in MyBackend.

  1. Create a New Library in your workspace and name it MyBackend-Lib. The WSDL for MyBackend is provided in MyBackend-WSDL.zip.
  2. Extract the contents of MyBackend-WSDL.zip into a temporary folder and from the temporary folder. Import the WSDL to MyBackend-Lib using the WSDL/Interface Import wizard.

Creating the WebSphere Commerce library - WC-Lib

You require only the WSDL for the Inventory service in WebSphere Commerce.

  1. Create a new library in your workspace and name it WC-Lib, where WC stands for WebSphere Commerce.
  2. You need to import the WSDL from the Web module WebServicesRouter in WebSphere Commerce Server. The WebServicesRouter Web module is found in the WC_eardir directory in a WebSphere Commerce Server, where as an example, WC_eardir stands for C:\Websphere\AppServer\profiles\demo\installedApps\WC_demo_cell\WC_demo.ear.
  3. Using the WSDL/Interface Import wizard, import the WSDL InventoryServices.wsdl from the WC_eardir\WebServicesRouter.war\component-services\wsdl folder into WC-Lib.

Developing the mediation module

  1. Create a new mediation module from File -> New -> Mediation Module and enter the details as shown in Figure 1.
    Figure 1. Creating a mediation module
    Creating a mediation module
  2. Click Next and select the libraries as shown in Figure 2.
    Figure 2. Selecting the required libraries
    Selecting the required libraries
  3. Click Finish. At this point, a new mediation module named “Basic” is created and the Assembly Diagram opens automatically in the Assembly Editor. This contains a mediation flow component called "BasicMediationImpl".

Mediation module assembly

Now you have a mediation module containing only a mediation flow component, BasicMediationImpl. The mediation flow component is useless without an export component, as otherwise it cannot be executed by any external request. An import component is required so that the mediation flow can invoke the Inventory service in MyBackend. The following sections will demonstrate how you can define an export and an import component in the mediation module.

Defining the export component

  1. Select Export from the palette and drop it into the assembly diagram.
  2. Edit the name, for example, WC_InventoryServiceExport, to make it more meaningful.
  3. Right-click the export component and select Add Interface and choose the Inventory interface of WebSphere Commerce as shown in Figure 3.
    Figure 3. Choosing an interface
    Choosing an interface
  4. Right-click the export component and select Generate Binding... -> Web Service Binding.
  5. In the Transport Selection pop-up window, select soap/http as shown in Figure 4 and click OK.
    Figure 4. Choosing the Web service transport
    Choosing the Web service transport
  6. Save the Assembly diagram. Make sure that Build Automatically is selected.

The default URL generated for the export component is http://localhost:9080/BasicWeb/sca/WC_InventoryServiceExport. Here, BasicWeb is the context root of the Web module of Basic mediation module and sca/WC_InventoryServiceExport is the relative URL. The default URL is difficult to remember. Hence, to simplify the URL, do the following:

  1. Right-click the export component and select Show in Properties.
  2. In the Properties tab, click the Binding tab.
  3. Click the Configure button. The Module Deployment Editor opens.
  4. Click the Exports tab.
  5. Expand Context Root and edit the Context root to something easier to remember, for example, Basic.
  6. In the Export Specific Settings section, select WC_InventoryServiceExport in the list of Web Service Exports.
  7. Expand the URL Mappings section and click Add.
  8. Add a new URL pattern, for example, /InventoryService, as shown in Figure 5.
    Figure 5. Export Configuration options
    Export Configuration options
  9. Uncheck the Include default mapping checkbox.
  10. Save the changes.
  11. After the above changes, the URL to WC_InventoryServiceExport becomes http://localhost:9080/Basic/InventoryService.
  12. Now, add the wire from WC_InventoryServiceExport to BasicMediationImpl. If there is a confirmation pop-up similar to Figure 6, click OK. Save the changes in the Assembly Diagram.
    Figure 6. Add wire confirmation
    Add wire confirmation

Defining the import component

  1. Select Import from the palette and drop it into the assembly diagram.
  2. Edit the name, for example, MyBackend_InventoryServiceImport, to make it more meaningful.
  3. Right-click the import component and select Add Interface and choose the Inventory interface of MyBackend as shown in Figure 7.
    Figure 7. Choosing an interface
    Choosing an interface
  4. Right-click the import component and select Generate Binding... -> Web Service Binding.
  5. Select Use an existing web service port and click Browse.
  6. Select the Web service port of the MyBackend/InventoryService as shown in Figure 8 and click OK.
    Figure 8. Choosing the Web service port
    Choosing the Web service port
  7. Add the wire from BasicMediationImpl to MyBackend_InventoryServiceImport and click OK if you get a confirmation as shown in Figure 9.
    Figure 9. Add wire confirmation
    Add wire confirmation
  8. Save the changes in the Assembly Diagram.
  9. After completing Step 6, the import component is bound to the default URL mentioned in the Web service port of MyBackend Inventory service WSDL, which is http://localhost:9081/MyBackend/InventoryService. If required, modify the URL in the properties of MyBackend_InventoryServiceImport after resolving the URL of the MyBackend Inventory service by performing the tasks mentioned in Verifying the installation of MyBackend.

Mediation flow

The export component and import component will take care of the Web Service invocation to and from the mediation flow. The mediation flow contains the implementation of the mediation logic between the interfaces. A mediation flow contains the mediation logic for multiple operation connections. To create the mediation flow implementation, do the following:

  1. Double-click BasicMediationImpl from the Assembly Diagram and click OK if you get a confirmation as shown in Figure 10.
    Figure 10. Mediation flow confirmation
    Mediation flow confirmation
  2. In the Generate Implementation pop-up window, click New Folder and enter a folder name, such as MediationImpl, and click OK. This will place the mediation flow implementation files inside the sub-folder MediationImpl for better file structure of the mediation module.
  3. Click OK. The mediation flow editor opens.
  4. Go back to Assembly Diagram and save the changes and close the Assembly Diagram.

Connecting the operations

Each operation connection in a mediation flow implementation contains the mediation logic for a certain scenario. The interfaces that you see on the left-hand side are the interfaces that the Export components in the mediation module support. The interfaces that you see on the right-hand side are the references to the interfaces that the import components in the mediation module support. Each export interface can refer to multiple import interface references. However, for the sake of simplicity, only a single operation connection between GetInventoryAvailability and CheckMaterialAvailability will be used in this tutorial. To connect the operations do the following:

  1. Click the GetInventoryAvailability operation and add the wire to CheckMaterialAvailability as shown in Figure 11.
    Figure 11. Connecting operations
    Connecting operations
  2. Save the changes.

Implementing the mediation flow

In this section, you will learn how to implement the mediation flow for the operation connection that you have made between GetInventoryAvailability and CheckMaterialAvailability. Click the wire so that the request and response flows for the operation connection are displayed on the lower half of the mediation flow editor as shown in Figure 12.

Figure 12. Implementing the request and the response flow
Implementing the request and the response flow

To transform GetInventoryAvailability to CheckMaterialAvailability, you need to use the XSL transformation mediation primitive. Do the following:

  1. Click the Transformation tab on the palette.
  2. Select XSL Transformation and drop it into the Request flow.
  3. Edit the name to a meaningful one, for example, GetInventoryAvailabilityXSLT.
  4. Click Input and wire its output terminal to the input terminal of GetInventoryAvailabilityXSLT, and the output terminal of GetInventoryAvailabilityXSLT to the input terminal of callout as shown in Figure 13.
    Figure 13. Wiring the components
    Wiring the components
  5. Save the changes.

The XSL transformation component has been added in the flow. However, you need to implement the mapping between the two business objects in the XSL transformation component. Do the following to create the map:

  1. Double-click GetInventoryAvailabilityXSLT, which opens the wizard to create a new XML Mapping.
  2. Enter the details as shown in Figure 14.
    Figure 14. Creating a new XML map
    Creating a new XML map
  3. Specify the message types. Since you have already connected the input and output terminals of the XSL transformation component, it automatically resolves the message types as shown in Figure 15.
    Figure 15. Specifying the message types
    Specifying the message types
  4. Click Finish. It opens the GetInventoryAvailabilityXSLT map in the Mapping Editor.
  5. Go back to the mediation flow editor and save the changes.

To map the business objects in GetInventoryAvailabilityXSLT map do the following:

  1. Open the GetInventoryAvailabilityXSLT map.
  2. The CheckMaterialAvailability request requires only two properties, MaterialNumber and FullfillmentCenter. In Part 2 of the tutorial, you will learn how to parse the XPath from GetInventoryAvailability and map the parameters to CheckMaterialAvailability. In Part 1, hard code the properties MaterialNumber and FullfillmentCenter so that a request can pass through. Right-click the property and select Create Transform, which displays the properties of the transform assign. Hard code a value, for example, MSCFF39B for MaterialNumber and FF01 for FullfillmentCenter as shown in Figure 16.
    Figure 16. Setting the value in assign transform
    Setting the value in assign transform
  3. Since you are hard coding the request for only one material, specify the array indices for the assign transforms from the Cardinality tab under Properties of the transform. Set the index of MaterialAvailability and MaterialNumber as “1” as shown in Figure 17.
    Figure 17. Setting the output array indices
    Setting the output array indices
  4. Save the changes.
  5. You can use the Test Map utility to test your XML map without deploying the mediation module. It helps you to narrow down a problem that might occur in the mediation module. You can provide a sample input XML containing the body and run the tool, which will display the resultant XML output on the right-hand side.
  6. The tasks required to implement the response flow is similar to what you have just learned for the request flow. In the response flow, you need to wire the output terminal of the callout response to the input terminal of the XSL transformation component. The output terminal of the XSL transformation component is connected to the input terminal of input response as shown in Figure 18.
    Figure 18. Response flow
    Response flow
  7. The Download section contains a sample mediation module implementation in BasicMediation_PI.zip. The ShowInventoryAvailabilityXSLT map in the sample code makes use of other XSL transforms like "For Each" and "Move". For Each and Move are some of the primitive XSL transforms. Refer to the online Help in WebSphere Integration Developer to learn more about the supported transform types.
  8. Import BasicMediation_PI.zip into your workspace using the Project Interchange import wizard. The mediation module Basic contains references to the libraries MyBackend-Lib and WC-Lib, which are not included in the project interchange zip. You need to first create the libraries as mentioned in the sections above and then import the project interchange in your workspace.

Auditing the business objects using message logger

A business object passes through different components in a mediation flow. Since it undergoes transformation, for debugging and auditing purposes, you can use the message logger primitive component in the mediation flow. For instance, you can use message logger to log the input and output business object of an XSL transformation. On execution of every flow, the business objects will be logged to the database. You can view the business objects in the message logs by querying the database.

The message logger has two transaction modes - "Same" and "New". If you use the Same transaction mode, then messages are logged using the same transaction of the message flow. This means that if an error occurs in the flow, logs will not be committed to database. If you use the New transaction mode, then a new transaction is created for the message logger and the logs will be committed using the new transaction. For debugging purposes, you can use the New transaction mode to identify the cause of the error in the flow.

The sample code already contains message loggers in the flows as shown in Figure 19.

Figure 19. Message loggers in mediation flow
Message loggers in mediation flow

The Download section contains an EAR application, DBAccessApp.ear. DBAccessApp provides a simple Web interface to query your database. Using this application, you can query your database to view the business objects logged by the message logger in the flows. Tasks required to deploy DBAccessApp are similar to what is mentioned in the sections Installing the proxy backend and Verifying the installation of MyBackend. The default URL to launch the database query page is http://localhost:9081/db/access.


Testing the mediation module

Tasks required to test the mediation module are similar to what is mentioned in the sections Verifying the installation of MyBackend and Testing the Inventory service in MyBackend.

  1. You need to post the SOAP request GetInventoryAvailability to the URL of the export component of the mediation module, which is http://localhost:9081/Basic/InventoryService. Sample_Messages_Part_1.zip provided in the Download section contains a sample SOAP request, GetInventoryAvailability.xml, and a sample SOAP response, ShowInventoryAvailability.xml.
  2. Verify that you get the sample response for the sample request.
  3. After receiving the response, you can launch DBAccessApp using the URL http://localhost:9081/db/access and view the business objects that are logged at various stages in the mediation flow.

Securing the mediation module

You can implement basic authentication by following the instructions given in Implementing authentication in the WebSphere Integration Developer Information Center.

To secure the messages at the transport layer, you can use HTTPS by following the instructions in Configuring SSL for secure outbound Web service calls from WebSphere Commerce to WebSphere Enterprise Service Bus.


Conclusion

From this tutorial, you learned how to create a basic mediation module in WebSphere Integration Developer using the interfaces from WebSphere Commerce and a proxy backend system. You learned how to:

  • Create libraries and use them in the mediation module.
  • Create the mediation assembly.
  • Connect the operations and how to implement the mediation flow.
  • Audit the business objects at different stages of the mediation flow.

Acknowledgements

The author would like to thank Jacob Vandergoot for his help in reviewing this tutorial.


Downloads

DescriptionNameSize
Proxy backend filesMyBackend.ear27KB
WSDL files from MyBackendMyBackend-WSDL.zip3KB
SOAP messagesSample_Messages_Part_1.zip3KB
Basic mediation moduleBasicMediation_PI.zip18KB
Database access applicationDBAccessApp.ear5KB

Resources

Learn

Discuss

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=447426
ArticleTitle=Developing a WebSphere Commerce Get Web service mediation in WebSphere Enterprise Service Bus, Part 1
publish-date=11182009