The external client

Outbound communication is performed using each service's external client.

The external client is bound to either JCA binding to use WebSphere Commerce routing or to an ESB to leverage more advanced routing and mediation features. The JCA binding is used by default, as it enables messages with different actions to be wired to different endpoints. For example, a transfer order message can be sent to a backend system, while an approve order message can be sent to a workflow engine.

Configuration of the external client

An external client's configuration is found in the following location:

WC\xml\config\ServiceName.external
For example, the external Order client's configuration is found under the com.ibm.commerce.order.external directory.

This directory should contain a wc-component-client.xml file that indicates the binding method used to perform external requests.

For external clients, the recommended binding is JCAInvocationBinding, which uses the WC messaging system and the JCAHttp Web Service adapter or the JCAJMS Web Service adapter to send requests.

Using an external client

The following sample steps outline using an external client:
  1. Write code to make a request using the external client. For example:
    
// Create the project noun.
ProjectType project = ProjectFactory.eINSTANCE.createProjectType();
ProjectIdentifierType projectIdentifier = ProjectFactory.eINSTANCE.createProjectIdentifierType();
projectIdentifier.setUniqueID("theProjectID");
project.setProjectIdentifier(projectIdentifier);

// Create the process action expression.
String expression = ProjectFacadeConstants.XPATH_PROJECT + "1" + ProjectFacadeConstants.CLOSE_XPATH;
List<ActionExpressionType> actionExpressions = new ArrayList();
actionExpressions.add(ExternalProjectFacadeClient.createActionExpression("Transfer", SelectionCriteriaHelper.STR_XPATH_LANG, expression));

// Create the process BOD.
ProcessProjectType processProject = ProjectFactory.eINSTANCE.createProcessProjectType();
ProcessProjectDataAreaType projectDataArea = ProjectFactory.eINSTANCE.createProcessProjectDataAreaType();

// Populate the process verb.
projectDataArea.setProcess(ExternalProjectFacadeClient.createProcessVerb(actionExpressions));

// Populate the project noun.
projectDataArea.getProject().add(project);

// Send the external project request.
ExternalProjectFacadeClient externalProjectClient = new ExternalProjectFacadeClient();
AcknowledgeProjectType acknowledgeProcess = externalProjectClient.processProject(processProject);
  2. Configure the external client to use JCA Binding. For example:
    1. Create a configuration directory for the external client. For example, \xml\config\com.mycompany.commerce.project.external.
    2. Create a wc-component-client.xml file in the directory configured for JCA Binding. For example:
      
<_config:DevelopmentClientConfiguration xmlns:_config="http://www.ibm.com/xmlns/prod/commerce/foundation/config"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation/config ../xsd/wc-component-client.xsd">
	<_config:invocationservice>
	
		<_config:invocationbinding
				bindingImpl="com.ibm.commerce.foundation.internal.client.services.invocation.impl.JCAInvocationBindingImpl">
		</_config:invocationbinding>
		
	</_config:invocationservice>	
</_config:DevelopmentClientConfiguration>
  3. Configure the transport and destination within the WC messaging system. For example:
    1. Add a new message type for the external service requests (SQL).
      The following example creates a com.mycompany.commerce.project.external message type:
      • Connect to the database.
      • Run the following query: 
        
insert into msgtypes (msgtype_id, msgtdir, name, viewname, description) values (1010, 1, 'com.mycompany.commerce.project.external', ' ', 'External Project Service');
    2. Configure the transport and destination for the new message type.
      Note: The HTTP Web Service adapter must be enabled.
      1. Open the Administration Console.
      2. Select Configuration > Message Types.
      3. Click New.
      4. Select the new message type. For example, com.mycompany.commerce.project.external.

        Transport: WebServices(HTTP)

        Device format: WebServices

      5. Click Next.
      6. Add the destination URL and username and password if needed.
      7. Click Finish.
  4. The following is a sample Outbound Request from WC, using the code snippet from step 1:
    
<myprj:ProcessProject releaseID="9.0" versionID="7.0.0.0" 
 xmlns:_wcf="http://www.ibm.com/xmlns/prod/commerce/9/foundation" 
 xmlns:myprj="http://www.mycompany.com/xmlns/prod/commerce/9/project" 
 xmlns:oa="http://www.openapplications.org/oagis/9" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <oa:ApplicationArea xsi:type="_wcf:ApplicationAreaType">
    <oa:CreationDateTime>2009-10-23T20:07:15.156Z</oa:CreationDateTime>
    <oa:BODID>a8688c80-c00f-11de-b7b8-829b4ae20b43</oa:BODID>
    <_wcf:BusinessContext/>
  </oa:ApplicationArea>
  <myprj:DataArea>
    <oa:Process>
      <oa:ActionCriteria>
        <oa:ActionExpression actionCode="Transfer" expressionLanguage="_wcf:XPath">/Project[1]</oa:ActionExpression>
      </oa:ActionCriteria>
    </oa:Process>
    <myprj:Project>
      <myprj:ProjectIdentifier>
        <myprj:UniqueID>theProjectID</myprj:UniqueID>
      </myprj:ProjectIdentifier>
    </myprj:Project>
  </myprj:DataArea>
</myprj:ProcessProject>