Transferring Binary Data as Attachments with MTOM

The performance of Web services is affected by the transfer of large quantities of binary data. The SOAP Message Transmission Optimization Mechanism (MTOM) is a mechanism for optimizing the performance in the transfer of binary data in Web services. In doing so, binary data is not sent base64-encoded in the SOAP message but as an attachment of the SOAP message. The MTOM recommended by W3C specifies that binary data is included as the content of an element of type xsd:base64binary.

Refer to https://www.w3.org/TR/2005/REC-soap12-mtom-20050125/

Sending Messages with Binary Attachments

You can send binary data with MTOM as attachments of SOAP messages.

For a Medium/Output Connector, sending takes place within the outgoing message.

For an Input Listener Connector which is deployed in the Metro-Framework and thus not running in compatibility mode, the response is only MTOM encoded if the Web Service consumer signals its MTOM support explicitly.

The Web Service consumer can signal its MTOM support explicitly by sending an MTOM request or by adding the entry application/xop+xml to the Accept HTTP header. If you call up a Web Services Input Listener Connector with a Web Services Medium/Output Connector and expect an MTOM-encoded response, you must activate the option Enable MTOM attachments for the outgoing response message in the Medium/Output Connector.

Refer to Extended Tab in the Web Service Editor

If the Web Service consumer did not signal its MTOM support explicitly, the attachment data is sent inline in the SOAP message.

For an Input Listener Connector, sending takes place as an output message within the response.

You define the actual data (e.g. graphics as jpeg or documents as pdf) as workflow variables and adjust the SOAP in such a way that it includes an element of type xmime:base64Binary with attribute xmime:contentType and the respective value (e.g. image/jpeg). In doing so, you also have to create a variable that specifies the element of the SOAP message for which the data is intended.

The elements of the SOAP message, the content of which is supposed to be sent using MTOM, must be filled with attribute xmime:contentType.

Prerequisites

Web services medium/output or input listener connector is created and configured.

Refer to Calling a Web Service
You have created a SOAP message for sending.

Refer to Calling a Web Service

Proceed as follows

In the module editor, choose the Web services medium/output or input listener connector that is supposed to send the binary data.
For the respective selected connector type, show the Extended tab and continue with the corresponding connector:
- For the medium/output connector
  1. In the Attachments/binary data area, choose the option Activate MTOM attachments for outgoing messages.
  2. Adjust your SOAP message so that the binary data to be sent is included in a message element (e.g. with the name imageData for graphic data) of type xmime:base64Binary and assign attribute xmime:contentType to this message element.
- For the input listener connector
  1. In the Attachments/binary data area, choose the option Activate MTOM attachments for response message.
  2. Display the XML Schemas tab.
  3. Choose the message element whose content you want to send as the attachment (e.g. imageData).
  4. To this element, assign type xmime:base64Binary. You do so by dragging it from the lower section of the editor from the complex types group, and dropping it onto the corresponding element in the message above.
    
    By doing so, you have assigned the required attribute xmime:contentType to the element at the same time.

Example for a SOAP message

Adjust the outbound SOAP message in such a way (e.g. in an XSLT Converter) that, in the corresponding message element, which is supposed to contain the MTOM data, for the xmime:contentType attribute, the correct content type is set (e.g. image/jpeg; if you are not sure, set application/octet-stream as a generic content type, e.g.:
```
<soapenv:Envelope xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
  <soapenv:Body>
    <operationA>
      <imageData xmime:contentType="image.jpeg/">
      </imageData>
      <pdfData xmime:contentType="application/pdf">
      </pdfData>
    </operationA>
  </soapenv:Body>
</soapenv:Envelope>
```
In the workflow, create the following variables for the data of the imageData element and the pdfData element and define their values:
- Variables for the data of the imageData element:
  
  Name Type Value
  
  WSAttachment.0
  
  xs:base64Binary
  
  image data
  
  WSAttachmentName.0
  
  xs:String
  
  imageData
  
  (corresponds to the name of the message element)
- Variables for the data of the pdfData element:
  
  Name Type Value
  
  WSAttachment.1
  
  xs:base64Binary
  
  PDF data
  
  WSAttachmentName.1
  
  xs:String
  
  pdfData
  
  (corresponds to the name of the message element)
  
  These variables contain the names of the message elements to be referenced and the actual data.
  
  Refer to
- Creating Mapping Rules for the Mapping of Variables
- Defining Variables

Name	Type	Value
WSAttachment.0	`xs:base64Binary`	image data
WSAttachmentName.0	`xs:String`	`imageData` (corresponds to the name of the message element)

Name	Type	Value
WSAttachment.1	`xs:base64Binary`	PDF data
WSAttachmentName.1	`xs:String`	`pdfData` (corresponds to the name of the message element)

You can use a File Connector for importing the binary data from a file. You place this connector before the Web services connector in the workflow. Then, use a variable mapping by assigning the binary data to a variable of type xs:base64Binary.

Receiving Messages with Binary Attachments

By default, the content of attachments is integrated directly into the receiving SOAP XML message as base64-encoded data and transferred to the workflow.

You can also extract the content of elements with binary data (e.g. the MTOM attachments) and set it as the content of workflow variables.

Prerequisites

Web services medium/output or input listener connector is created and configured.

Refer to Calling a Web Service

Proceed as follows

In the module editor, choose the Web services medium/output or input listener connector that receives binary contents or MTOM attachments.
For the respective selected connector type, show the Extended tab and continue with the corresponding connector:
- For the input listener connector
  
  In the Attachments/binary data area, choose the option Extract binary data from the input message and set it as variable values.
- For the medium/output connector
  
  In the Attachments/binary data area, choose the option Extract binary data from the response message and set it as variable values.

The incoming SOAP message is searched for elements with attribute xmime:contentType and their content is written to the following variables:

WSAttachmentName.[index]: Name of the message element
WSAttachment.[index]: (type :`xs:base64Binary`) data of the message element
WSAttachmentContent type.[index]: Content type of the data
WSAttachmentNumber: Total number of contents found

If the option Save attachments in the file system is active, variable WSAttachmentFileName.[index] is set instead of WSAttachment.[index]. Their content is the name of the file with the data.

In order to transfer the data read from the variables to the next module, you must perform a mapping, which maps the corresponding variables to the input message.