Web services message protocol

The B2Bi trading engine web services framework allows for the sending and receiving of SOAP messages with payloads in the SOAP body or as MIME attachments. Included is support for WS-Security and WS-Addressing. In addition, custom SOAP handlers can be configured to perform processing on the SOAP messages. Possible processing operations are payload transformation, payload validation, WS* header processing, compression, and so on.

Architecturally, the web services framework is designed to pass messages through a chain of handlers. Each handler is responsible for one operation on a message. For example, WS-Security is implemented as a handler. For an inbound message, the WS-Security handler is responsible for decrypting and signature validation. For an outbound message, the WS-Security handler is responsible for encryption and signature creation. Other handlers are responsible for other message operations. The handlers, which can be defined in a module, are run in order of configuration. Handlers are executed within a phase.

Concepts:

Global configuration file

Global configuration settings can be modified for each community in the B2Bi user interface in Trading configuration > Show collaboration settings. If you want to perform more advanced configuration than this, you can do so through the global configuration file. The global configuration file defines how SOAP messages are packed and unpacked. The default file, axis2.xml, is located in <install directory>/conf. In addition, the axis2_sample.xml sample file is available in the te_sample.zip folder that is packaged with this guide.

The collaboration setting axis2.xml file is used when sending a WS BP packaged message outbound to a partner delivery exchange. The trading pickup axis2 file is used when receiving an inbound WS BP message to a trading pickup. As settings modifications are made, the new axis2 files are created, stored, registered, and then configured.

If you use a custom axis2 file with code that replaces the default implementation code, or if you add classes that perform additional WS processing, you must also copy the JAR file or the classes referred to in the modified axis2 file into the trading engineB2Bi node classpath.

The following describes elements in the global configuration file:

parameter

The parameter is a name-value pair. Each top-level parameter in axis2.xml corresponds to axis configuration properties.

transportSender

This is the registered transport sender in the system. It is used during runtime to send the messages.

module

A top-level module element engages a module system wide.

phaseOrder

This specifies the order of phases in the execution chain.

phase

This defines the phases. It is the only element allowed within phaseOrder. A phase is defined for inbound and outbound messages.

After the settings are modified, perform these additional steps:

  • Add each axis2 file you define to the file registry. This makes it available to the web services protocol sender and receiver. The file registry is filereg.xml at <install directory>/conf.
  • Copy each of your axis2 files to the conf directory.
  • Copy the JAR file and the classes referred to in the modified axis2 file into the trading engineB2Bi node classpath.

The appropriate axis2 file to use is passed to the web services protocol sender as part of the binary collaboration. The default axis2.xml file is used for packing and unpacking a message, unless a user-defined file is specified.

The following are methods to use to specify user-defined axis2 files for outbound and inbound messages. Regardless how the axis2 file is specified, the value must be a file name that has been registered in the file registry.

Outbound

Ways to specify user-defined axis2 files for outbound messages:

  • Enter the name of the axis2 file in the Send handler config file field on the Web services tab in the Collaboration settings area of the user interface.
  • Set the message metadata attribute AxisHandlerConfigWSDD on a per-message basis to override the value set in the collaboration settings area of the user interface. See MMD from integration.

Inbound

Ways to specify user-defined axis2 files for inbound messages:

  • On the maintenance page for a community web services exchange for receiving messages from partners. In the user interface, open the maintenance page for the exchange and click the Advanced tab. Enter the file name in the Receive handler config file field.
  • Set the message metadata attribute AxisHandlerConfigWSDD on a per-message basis to override the value set on the delivery exchange.

Regardless how the axis2 file is specified, the value must be a file name that has been registered in the file registry.

Service configuration

The service is described in a services.xml file. In order to be valid, each service archive file must have services.xml. Each file must be available in the META-INF directory of the archive file. When compiled, the archive file testhandler.aar is generated.

The following figure illustrates the example services.xml file in the SDK at sdk/java-src/examples/webservices/tradingenginenodeservices/Axis2TestServices/META-INF.

The class TestService.java under Axis2TestServices defines the service it provides.

<service name="TestService">
  <description>
   This service supports unpackaging messages received by the
   Interchange Web Services Business Protocol
  </description>
  <module ref="testmodule"/>
  <parameter name="ServiceClass" locked="false">
   examples.webservices.tradingenginenodeservices.Axis2TestServices.
   TestService</parameter>
  <operation name="handleMessage">
   <messageReceiver class="org.apache.axis2.receivers.
   RawXMLINOnlyMessageReceiver"/>
 </operation>
