WebSphere Commerce as a service provider

When you enable business operations in WebSphere Commerce as Web services that can be accessed by external systems, WebSphere Commerce becomes the service provider.

The deployment model for Web services is to have a central server with published WSDL that defines the services it supports. From there, clients, whether they are external systems, Web applications, or rich client applications, will connect to the central server and invoke services that are defined by the publicly available WSDL.

 

Processing the request

The WebSphere Commerce Web service framework uses the approach of mapping the XML (SOAP body) request into the name-value-pair parameters passed to the service command that will be executed.

In terms of overall Web service request handling, the WAS Web service engine is responsible for delegating the request to the WebSphere Commerce Web service framework, and the framework is responsible for processing the request and generating the response. Processing the request consists of resolving credentials to associate with the request, converting the SOAP body into name-value pairs, mapping to a controller command, executing the command, and using the JSP composition service to create the response.

From the high-level perspective, success and application exceptions are handled in a similar fashion. The only difference is the JSP page used to compose the response: when an exception occurs, the error view will be used to determine the JSP page composing the response. For example, taking the OAGIS approach, the resulting document for the request would contain the status of the operation. This means that if an application exception occurs (that is, command execution results in an error), the resulting business object document would still be created but will indicate failure. A Web service fault will be returned only if an external error, such as an exception or a SOAP fault returned by the JSP page, occurs when preparing the request for processing. Refer to the Faults and error response section below for further details.

Standard OAGIS messages are not supported. Although the OAGIS style of interaction is used, only the OAGIS message envelope and verbs have been adopted by WebSphere Commerce. Simplified nouns which better represent the structure of how the business objects are modeled in WebSphere Commerce have been provided.

 

Create the response

The WebSphere Commerce Web service framework leverages the JSP composition service for creating the XML response to a Web service request. This allows the user to simply modify the JSP template file in order to insert additional nodes in the response instead of having to provide Java code for this capability.

JSP page resolution differs somewhat between the WebSphere Commerce Struts-based Web application and the WebSphere Commerce Web services:

Struts-based Web application:

• The result of executing the business logic is a set of response properties, one of which is the name of the view to be used to determine which JSP page to invoke.

• The JSP page invoked generates an HTML response.

Web services:

• The view for determining the response is specified in the mapping configuration. The view in the response properties is only used if no view is found in the mapping configuration.

• The view for Web service response uses a JSP page to generate an XML response, which is returned as the response message to the Web service request. The Web service engine handles adding the necessary SOAP envelope to the response, and the Web service framework provides the capability of converting the XML JSP response to the SOAP element.

Configure the view in the mapping is accomplished as follows:

<TemplateDocument>
              <DocumentType
version="6.0">SyncCatalog</DocumentType>
              <StartElement>SyncCatalog</StartElement>
             
<TemplateTagName>SyncCatalog90Map</TemplateTagName>
              <CommandMapping>
                     <Command
CommandName="com.ibm.commerce.catalogmanagement.commands.CatalogUpdateCmd">
                           
<Constant
Field="viewTaskName">SyncCatalogSuccessView</Constant>                           
<Constant
Field="errorViewName">SyncCatalogErrorView</Constant>                     </Command>
              </CommandMapping>
              ...

Note the use of the viewTaskName and the errorViewName constant to specify the success and error response view, respectively.

For mapping non-browser requests to a JSP page, WebSphere Commerce uses the device format ID as part of the view name. This means that the device format ID will be set in the WebSphere Commerce Web service controller and every view defined for a Web service response will be of the format view_name/ store_ID/ device_format . The device format used for Web services is -10.

The following sample snippet configures GetCatalogView to generate a Web service response:

<forward className="com.ibm.commerce.struts.ECActionForward"
name="GetCatalogView/0/-10"
path="webservices/OAGIS/9.0/BODs/ShowCatalog.jsp">
      <set-property property="properties"
value="storeDir=no"/>
      <set-property property="implClassName"
value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl"/>
      <set-property property="interfaceName"
value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommand"/>
      <set-property property="direct" value="true"/>
      <set-property property="resourceClassName"
value="com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl"/>
</forward>
...
<action path="/GetCatalogView"
type="com.ibm.commerce.struts.BaseAction"/>

 

Response-only requests

