How to Receive and Send MIME SOAP Attachments for Web Services


This document describes how to receive and send MIME attachments when working with SOAP-based web services.

 

Overview

It is a common scenario to transmit attachments with SOAP messages. Boomi allows you to achieve this with the Web Services Server and Web Service SOAP Client connector. Let's familiarize ourselves with the general flow of the process for receiving and sending SOAP attachments:

  1. Receiving an attachment
    1. A Web Services Server is setup with a document cache in the operation
    2. A SOAP message that can include MIME attachments is sent to the Web Services Server
    3. The server receives the SOAP message with attachment
    4. The main SOAP body content is passed into the process as a normal document
    5. The attachment(s) are added it to the document cache and indexed by a dynamic document property named "WSS_ROOT_DOCUMENT_ID" with a unique, auto-generated ID value
    6. The SOAP body flows through the rest of the process
    7. The attachment can be retrieved by referencing the DDP "WSS_ROOT_DOCUMENT_ID" in the cache
  2. Sending an attachment
    1. The DDP "WSS_ROOT_DOCUMENT_ID" of your choosing is associated with the attachment(s)
    2. The attachment(s) is sent to a document cache
    3. The Web Services SOAP Client connector uses the same document cache above in the Web Services SOAP Client operation
    4. A SOAP body is sent to the SOAP client connector
    5. The connector sends the SOAP body and the attachments in the doc cache

For additional information, see the User Guide: Web services with multipart SOAP attachments.
 

Document Cache Configuration

The attachment cache field in the Web Services Server operation and in the Web Services SOAP Client operation are used for storing/retrieving the attachment. You need to create a cache with a single index and a document property key WSS_ROOT_DOCUMENT_ID as shown below.
Note: the Profile Type set is "None".


 

Common Scenarios

Scenario 1: Receiving Attachments with the Web Services Server

A good example of receiving an attachment would be a candidate applying for a job, where he fills his details and uploads his resume on a portal. On submitting this form, a SOAP request is sent to a Boomi web service, where the resume is retrieved and used later in an encoded format.

Here's how the process could be configured to receive a MIME type of attachment:



The web services server operation:
User-added image

The cache configuration in the process. The key value is going to be the DDP WSS_ROOT_DOCUMENT_ID that is automatically assigned. The key name will be the same name as the DDP used to retrieve the attachments, so that's why the parameter value looks like that.
User-added image

In branch 1, the retrieve from cache retrieves the attachment document, which is then base64 encoded and stored in a process property. Branch 2 uses the incoming data as well as the encoded data of the PDF resume and returns the response.

Note: This example assumes a single attachment is received on the request and therefore can store the attachment data in a Process Property.

For testing purpose, we will be using SOAP UI to send the candidate information and the resume. Import the WSDL which contains the deployed WSS process details. Remember to set Enable MTOM as true in custom properties of your SOAP UI project to send the attachment as a MIME.

The candidate data along with a Base64 encoded format of resume is present in the response.

Here's an example of the raw SOAP request that will work with the SOAP attachment retrieval:

--uuid:736d19fd-646c-40b5-afb3-640a2738de35
Content-Id: <rootpart*736d19fd-646c-40b5-afb3-640a2738de35@example.jaxws.sun.com>
Content-Type: application/xop+xml;charset=utf-8;type="text/xml"
Content-Transfer-Encoding: binary

<?xml version='1.0' encoding='UTF-8'?><ns1:Envelope xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"><ns1:Body>
   <ns2:testget xmlns:ns2="http://www.boomi.com/connector/wss">
     <element>
       <test>123</test>
     </element>
   </ns2:testget>
 </ns1:Body></ns1:Envelope>
--uuid:736d19fd-646c-40b5-afb3-640a2738de35
Content-Id: <testpdf>
Content-Type: application/binary; name="testpdf"
Content-Transfer-Encoding: binary

<<PDF_data>>
--uuid:736d19fd-646c-40b5-afb3-640a2738de35--
The above is a multipart request. Retrieving the attachment will not work if you put the attachment data into an element in the SOAP body. You can use the element like you normally would, but there would be no attachments. For example, this would not produce any attachments and the listener process would not pull anything from the cache: 
<?xml version='1.0' encoding='UTF-8'?><ns1:Envelope xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"><ns1:Body>
   <ns2:testget xmlns:ns2="http://www.boomi.com/connector/wss">
     <element>
       <pdf><<PDF_Data>></pdf>
     </element>
   </ns2:testget>
 </ns1:Body></ns1:Envelope>

 

Scenario 2: Sending Attachments with the Web Services SOAP Client Connector

Let's say you want to send an images of the product which are a part of tags in XML. The images are currently in base64 encoded format in the associated tags. While sending the product details and image to web server, we need to extract the images and send them to the web service as MIME SOAP Attachment.

The overall process:



The SOAP Operation with the Attachment Cache:
User-added image

The DDP WSS_ROOT_DOCUMENT_ID has been configured with some static value in the beginning of the process. It can be any value if it is one document or you can set some profile value (or unique value) if you have multiple.

User-added image

Note: the DDP WSS_ROOT_DOCUMENT_ID has to be defined before the branch so it can flow into the second branch and be used to pull the corresponding attachment in the doc cache. If you put it in the first branch only, the next branches will not be able to pull from the cache correctly since DDP's are not passed into different branches. 

The DDP WSS_ATTACHMENT_CONTENT_ID determines the content ID and Content-Type name to be used in the SOAP request as show below in the headers:

--uuid:736d19fd-646c-40b5-afb3-640a2738de35
Content-Id: <123>
Content-Type: application/binary; name="123"
Content-Transfer-Encoding: binary

<<PDF_Data>>
--uuid:736d19fd-646c-40b5-afb3-640a2738de35--
If you need to set those, you can do it through that DDP. This is optional, otherwise the process will choose a random content ID.

Branch 1 stores the attachment. In branch 2, the SOAP request body is created and sent while the attachments are loaded from the cache in the connector operation. Make sure the Web Services SOAP Client Operation has a doc cache in the "Attachment Cache" field.

 

Unsupported scenarios

Currently you cannot: