This document describes how to receive and send MIME attachments when working with SOAP-based web services.
It is a common scenario to transmit attachments with SOAP messages. Boomi allows you to achieve this with the help of Web Services Server and Web Service SOAP Client connectors. Let's familiarize ourselves with the general concepts of the flows for receiving and sending SOAP attachments.
- Receiving an attachment - If you wish to publish a web service process to receive SOAP messages that can include MIME attachments, you specify a Document Cache in the Web Services Server operation component. When the server receives a SOAP message, it passes the main SOAP body content into the process as the normal document. It takes the attachment(s) and adds it to the Document Cache, indexed by a dynamic document property named "WSS_ROOT_DOCUMENT_ID" with a unique, auto-generated ID value.
- Sending an attachment - If you wish to send a SOAP message that includes MIME attachments using the Web Services SOAP Client connector, you specify a Document Cache in the Web Services SOAP Client operation. Prior to the connector shape, you add the attachments to the Document Cache, indexed by a dynamic document property named "WSS_ROOT_DOCUMENT_ID" with a unique value of your choosing. The Web Service SOAP Client shape sends the MIME attachment along with the body of the request to an external service.
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 as below. Note the Profile Type set to "None".
You can use this cache in the Web Service Server operation to cache the MIME attachment from the incoming document. WSS_ROOT_DOCUMENT_ID will be a unique identifier which is auto-generated for the attachment and will be available in the message body. When this document is being sent to another web service using Web service SOAP Client, the same cache is to be used in the client's operation and based on the incoming document's WSS_ROOT_DOCUMENT_ID value, the right attachment will be picked up and sent to the endpoint.
Scenario 1: Receiving Attachments with the Web Services Server
Let's take a scenario where we have to receive a document sent as MIME SOAP attachment along with some data. A good example 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 will be configured to receive a MIME type of attachment.
The process uses a cache with a single Index and Document Property key, which is a dynamic document property "WSS_ROOT_DOCUMENT_ID".
When this cache is used for configuring the attachment cache in the WSS operation, the attachment is cached. In branch 1, the same cache is used in a Load From Cache shape to retrieve 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.
Scenario 2: Sending Attachments with the Web Services SOAP Client Connector
Consider a case where we want to send a MIME SOAP Attachment to a web service. We would have to configure a client to do so. To demonstrate an example, take a case of an XML with product details, which has a multiple 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 images to web server, we need to extract the images and send them to the web service as MIME SOAP Attachments.
We now design our client process with two branches. Branch 1, splits the number of attachments (extracted from the input tag) and decodes each attachment before adding to the cache. Note the configuration of the cache.
The Dynamic Document Property WSS_ROOT_DOCUMENT_ID has been configured with a static value in the beginning of the process.
In Branch 2, the product details are sent as is while the attachments are loaded from the cache in the connector operation, by using the same cache component in the Attachment Cache configuration.
The receiving web service should extract the images from the cache (similar to scenario 1) and perform the desired action with the attachments (let's say, store to a disk).
What are the unsupported scenarios?
Currently you cannot:
- Include attachments in the response to a Web Service Server Listener (i.e. Return Documents shape). Only RECEIVE is possible.
- Retrieve attachments with a Web Service SOAP Client call (i.e. Web Services SOAP Client Get call). Only SEND is possible.
- Get or Send attachments with the HTTP Client connector.