</service>

The following describes elements in the file.

service name

The name of the archive file.

description

A description of the service. Optional.

parameter

The required ServiceClass attribute specified within the parameter is loaded by MessageReceiver and performs the work in services.xml.

Services.xml can have any number of top-level parameters, and all the specified parameters are transformed into service properties in the corresponding ServiceDescrption.

operation

Specifies the operations exposed by the service. The required name attribute is the name of the operation. A custom message receiver can be registered per operation. The registered message receiver is the receiver for the corresponding operation. If not specified, the default message receiver is used.

Module configuration

The module is described in a module.xml file. Each module archive file must have a module.xml file in the META-INF directory of the archive file.

The following example illustrates a module.xml file.

The example module.xml file is in the SDK at sdk/java-src/examples/webservices/tradingenginenodeservices/Axis2TestModule/META-INF.

<module name="testmodule" class="examples.webservices.
  tradingenginenodeservices.Axis2TestModule.TestModule">
  <InFlow>
   <handler name="InFlowTestHandler" class="examples.
    webservices.tradingenginenodeservices.Axis2TestModule.
    TestReceiverHandler">
    <order phase="testmodulePhase"/>
   </handler>
  </InFlow>

  <OutFlow>
   <handler name="OutFlowTestHandler" class="examples.
    services.tradingenginenodeservices.Axis2TestModule.
    TestSenderHandler">
    <order phase="testmodulePhase"/>
   </handler>
  </OutFlow>
</module>

The following describes elements in the file.

class

The module implementation class.

InFlow and OutFlow

The handlers in a module are defined inside flows, which process inbound and outbound messages.

handler

Attributes for this element are:

name – Name of the handler.

class – Handler implementation class.

phase – The phase where the handler should be in the execution chain.

A sample module is in the SDK at sdk/java-src/examples/webservices/tradingenginenodeservices/Axis2TestModule. The following files are included:

  • ExampleHandlerException.java – Common exception class for send and receive code.
  • TestReceiveHandler.java – Parses SOAP header for IntegrationId and copies the value to the Interchange Inline Message Object as metadata.
  • TestSendHandler.java – Copies IntegrationId value from the Interchange Inline Message Object and places the value into the SOAP header.
  • TestModule – Starts and stops the module.
  • module.xml – Defines the handlers for processing inbound and outbound messages.

Payload packing

The payload transferred in a SOAP message can be in the SOAP body or packaged as a MIME attachment.

When packing an outbound message, you must decide where to place the payload. The packing decision is specified as part of the binary collaboration. By default, outbound payloads are placed in the SOAP body of the packaged message. Also, the payload can be packaged as an attachment by changing the payload location field on the web services tab in the collaboration settings area of the user interface. Setting the payload location to none has the effect of not attaching the payload as an attachment or in the SOAP body. In the none case, a SOAP handler must be configured to attach the payload where desired.

The payload location collaboration setting in the user interface can be overridden by setting the metadata items named AxisShouldAddPayload and AxisAddPayloadAsAttachment.

For AxisShouldAddPayload, the value should be true to add the payload to the body or as an attachment and false to not automatically include the payload.

The AxisAddPayloadAsAttachment value should be true to package payloads as attachments. The value should be false to package payloads as part of the SOAP body.

The SOAP body can only contain XML payloads. Other payload types and large XML payloads should be packaged as attachments.

Payload unpacking

An inbound SOAP message can have payloads in the SOAP body or as attachments.

The default behavior is to integrate payloads found in the SOAP body and integrate any MIME attachments. The Advanced tab for the web services delivery exchange for a community allows for SOAP body and attachment integration to be disabled. Also, the AxisShouldIntegrateSoapBody and AxisShouldIntegrateAttachments message metadata values can be set to override the values on the Advanced tab.

Message metadata

The following defines the message metadata elements.

AxisHandlerConfigWSDD

Can be used to override the value for the Send handler config file field in the collaboration settings area of the user interface. It also can be used to override the value for the Receive handler config file field on the Advanced tab of the maintenance page for a community web services delivery exchange. The value must correspond to a file that is configured within the file registry.

AxisShouldAddPayload

