Map to Construct the Payload for an External REST API that Accepts multipart/form-data as the Content Type

Categories

There are two categories of multipart request (and response):

multipart/mixed or multipart/form-data configured with a JSON or XML sample

This category shows the attachments schema and payload schema. The payload schema is derived based on the sample JSON/XML schema provided during Adapter Endpoint Configuration Wizard configuration.
multipart/form-data with HTML form payload

This is used when you select Multipart request is of type multipart/form-data with HTML form payload on the Request page of the Adapter Endpoint Configuration Wizard or when you select Multipart request is of type multipart/form-data with HTML form payload on the Response page for a response. This configuration shows the attachments schema and a generic schema with a ParameterList element. The ParameterList element consists of an unbounded element parameter. 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.

Attachments Schema

The attachments element has an unbounded attachment element. This provides support for 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 attachmentProperties element is used follows:

The contentId property is used to set the Content-ID header of the body part. The Content-ID header is used to set a unique ID for the body part.
The contentType property is used to set the Content-Type header of the body part. For example, if a PDF file is being 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 is used to set the Content-Transfer-Encoding header of the body part. This header's value is a single token specifying the type of encoding, as enumerated below. Formally:
```
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 is used to set the fileName of the body part. The attached file/bodypart should be saved by a target system with this name.
The contentDisposition property is used to set the Content-Disposition of the body part.
In a multipart/form-data body, the HTTP Content-Disposition is a header used on the subpart (that is, attachment) of a multipart body to provide information about the field to which it applies. The Content-Disposition header value is typically set to form-data. The optional directive name and filename can be used. For example:
```
Content-Disposition: form-data
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"
```
and so on.
The contentDescription property is used to set some descriptive information with a given body part. For example, it may be useful to mark an image body as a picture of the Space Shuttle Endeavor. Such text may be placed in the Content-Description header field.
The fileInputHtmlFieldName property lets you set the name of the part from which the server needs to read the file. This is generally used when there is an HTML form to upload the file. The file upload input field name is used as a body part name.

Scenario 1 - source and target both have multipart requests with JSON/XML payload (Category A)

The following sample map focuses only on the mapping of attachmentReference to the target. 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 do that.
Description of rest_adapter_con_pay1.png follows
Description of the illustration rest_adapter_con_pay1.png

Scenario 2 - source is multipart/mixed or multipart/form-data with JSON/XML payload (Category A). Outbound request multipart/form-data with form fields (Category B)

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

Note:

If the source is not multipart and the target must be multipart/form-data with form fields, you must specify the value for the contentType and partName elements on the target side.

The fileInputHtmlFieldName element is important to consider if the target endpoint expects attachments under a specific body part name. The body part name should be specified here. For example, in the following image, the target endpoint is expecting a PDF document under a body part named file in the multipart/form-data request payload.
Description of rest_adapter_con_pay2.png follows
Description of the illustration rest_adapter_con_pay2.png

Scenario 3 - creating a reference from base64–encoded content

In this scenario, the source has a base64-encoded string and the target can be either one of the three: multipart/mixed or 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. The base64 string can be converted into a reference using XSL function decodeBase64ToReference and the reference can be assigned to the attachmentReference element as shown below. Since the inbound request is not multipart, but the outbound must be multipart, you must set some multipart-specific properties in the mapper for outbound. The contentType is set 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 fileInputHtmlFieldName element.

Note:

If the target is multipart/mixed or multipart/form-data using a JSON/XML payload, the schema of the target also has the schema from JSON/XML, as shown in Scenario 1. The approach for constructing the outbound request payload is the same.

Description of rest_adapter_con_pay3.png follows

Description of the illustration rest_adapter_con_pay3.png

Description of rest_adapter_con_pay4.png follows

Description of the illustration rest_adapter_con_pay4.png

Scenario 4 - source is an FTP file read operation (nonmultipart) and outbound is multipart/mixed with a JSON or XML payload

Description of rest_adapter_con_pay5.png follows

Description of the illustration rest_adapter_con_pay5.png

Note:

If both the source and target are multipart, then assigning only the attachmentReference element from source to target is sufficient.
- This keeps the multipart properties for the target the same as the source.
- If you must make changes to the multipart properties for the target endpoint, this can be done through the mapper for the target.
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.