Multipart Attachment Support for Trigger and Invoke Connections

The REST Adapter supports multipart attachments for trigger (inbound) and invoke (outbound) requests.

For example, you can send a review document attachment with the trigger (inbound) REST Adapter to an invoke (outbound) Adobe eSign or DocuSign for delivery to the downstream endpoint for signing.

If you want to send attachments from inbound to outbound (in request messages) or to download attachments from outbound to inbound (in response messages), then for each attachment you must map the attachmentReference from source to target in the mapper.
Description of ics_rest_multpart_map.png follows
Description of the illustration ics_rest_multpart_map.png

If you do not map attachmentReference in the mapper for a request, the outbound REST Adapter does not receive attachments from the inbound direction (multipart request). Similarly, if you do not map attachmentReference in the mapper for a response, the inbound REST Adapter does not receive attachments from the outbound REST Adapter (multipart response).

Understand the data structures of different types of configurations made using the REST Adapter or any application adapter exposing the REST API (used as a trigger) or consuming the REST API (used as an invoke).

There are two configuration categories of multipart request and response:

A - Multipart/mixed or multipart/form-data configured with JSON or XML samples

This configuration uses the attachments schema and payload schema. The payload schema is derived based on a sample JSON/XML schema provided during configuration in the Adapter Endpoint Configuration Wizard.
B - Multipart/form-data with HTML form payload

This configuration uses the attachments schema and a generic schema with a ParameterList element. The ParameterList element consists of an unbounded parameter element. Each parameter has a name attribute. The value of the parameter is set directly to the parameter element. If there are multiple parameters, the parameter element can be repeated in the mapper. The datatype of the parameter and name is string.

Note:
This category is used when you select Request is HTML Form in the Request page of the Adapter Endpoint Configuration Wizard. This is similar for a response if you select Response is HTML Form in the Response page of the Adapter Endpoint Configuration Wizard.

Note the following details about both configuration categories:

Attachments schema

The attachments element has an unbounded attachment element. This configuration supports receiving (on the source) or sending (on the target) multiple attachments. Each attachment element has attachmentReference and attachmentProperties.
The AttachmentReference element contains the location where the attachment has been staged for access.
The AttachmentProperties element provides metadata about a single attachment:
- The contentId property sets the Content-ID header of the body part. The Content-ID header sets a unique ID for the body part.
- The contentType property sets the Content-Type header of the body part. For example, if a PDF file is sent, the contentType property should be application/pdf. If the source is providing a multipart attachment, this is determined automatically. The mapper can set/override these values.
- The transferEncoding property sets the Content-Transfer-Encoding header of the body part. This header's value is a single token specifying the type of encoding:
```
Content-Transfer-Encoding := "BASE64" / "QUOTED-PRINTABLE" / 
                             "8BIT"   / "7BIT" / 
                             "BINARY" / x-token
```
  These values are not case sensitive. That is, Base64, BASE64, and bAsE64 are all equivalent. An encoding type of 7BIT requires that the body is already in a seven-bit, mail-ready representation. This is the default value (that is, Content-Transfer-Encoding: 7BIT is assumed if the Content-Transfer-Encoding header field is not present). See https://www.w3.org/Protocols/rfc1341/5_Content-Transfer-Encoding.html.
- The partName property sets the fileName of the body part. The attached file/body part is saved by the target system with this name.
- The contentDisposition property sets the Content-Disposition header of the body part.
  
  In a multipart/form-data body, the HTTP Content-Disposition is a header to use on the subpart (that is, the attachment) of a multipart body to provide information about the field to which it applies. The Content-Disposition header value is generally set to form-data. The optional directive name and filename can also be used. For example:
```
Content-Disposition: form-data
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"
```
- The contentDescription property sets some descriptive information with a given body part. For example, you can mark an image body as a picture of the Space Shuttle Endeavor. You can place such text in the Content-Description header field.
- The fileInputHtmlFieldName property sets the name of the part from which the server must read the file.

Mapper configuration scenarios:

Both source and target have multipart requests with JSON/XML payload (category A)

The following sample map focuses only on the mapping of attachmentReference to the target. In this scenario, there is an assumption that only one attachment from the source is being mapped to the target. The mapping of the payload (request-wrapper node) between the source and target is not shown. You must perform that task.

Description of the illustration rest_multipart_1.png
The source is multipart/mixed or multipart/form-data with JSON/XML payload (Category A). The target is multipart/form-data with form fields (Category B)

The following map focuses on mapping of the attributes on the HTML form. There must be as many parameters in the parameterList as there are fields in the HTML form.

Description of the illustration rest_multipart_2.png
Creating a reference from base64–encoded content. The source has a base64–encoded string and the target can be any of the three: multipart/mixed, multipart/form-data with JSON/XML payload, or multipart/form-data with HTML form payload.

In the inbound payload, the content element is a base64–encoded string. This can be sent as an attachment in the outbound request.

Since the inbound request is not multipart, but the outbound must be multipart, you must set multipart-specific properties in the mapper for the outbound direction. The contentType is set here to image/png, partName is set to picture.png, and fileInputHtmlFieldName is set to image. The assumption is that the target system is configured to read from a body part having name="image" in its content disposition. This is done with the element fileInputHtmlFieldName.

Description of the illustration rest_multipart_3.png

The base64 string can be converted into a reference using XSL function decodeBase64ToReference and the reference can be assigned to the attachmentReference element.

Description of the illustration rest_multipart_4.png
The inbound is an FTP file read operation (nonmultipart) and the outbound is multipart/mixed with a JSON or XML payload.

Description of the illustration rest_multipart_5.png

Note:

If the source is not multipart, but the target must be multipart, contentType and partName must be provided for the target through the mapper.
The response mapper description is similar to the request mapper.

Several implementation patterns are provided. See Implement Common Patterns Using the REST Adapter.