Web Services message protocol

Communities can use the Web Services message protocol to trade messages with partners. The Web Services framework enables you to send and receive SOAP messages with payloads:

  • In the SOAP body
  • In the SOAP header
  • In the SOAP header and body
  • Included as MIME attachments

The framework also supports WS-Security and WS-Addressing. Additionally, you can configure custom SOAP handlers to perform processing on SOAP messages. Possible processing operations include payload transformation, payload validation and WS header processing.

Architecturally, the Web Services framework passes messages through a chain of handlers. Each handler performs an action on a message. For example, for an inbound message the WS-Security handlers are responsible for decrypting and signature validation. For an outbound message, the WS-Security handlers are responsible for encryption and signature creation. Other handlers are responsible for other message actions. These actions are broken down into phases, with several pre-defined built-in phases such as pre-dispatch, dispatch, and so on. Each phase is a collection of handlers. Axis2 enables the user to choose the phases for the handlers, as well as the order of execution of handlers. You can also define handlers in a module that you plug into a running Axis2 system. One such module is Rampart, which provides an implementation of WS-Security.

Adding a transport in the delivery exchange wizard for the Web Services message protocol is just like setting up an HTTP exchange. For information see HTTP (embedded) trading configuration and HTTP (external) trading configuration.

Also see:

Payload packaging

The payload that is transported in a SOAP message can be located in the SOAP body, header, header and body, or packaged as a MIME attachment.

When packaging an outbound message, a decision must be made on where to place the payload. The packaging decision is specified as part your exchange agreement with your trading partner. By default outbound payloads are placed in the SOAP body of the packaged message. To specify that the payload should be packaged as an attachment, change the payload location field on the WebServices 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, you must configure a SOAP handler to attach the payload where desired. To do this you require the optional Interchange Software Development Kit.

To override the payload location collaboration setting in the user interface, set the metadata items named AxisShouldAddPayload and AxisAddPayloadAsAttachment.

  • AxisShouldAddPayload – Set the value to true to add the payload to the body or as an attachment. set the value to false to not automatically include the payload.
  • AxisAddPayloadAsAttachment – Set the value to true to package payloads as attachments. Set the value to false to package payloads as part of the SOAP body.

The SOAP body can only contain XML payloads. Package other payload types and large XML payloads as attachments.

Payload unpackaging

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

By default, Activator integrates payloads found in the SOAP body and integrates any MIME attachments. To disable the default SOAP body and attachment integration, use the Advanced tab of the Community Web Services delivery exchange modification page.

To override the payload integration values that you set on the Advanced tab, you can set override values for the AxisShouldIntegrateSoapBody and AxisShouldIntegrateAttachments message metadata attributes.

Message metadata

The following defines the message metadata elements.

  • AxisShouldAddPayload – Overrides 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 – Overrides the value of the "Payload location" field in the Collaboration settings screen of the user interface. Specifies whether to add the payload as an attachment or in the SOAP body.
  • AxisShouldIntegrateSoapBody – Overrides 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 – Overrides 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 Activator.
  • AxisToEndpointReference – Specifies the address of the Axis service to which inbound WebServices messages are directed for handling and processing.
  • SOAPAction – Specifies the SOAP action header value. If specified for outbound messages, the value is used when packaging. If no value is specified, SOAPAction defaults to handleMessage.
  • 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 handler

Activator uses Apache’s Axis2 implementation to handle the WS-Security for the SOAP messages. The Rampart module in Axis2 has WS-Security handlers to use for signing and encrypting SOAP messages and for validating signatures and decrypting.

The Rampart module supports signature and encryption operations on the SOAP envelope and Body. Axway added support for signature and encryption operations on SOAP attachments in the Rampart implementation. The Rampart module is defined under axis2.xml.

The collaboration settings area of the user interface allows configuration of signing and encryption parameters. See Web Services collaboration settings.

WS-Addressing handler

Activator uses the Apache Axis2 implementation to handle the WS-Addressing for SOAP message.

Activator provides two versions of the Axis2 file:

  • axis2.xml
  • This file has handlers for adding routing information to the SOAP header and interpreting routing information. If you want to use WS-addressing you must use this file.
  • axis2NoWSAddressing.xml
  • This file disables WS-Addressing. If you do not want to use WS-addressing, select this file.

To select the axis file version to use:

  • In client (consumer) mode – Go to the Web Services settings of the community collaboration settings. Then select the axis2.xml version in the Send handler config file field.
  • For more information, see Web Services collaboration settings.
  • In server (provider) mode – Go to the management page for the community Web Services pickup. Select the Advanced tab and then select the axis2.xml version in the Receive handler config file field.

Default configuration

The default configuration of the Web Services message protocol enables trading of secure XML payloads between two instances of Activator. The default configuration is useful to get two instances of Activator trading quickly. Typically, users will need to modify the default configuration. This requires the use of the optional Interchange Software Development Kit.

Default packaging configuration

Under the default configuration for packaging:

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

Default unpackaging configuration

Under the default configuration for unpackaging:

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

Related topics

Web Services transport user accounts

Web Services exchanges can optionally require user names and passwords in a UsernameToken element in the SOAP header. Within communities, you can specify different types of Web Services user accounts:

  • Community accounts are owned by communities. Any partner can use community accounts.
  • Partner accounts are owned by specific partners. Only the specified partner can use a partner account.

Related topics

Related Links