This topic applies only to the IBM Business Process Manager Advanced configuration.

Referenced attachments: top-level message parts

You can send and receive SOAP messages that include binary attachments that are declared as parts in your service interface.

In a MIME multipart SOAP message, the SOAP body is the first part of the message, and the attachment or attachments are in subsequent parts.

What is the advantage of sending or receiving a referenced attachment in a SOAP message? The binary data that makes up the attachment (which is often quite large) is held separately from the SOAP message body so that it does not need to be parsed as XML. This results in more efficient processing than if the binary data were held within an XML element.

Types of SOAP messages with referenced attachments

Beginning with Version 7.0.0.3 of IBM® Integration Designer, you have a choice about how the SOAP message is generated:

WS-I-compliant messages
The runtime can generate SOAP messages that comply with the WS-I Attachments Profile Version 1.0 and the WS-I Basic Profile Version 1.1. In a SOAP message that is compliant with these profiles, only one message part is bound to the SOAP body; for those that are bound as attachments, the content-id part encoding (as described in the WS-I Attachments Profile Version 1.0) is used to relate the attachment to the message part.
Non-WS-I-compliant messages
The runtime can generate SOAP messages that do not comply with the WS-I profiles but that are compatible with the messages generated in Version 7.0 or 7.0.0.2 of IBM Integration Designer. The SOAP messages use top-level elements named after the message part with an href attribute that holds the attachment content-id, but the content-id part encoding (as described in the WS-I Attachments Profile Version 1.0) is not used.

Selecting WS-I compliance for web service exports

You use Integration Designer to configure an export binding. You create a module and its associated interface and operations. You then create a web service (JAX-WS) binding. The Referenced attachments page displays all the binary parts from the created operation, and you select which parts will be attachments. You then specify, on the Specify the WS-I AP 1.0 compliance page of Integration Designer, one of the following choices:

Use WS-I AP 1.0 compliant SOAP message
If you select this option, you also specify which message part should be bound to the SOAP body.
Note: This option can be used only when the corresponding WSDL file is also WS-I compliant.
A WSDL file that is generated by Integration Designer Version 7.0.0.3 is compliant with WS-I. However, if you import a WSDL file that is not compliant with WS-I, you cannot select this option.
Use non WS-I AP 1.0 compliant SOAP message
If you select this option, which is the default, the first message part is bound to the SOAP body.

Note: Only top-level message parts (that is, elements defined in the WSDL portType as parts within the input or output message) that have a binary type (either base64Binary or hexBinary) can be sent or received as referenced attachments.

See the "Working with attachments" topic in the Integration Designer information center for more detailed information.

For WS-I-compliant messages, the content-ID that is generated in the SOAP message is a concatenation of the following elements:

The value of the name attribute of the wsdl:part element referenced by the mime:content
The character =
A globally unique value, such as a UUID
The character @
A valid domain name

Inbound processing of referenced attachments

When a client passes a SOAP message with an attachment to a Service Component Architecture (SCA) component, the web service (JAX-WS) export binding first removes the attachment. It then parses the SOAP part of the message and creates a business object. Finally, the binding sets the attachment binary in the business object.

Figure 1. How the web service (JAX-WS) export binding processes a WS-I compliant SOAP message with a referenced attachment

Illustration of a SOAP message with a referenced attachment converted to a business object that includes the attachment.

Accessing attachment metadata in a mediation flow component

As shown in Figure 1, when referenced attachments are accessed by components, the attachment data appears as a byte array.

Each referenced attachment of a SOAP message also has a corresponding attachments element in the SMO. The attachments element includes the attachment content type and the path to the message body element where the attachment is held.

Figure 2. How referenced attachments appear in the SMO

Illustration of how the attachment data is represented in the SMO.

Important: The path to the message body element is not automatically updated if the message is transformed and the attachment moved. You can use a mediation flow to update the attachments element with the new path (for example, as part of the transform or using a separate message element setter).

For details about the structure of the SMO, see the information in "Related topics".

How outbound SOAP messages are constructed