Can be used to override the value of the payload location field in the collaboration settings area of the user interface. Specifies whether to automatically add the payload to an outbound SOAP message. A value of false indicates the payload should not be added to the SOAP message. AxisAddPayloadAsAttachment specifies the location to add the payload if AxisShouldAddPayload is true.

AxisAddPayloadAsAttachment

Can be used to override the value of the payload location field in the collaboration settings area of the user interface. Specifies whether to add the payload as an attachment or in the SOAP body.

AxisShouldIntegrateSoapBody

Can be used to override the integrate SOAP body setting on the Advanced tab of the maintenance page for a community web services delivery exchange. Specifies whether to integrate the contents of the SOAP body.

AxisShouldIntegrateAttachments

Can be used to override the integrate attachments setting on the Advanced tab of the maintenance page for a community web services delivery exchange. Specifies whether to integrate the attachments of the SOAP message. The value defaults to true.

AxisMessageType

Specifies whether a message is a request or a response. This is set by the trading engineB2Bi.

AxisToEndpointReference

The address of the Axis service to which inbound web service messages are directed for handling and processing.

SOAPAction

The SOAP action header value. If specified for outbound messages, the value is used when packaging. If no value is specified, SOAPAction defaults to handlerMessage.

SOAPVersion

Specifies whether the trading engine, acting as a web service client, needs to use SOAP 1.1 or SOAP 1.2 to trade with a remote trading partner.

ws.IsSyncResponse

Indicates whether the message is a synchronous response. Set to true on outbound synchronous responses generated in the back end.

ConnectionId

The internal unique identifier of the bundled HTTP server connection through which to send synchronous responses. Must be set on outbound synchronous responses.

ValidateBodyXML

Specifies whether XML payloads should be schema-validated before adding the payload to the SOAP body of an outbound message. A value of true enables validation. Validation is false by default.

WS-Security and WS-Addressing handlers

The Rampart and Addressing modules handle the security and addressing details of the SOAP messages in axis2. They are loaded by default, but can be removed from axis2.xml if not needed. Removing the Rampart module results in not applying the security parameters. If the Addressing module is removed, you must define some handlers that can retrieve the sender and receiver routing IDs.

Encryption and signature parameters

The collaboration settings area of the user interface allows for configuration of signing and encryption parameters. The following describes the parameters.

Encryption

  • Encrypt message (on or off master switch)
  • Encryption algorithm (only Triple DES and AES supported)
  • Encrypt attachments (on or off)
  • Encrypt SOAP body (on or off)
  • XPaths to encrypt (allows configuration of specific SOAP envelope elements and sub-elements to be encrypted)
  • ID refs to encrypt (allows configuration of specific SOAP envelope elements and sub-elements to be encrypted).

Signature

  • Sign messages (on or off master switch; SHA1 is used when signatures are enabled)
  • Sign attachments (on or off)
  • Sign SOAP body (on or off)
  • XPaths to sign (allows configuration of specific SOAP envelope elements and sub-elements to be signed)
  • ID refs to sign (allows configuration of specific SOAP envelope elements and sub-elements to be signed).

The following links are for information about WS-Security.

Web Services Security: SOAP Message Security 1.0

Web Services Security SOAP Messages with Attachments (SwA) Profile 1.0

Web Services Security X.509 Certificate Token Profile

XML-Signature Syntax and Processing

XML Encryption Requirements

XML Encryption Core

The following link is for information about WS-Addressing:

Default configuration

The default configuration of the web services message protocol enables trading of secure XML payloads between two instances of The B2Bi trading engine. The default configuration is somewhat arbitrary, but useful to get two instances of The B2Bi trading engine trading quickly. However, most users probably will want a different configuration.

Default packing configuration

Under the default configuration for packing:

  • Payload is placed in the SOAP body.
  • WS-Security is enabled. The SOAP body is signed and encrypted.
  • SOAP action value is handlerMessage.
  • WS-Addressing header is added. Included are the sender and receiver routing IDs and a message ID.

Default unpacking configuration

Under the default configuration for unpacking:

  • SOAP body contents are integrated.
  • Attachments are integrated.
  • Synchronous acknowledgements are not enabled, so a 204 HTTP response is sent immediately on completion of unpacking.
  • WS-Addressing header is expected. Sender and receiver routing IDs and message ID are expected.

Synchronous responses

