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.
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.
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.
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.
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.
- 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.
- Make sure you save the settings to the Master Configuration so
that you do not have to install
- The newly installed applications do not start automatically so you need to manually start the application.
Verifying the installation of MyBackend
- 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,
- 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.
- Replace the port number in the default Inventory service URL and execute the URL from a browser.
- 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
- 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.xmland a sample SOAP response
- 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.
- Create a New Library in your workspace and name it
MyBackend-Lib. The WSDL for MyBackend is provided in MyBackend-WSDL.zip.
- 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.
- Create a new library in your workspace and name it
WCstands for WebSphere Commerce.
- You need to import the WSDL from the Web module
WebServicesRouterin WebSphere Commerce Server. The
WebServicesRouterWeb module is found in the
WC_eardirdirectory in a WebSphere Commerce Server, where as an example,
- Using the WSDL/Interface Import wizard, import the WSDL
InventoryServices.wsdl from the
WC_eardir\WebServicesRouter.war\component-services\wsdlfolder into WC-Lib.
Developing the mediation module
- 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
- Click Next and select the libraries as shown in Figure 2.
Figure 2. Selecting the required libraries
- 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
- Select Export from the palette and drop it into the assembly diagram.
- Edit the name, for example,
WC_InventoryServiceExport, to make it more meaningful.
- 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
- Right-click the export component and select Generate Binding... -> Web Service Binding.
- 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
- Save the Assembly diagram. Make sure that Build Automatically is selected.
The default URL generated for the export component is
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:
- Right-click the export component and select Show in Properties.
- In the Properties tab, click the Binding tab.
- Click the Configure button. The Module Deployment Editor opens.
- Click the Exports tab.
- Expand Context Root and edit the Context root to something
easier to remember, for example,
- In the Export Specific Settings section, select WC_InventoryServiceExport in the list of Web Service Exports.
- Expand the URL Mappings section and click Add.
- Add a new URL pattern, for example,
/InventoryService, as shown in Figure 5.
Figure 5. Export Configuration options
- Uncheck the Include default mapping checkbox.
- Save the changes.
- After the above changes, the URL to WC_InventoryServiceExport
- 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
Figure 6. Add wire confirmation
Defining the import component
- Select Import from the palette and drop it into the assembly diagram.
- Edit the name, for example,
MyBackend_InventoryServiceImport, to make it more meaningful.
- Right-click the import component and select Add Interface
and choose the Inventory interface of MyBackend as shown in
Figure 7. Choosing an interface
- Right-click the import component and select Generate Binding... -> Web Service Binding.
- Select Use an existing web service port and click Browse.
- Select the Web service port of the
MyBackend/InventoryService as shown in Figure 8 and
Figure 8. Choosing the Web service port
- 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
- Save the changes in the Assembly Diagram.
- 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.
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:
- Double-click BasicMediationImpl from the Assembly Diagram
and click OK if you get a confirmation as shown in Figure
Figure 10. Mediation flow confirmation
- 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.
- Click OK. The mediation flow editor opens.
- 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
CheckMaterialAvailability will be used in
this tutorial. To connect the operations do the following:
- Click the
and add the wire to CheckMaterialAvailability as
shown in Figure 11.
Figure 11. Connecting operations
- 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
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
you need to use the XSL transformation mediation primitive. Do the
- Click the Transformation tab on the palette.
- Select XSL Transformation and drop it into the Request flow.
- Edit the name to a meaningful one, for example,
- 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
- 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:
- Double-click GetInventoryAvailabilityXSLT, which opens the wizard to create a new XML Mapping.
- Enter the details as shown in Figure 14.
Figure 14. Creating a new XML map
- 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
Figure 15. Specifying the message types
- Click Finish. It opens the GetInventoryAvailabilityXSLT map in the Mapping Editor.
- Go back to the mediation flow editor and save the changes.
To map the business objects in GetInventoryAvailabilityXSLT map do the following:
- Open the GetInventoryAvailabilityXSLT map.
- 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. Setting the value in assign transform
- 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. Setting the output array indices
- Save the changes.
- 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.
- 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
Figure 18. Response flow
- 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.
- 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
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
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
The Download section contains an EAR application,
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
Testing the mediation module
- You need to post the SOAP request
GetInventoryAvailabilityto 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,
- Verify that you get the sample response for the sample request.
- After receiving the response, you can launch DBAccessApp
using the URL
http://localhost:9081/db/accessand 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.
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.
The author would like to thank Jacob Vandergoot for his help in reviewing this tutorial.
|Proxy backend files||MyBackend.ear||27KB|
|WSDL files from MyBackend||MyBackend-WSDL.zip||3KB|
|Basic mediation module||BasicMediation_PI.zip||18KB|
|Database access application||DBAccessApp.ear||5KB|
- Design pattern for Get service implementation
- WebSphere Commerce extended XPath notation
- Working with modules and libraries
- Creating mediation flows
- Implementing authentication
- Configuring SSL for secure outbound Web service calls from WebSphere Commerce to WebSphere ESB