You use Integration Designer to configure a web service (JAX-WS) import binding to invoke an external web service. The import binding is configured with a WSDL document that describes the web service to be invoked and defines which message parts should be passed as attachments. You can also indicate, on the Specify the WS-I AP 1.0 compliance page of Integration Designer, one of the following choices:

Use WS-I AP 1.0 compliant SOAP message
If you select this option, you also specify which message part should be bound to the SOAP body; all others are bound to attachments or headers. Messages sent by the binding do not include elements in the SOAP body that refer to the attachments; the relationship is expressed by way of the attachment content ID including the message part name.
Use non WS-I AP 1.0 compliant SOAP message
If you select this option, which is the default, the first message part is bound to the SOAP body; all others are bound to attachments or headers. Messages sent by the binding include one or more elements in the SOAP body that refer to the attachments by way of an href attribute.

Note: The part that represents an attachment, as defined in the WSDL, must be a simple type (either base64Binary or hexBinary). If a part is defined by a complexType, that part cannot be bound as an attachment.

Outbound processing of referenced attachments

The import binding uses information in the SMO to determine how the binary top-level message parts are sent as attachments.

Figure 3. How the referenced attachment in the SMO is accessed to create the SOAP message

Illustration of a referenced attachment in an SMO and how it relates to the outgoing SOAP message

The attachments element is present in the SMO only if a mediation flow component is connected directly to the import or export; it does not get passed across other component types. If the values are needed in a module that contains other component types, a mediation flow component should be used to copy the values into a location where they can then be accessed in the module, and another mediation flow component used to set the correct values before an outbound invocation by way of a web service import.

The binding uses a combination of the following conditions to determine how (or whether) the message is sent:

Whether there is a WSDL MIME binding for the top-level binary message part and, if so, how the content type is defined
Whether there is an attachments element in the SMO whose bodyPath value references a top-level binary part

How attachments are created when an `attachment` element exists in the SMO

The following table shows how an attachment is created and sent if the SMO contains an attachment element with a bodyPath that matches a message name part:

Table 1. How the attachment is generated
Status of WSDL MIME binding for top-level binary message part	How message is created and sent
Present with one of the following: No defined content type for the message part Multiple content types defined Wildcard content type defined	Message part is sent as an attachment. `Content-Id` is set to the value in the attachments element if present; otherwise, one is generated. `Content-Type` is set to the value in the attachments element if present; otherwise, it is set to `application/octet-stream`.
Present with single, non-wildcard content for the message part	Message part is sent as an attachment. `Content-Id` is set to the value in the attachments element if present; otherwise, one is generated. `Content-Type` is set to the value in the attachments element if present; otherwise, it is set to the type defined in the WSDL MIME content element.
Not present	Message part is sent as an attachment. `Content-Id` is set to the value in the attachments element if present; otherwise, one is generated. `Content-Type` is set to the value in the attachments element if present; otherwise, it is set to `application/octet-stream`. Note: Sending message parts as attachments when not defined as such in the WSDL may break compliance with the WS-I Attachments Profile 1.0 and so should be avoided if possible.

How attachments are created when no `attachment` element exists in the SMO

The following table shows how an attachment is created and sent if the SMO does not contain an attachment element with a bodyPath that matches a message name part:

Table 2. How the attachment is generated
Status of WSDL MIME binding for top-level binary message part	How message is created and sent
Present with one of the following: No defined content type for the message part Multiple content types defined Wildcard content type defined	Message part is sent as an attachment. `Content-Id` is generated. `Content-Type` is set to `application/octet-stream`.
Present with single, non-wildcard content for the message part	Message part is sent as an attachment. `Content-Id` is generated. `Content-Type` is set to the type defined in the WSDL MIME content element.
Not present	Message part is not sent as an attachment.

Important: As described in "XML representation of SMO," the Mapping mediation primitive transforms messages using an XSLT 1.0 transformation. The transformation operates on an XML serialization of the SMO. The Mapping mediation primitive allows the root of the serialization to be specified, and the root element of the XML document reflects this root.

When you are sending SOAP messages with attachments, the root element you choose determines how attachments are propagated.

If you use "/body" as the root of the XML map, all attachments are propagated across the map by default.
If you use "/" as the root of the map, you can control the propagation of attachments.