The web services message protocol supports synchronous business responses, but does not support the concept of business protocol-level message acknowledgements. The trading engineB2Bi can be configured to hold open inbound HTTP connections. This is so that either the backend can generate the payload to be included in a synchronous response or the response can be generated within the trading engine.

Backend generates synchronous response

An option must be selected in The B2Bi trading engine user interface to indicate the back-end system generates synchronous responses. The option is labeled "Synchronous response generated in backend". It is located on the Advanced tab of the maintenance page for a community’s web services message protocol delivery exchange. See the The B2Bi trading engine Administrator Guide for information about the option.

You must create an MMD for the trading engineB2Bi to pick up from integration. When the back-end system drops off the response payload, the ws.IsSyncResponse and ConnectionId metadata items must be set on the message. The ws.IsSyncResponse element must be set to true. ConnectionId must be set to the ConnectionId value of the inbound message. These two metadata items tell the trading engineB2Bi the message is a response and to send the response message back over the open HTTP connection.

Because it is a response message, make sure the SOAPAction is not set.

Remove any custom service from the repository that builds responses within the trading engineB2Bi.

<?xml version="1.0" encoding="UTF-8"?>
  <MessageMetadataDocument documentId="MMD123456789"
   protocol="webservices" protocolVersion="1.0">
    <Metadata name="From" type="string">SCBCASHWS</Metadata>
    <Metadata name="To" type="string">test</Metadata>
    <Metadata name="MessageID" type="string">ID1234567@ws.com
    </Metadata>
    <Metadata name="ws.IsSyncResponse">true</Metadata>
    <Metadata name="ConnectionId">http12682547197800
    </Metadata>
    <Metadata name="ValidateBodyXML">false</Metadata>
    <MessagePayloads>
    <Payload id="Attach001" packagingLocation="Attachment">
      <RemovePayloadAfterProcessing>false
      </RemovePayloadAfterProcessing>
    <MimeContentId>textDocument001</MimeContentId>
    <MimeContentType>text/plain</MimeContentType>
    <Location type="filePath">c:/payload/mmds/response.txt
    </Location>
    </Payload>
    </MessagePayloads>
   </MessageMetadataDocument>

the trading engine B2Bi generates synchronous response

When the UI check box described in the preceding topic (Synchronous response generated in backend) is not selected, The B2Bi trading engine generates the synchronous response.

A custom Axis service — ExchangeResponseService.aar — creates and builds the response. The service extends the message receiver InterchangeRawXmlInOutMessageReceiver, which is defined within The B2Bi trading engine. It receives the original message and helps in handling and sending the response built by the custom service.

As a new service is being defined, the SOAP action on the messages sent to this service should refer to responseMessage. The delivery exchange point on the receiving side should direct incoming messages to the new service, http://localhost/axis2/services/ExchangeResponseService/responseMessage.

The attribute AxisToEndpointReferencecan refer to the new service. Read WebservicesReadme.txt in the root SDK directory for more details.

<service name="ExchangeResponseService">
 <description> This service supports packaging responses
  within Interchange</description>
 <parameter name="ServiceClass" locked="false"> com.axway.
  webservices.protocols.ws2.services.ExchangeResponseService
 </parameter>
 <operation name="responseMessage">
  <messageReceiver class="com.cyclonecommerce.webservices.
   protocols.ws2.axis2.packaging.
   InterchangeRawXMLInOutMessageReceiver"/>
 </operation>
</service>

Message metadata documents

the trading engine B2Bi supports message metadata documents (MMDs) when file system integration is used with the web services message protocol. These XML documents are the interface between the trading engineB2Bi and the back-end system.

There are two types of MMDs:

  1. An MMD generated by a back-end system and retrieved from an integration pickup exchange. The MMD provides the location of a payload for the trading engineB2Bi to pick up, package and send to a partner via the web services message protocol. The MMD also provides information the trading engineB2Bi uses to process the outbound message.
  2. An MMD the trading engine generates and sends to the backend via an integration delivery exchange. The MMD contains information about a payload received from a partner via the web services message protocol. To trigger the trading engineB2Bi to generate an MMD, you must set up a file system with a message metadata integration delivery exchange for your community.

The following topics describe each type of MMD.

MMD from integration

The following is an example of an MMD from integration. The back-end system must generate an outbound MMD.