A common scenario is response-only requests, where no business logic processing is required and the sole purpose of the request is to obtain data. However, the current implementation of the mapping specifies an interface name as the command argument to represent the business logic to execute. Instead of creating a do-nothing business logic command, the mapping can be configured to execute only the view processing logic, as shown in the following snippet. When a response-only request is indicated, the WebSphere Commerce Web service controller will use the command name as the view to execute the response.

<TemplateDocument>
              <DocumentType
version="6.0">GetCatalog</DocumentType>
              <StartElement>GetCatalog</StartElement>
             
<TemplateTagName>GetCatalog90Map</TemplateTagName>
              <CommandMapping>
                     <Command CommandName="GetCatalogView">
                           <Constant
Field="ibm.wc.responseOnly">true</Constant>
                     </Command>
              </CommandMapping>
              ...

 

Faults and error response

In a typical Struts Web application, errors are handled when exceptions are thrown. Inside the exception is the view used to compose the error response, and if no view is specified, then a generic view is used. For the Struts Web application, the error response is used to present an HTML response displaying the error.

For Web services, two approaches can be taken:

1. Include the error information in the returned XML response. This would require the client to inspect the response from the request to check whether it contains the error response.

2. Utilize the fault definition that can be defined in WSDL. Web services allow different faults that may be associated with a service operation, and when JAX-RPC is used to generate the client proxy, these fault definitions will be represented as Java exception objects and will be thrown. With this approach, the client application can catch faults and react to them accordingly instead of inspecting the resulting response object.

Since it is not always known how the error response should be returned, the WebSphere Commerce Web service framework supports both approaches. The decision as to how the exception information should be represented rests with the JSP page that composes the error response.

The out-of-the-box implementation of the exception JSP response pages represents the exception as a fault. It will return pertinent information regarding the exception wrapped into a SOAP fault definition. This implementation is used for all the runtime and infrastructure exception views, but it is left to the implementer to decide which approach to use for customer error views.

The following JSP snippet shows an example of composing a Web service fault:

<%
      com.ibm.commerce.beans.ErrorDataBean errorBean = new
com.ibm.commerce.beans.ErrorDataBean();
      com.ibm.commerce.beans.DataBeanManager.activate(errorBean,
request, response);
      System.out.println ("ErrorDataBean:\n" +
errorBean.toString()+"\n");      
%>
<Fault>

<faultcode>Client</faultcode>
<faultstring><%= errorBean.getMessage()
%></faultstring>
<faultactor><%= errorBean.getOriginatingCommand()
%></faultactor>
<detail><%= errorBean.getCorrectiveActionMessage()
%></detail>
</Fault>

 

WSDL format

The WSDL format promoted by WebSphere Commerce is document/literal wrapped. There are many benefits for using this format, including validation and WS-I compliance. For more information on the different WSDL formats, see http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/.

• Enabling WebSphere Commerce as a service provider
  You can enable a business operation defined by WebSphere Commerce as a Web service. In this scenario, WebSphere Commerce acts as the service provider to external systems.

• Security and the WebSphere Commerce Web service framework
  The WS-Security specification (http://www.oasis-open.org/committees/wss/) defines several techniques for implementing Web service security.

• Web service caching
  The WAS Web service engine provides caching support, so that a Web service request can be cached and the cached response returned in place of subsequent processing.

• Modifying an inbound Web service
  To avoid having customization overwritten by future versions of WebSphere Commerce, we do not recommend that you modify existing inbound services. Instead, create a new version of the inbound service based on existing ones.

• Deploying an inbound Web service
  Deploying a web service to your production environment is treated the same way as deploying other assets -- as updates to the WebSphere Application Server using the WAS Administration Console.

• Inbound Web services provided
  WebSphere Commerce includes code and documentation that allow you to enable WebSphere Commerce business operations as Web services. You can allow WebSphere Commerce to be the service provider by enabling its business functions as Web services that can be accessed by external systems. The following Web services are provided by WebSphere Commerce.

• Configure the Secure Sockets Layer
  The SSL is required by inbound services of WebSphere Commerce to use SOAP/HTTPS.

Related concepts

Understanding the WebSphere Commerce Web service framework

WebSphere Commerce Web services with JSP pages

Business Object Documents long description

Related tasks

Enabling WebSphere Commerce as a service provider

Tutorial: Defining an inbound Web service

Tutorial: Defining a User Registration Web Service

Configure a Web application

Related reference

Additional information about Web services

Inbound Web services provided