Customizing the Web service client invocation XML file

When WebSphere Commerce acts as a service consumer, a component client API will be called from your task command. The client API will use the invocation service and the invocation service will require a deployed configuration file to determine how to communicate with the remote component. Each component has a separate configuration file to configure the client API. Each store can also have a version of the configuration file that will take precedence over the default configuration. This allows the store to override some or the entire configuration without changing the default configuration.

About this task

The configuration file referenced in this task is created as part of the customization and is not shipped with the product. Customers must create the path and the file. The configuration file name is:

  • WC_eardir/ xml/config/ext/.global/component id/wc-invocation-client.xml where, for example component id is com.ibm.commerce.inventory for the inventory component

  • WebSphere Commerce Developer workspace_dir/wc/xml/config/ext/.global/ component id/wc-invocation-client.xml

To override the configuration for a store, a copy of the file can be placed in your WC_eardir/xml/config/ext/ storedir or WC_eardir/xml/config/ext/.global for all stores. During invocation, the service first determines if the store has a configuration defined. If it exists, the service merges the custom configuration into the default configuration. If not, the service uses the default configuration. This allows the ability for store override without changing the default configuration.

Follow the instructions in Deploying Java EE assets for a partial application to deploy client invocation configuration files.

The XSD for the configuration file is in the following directory:

  • For IBM i OS operating systemSolarisLinuxAIXWindows WC_eardir/xml/config/xsd
  • WebSphere Commerce Developer workspace_dir/wc/xml/config/xsd

This is a sample invocation XML file to call the CheckInventory service on SomeExternalApp, a fictitious application that provides order management services such as inventory checking.


<wc:InvocationService
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:wc="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce
../../../xsd/wc-invocation-client.xsd">

The binding element, as seen below, should always be in your invocation file. The implementation must implement the InvocationBinding interface.



        <wc:InvocationBinding
               
bindingImpl="com.ibm.commerce.foundation.services.invocation.internal.impl.JCAInvocationBindingImpl"
/>

The action section can be used to scope configuration at a component or action level. It also allows for the use of an internal mediation plug-in that implements the MessageInvocationMediator interface. The example action element bindings below specify a JSP to be used to mediate between the WebSphere Commerce use of OpenApplications Group (OAGIS) message structure and the WSDL used by SomeExternalApp.

The asynchronous parameter determines whether the message should be sent immediately or when the current transaction commits (using the sendTransacted() capability of the messaging subsystem sending services). The scope parameter determines whether to scope the action for the entire component or by message.


        <wc:Action name="CheckInventory" asynchronous="false"
scope="component">
                <wc:PreInvokeMediator
                       
mediatorImpl="com.ibm.commerce.foundation.services.invocation.internal.impl.JSPMessageInvocationMediatorImpl">
                        <wc:Property name="url"
                               
value="https://localhost:8002/webapp/wcs/admin/IBM.WC.Compose/mediation/SomeExternalApp/OagisToSomeExternalAppCheckInventory.jsp"
/>
                </wc:PreInvokeMediator>
                <wc:PostInvokeMediator
                       
mediatorImpl="com.ibm.commerce.foundation.services.invocation.internal.impl.JSPMessageInvocationMediatorImpl">
                        <wc:Property name="url"
                               
value="https://localhost:8002/webapp/wcs/admin/IBM.WC.Compose/mediation/SomeExternalApp/SomeExternalAppToOagisCheckInventory.jsp"
/>
                </wc:PostInvokeMediator>
        </wc:Action>
</wc:InvocationService>

The PreInvokeMediator and PostInvokeMediator are for cases where you are using point-to-point integration. In the case of a point-to-point solution where WebSphere Commerce and the external system support the same protocol, WebSphere Commerce has a local message mediation capability to transform the declared OAGIS style message to the message format of the external system. This local mediation uses a JSP to format the outbound OAGIS request into the message format of the external system and another JSP to convert the external system response into the expected OAGIS response. This local mediation is provided if you cannot use the message transformation capability that can be found in ESB middleware.

Enterprise service bus (ESB) is a pattern where systems can communicate using different message formats and it is up to the systems integrator to link the different systems together. There are third party middleware products, such as WebSphere ESB, that perform this mediation. These products can do more then just simple message mediation. They are also used for message routing and linking multiple system that different protocols together.