<?xml version="1.0" encoding="UTF-8"?>
<MessageMetadataDocument documentId="ID1234567890" protocol=
 "webservices" protocolVersion="1.0">
 <Metadata name="From" type="string">Axway</Metadata>
 <Metadata name="To" type="string">IBM</Metadata>
 <Metadata name="MessageID" type="string">ID1234567@ws.com
 </Metadata>
 <Metadata name="AxisHandlerConfigWsdd">axis2.xml
 </Metadata>
 <Metadata name="ValidateBodyXML">false</Metadata>
 <MessagePayloads>
 <Payload id="0784247" packagingLocation="Attachment">
  <RemovePayloadAfterProcessing>false
  </RemovePayloadAfterProcessing>
  <MimeContentId>smallXmlPo</MimeContentId>
  <MimeContentType>application/xml</MimeContentType>
  <Location type="filePath">test/data/xml/smallxmlPo.xml
  </Location>
 </Payload>
 <Payload id="0784248" packagingLocation="SOAPBody">
  <RemovePayloadAfterProcessing>false
  </RemovePayloadAfterProcessing>
  <MimeContentId>smallXmlPo1</MimeContentId>
  <MimeContentType>application/xml</MimeContentType>
  <Location type="filePath">test/data/xml/smallxmlPO1.xml
  </Location>
 </Payload>
</MessagePayloads>
</MessageMetadataDocument>

The following describes the MMD:

protocol and protocolVersion

These attributes of MessageMetadataDocument element should be set to webServices and 1.0, respectively. Required.

From

This metadata item is the routing ID of the sending party. Required.

To

This metadata item is the routing ID of the receiving party. Required.

MessageId

This metadata item is a unique identifier for a message that conforms to . Optional.

AxisHandlerConfigWsdd

This metadata item specifies a Web Service Deployment Descriptor file. An axis2 file defines the SOAP handlers for the trading engine to invoke when packing or unpacking SOAP messages. Optional.

ws.IsSyncResponse

Indicates whether the message is a synchronous response. Optional. Set to true on outbound synchronous responses generated in the back end.

ConnectionId

This metadata item specifies a unique identifier of the embedded HTTP server connection through which to send a synchronous response after receiving a message from a partner. Optional.

SOAPAction

This metadata item specifies the SOAP action header value. If specified for an outbound message, the value is used when packaging. If no value is specified, SOAPAction defaults to a blank string. Optional.

ValidateBodyXML

This metadata item specifies whether XML payloads should be schema-validated before adding the payload to the SOAP body of an outbound message. A value of true enables validation. Validation is false by default. Optional.

packagingLocation

This optional attribute of the MessagePayloads element has the following valid values:

  • SOAPBody
  • Attachment
  • None

Only one payload can be attached to the SOAPBody, and only one SOAPBody value is allowed if multiple payloads are associated with the MMD.

The packagingLocation attribute replaces the attributes AxisShouldAddPayload and AxisAddPayloadAsAttachment, which should not be used in a web service MMD.

MMD to integration

The following is an example of an MMD to integration. The trading engineB2Bi generates an inbound MMD. After receiving a SOAP message from a partner, the trading engineB2Bi unpacks the payload into a separate file.

<?xml version="1.0" encoding="UTF-8"?>
 <MessageMetadataDocument
  id="ID124305781171657816783pnuechterlein-nc8430"
  protocol="webservices" protocolVersion="1.0">
  <Metadata name="From">g</Metadata>
  <Metadata name="To">nc8430</Metadata>
  <Metadata name="MessageID">
   uuid:M1171657803697.4819@pnuechterlein-g_
   te5226705375118153788</Metadata>
  <Metadata name="AxisMessageType">request</Metadata>
 </MessageMetadataDocument>

The following describes the MMD:

protocol and protocolVersion

These attributes of MessageMetadataDocument element should be set to webServices and 1.0, respectively.

From

This metadata item is the routing ID of the sending party.

To

This metadata item is the routing ID of the receiving party.

MessageId

This metadata item is a unique identifier for a message that conforms to , if not empty.

SOAPAction

This metadata item specifies the SOAP action header value, if not empty.

AxisMessageType

This metadata item specifies whether a message is a request or a response.

ConnectionId

If a synchronous business response is expected, this metadata item specifies an internal unique identifier of the embedded HTTP server connection.

MessagePayloads

Attributes of this element identify the type of message and its delivery location.

Related topic

Related Links