Design

Back Next

Attachments

Process Designer exposes an endpoint so you can access attachments in a process using an event handler, internal API calls, custom service connectors or built-in connectors like the Amazon S3 Connector. This enables you to pass through an attachment and extract data about the attachment like the file size and file name using functions on the response (where supported).

When you design a process, you can pass attachments into a subprocess, service connector, or

Service

steps or return attachments (where the output field is defined using the Attachment type).

In a

process

, you can allow the user to add one or more attachments as inputs where the attachment is coming directly from the screen (not carried across steps using

process

fields). For example, you could use a

process

to capture real property data and allow the user to attach photos of the associated property. However, you cannot access the attachment data within a

process

If you run a

process

on the cloud server, do not use an attachment whose size is more than the default 5,242,880 bytes. The cloud server cannot process attachments that are greater than 5,242,880 bytes.

Encoding: Attachments can be encoded as:
multipart/form-data (for browser-based interactions)
multipart/mixed

Data Types: You can specify named input parameters as attachments using two Simple data types:
Attachment
supports single attachments and allows you to define the maximum file size as a field property.
Attachments
supports multiple attachments and allows you to define the maximum file size and maximum number of files as field properties.

From within the process, you can access metadata about the attachment using an XQuery formula and built-in functions. For example, the following returns the size of the 'photo' input:

 sff:getAttachmentSize($input.photo)

You can assign input attachment fields to outputs or temp fields using an Assignment step. In that case, be sure that the target temp or output field is also of type Attachment.

In this example, the second parameter ($encodedContent) is a base64-encoded string:

 sff:createAttachmentFromBase64("base64", "UOpGUIRA", "ascii")

The attachment functions are available in processes but not in service connectors. See below for more information on handling attachments in service connectors.

Refer to Using Functions for more information on the functions available for use with attachments.

Attachment Payload

When using simple attachments, be sure that:

Each named part has the same name (name and Content-Disposition) as the Input parameter in the process.

The Content-Type of the part must also match the content type of the Input parameter. For all data types except attachments, Content-Type= text/plain (for example, text, checkbox, date).

If the part represents a process object, its contents should be valid, serialized JSON content (with a Content-Type of application/json).

You define process output field (s) of type Attachment (or Attachments). These fields are returned as attachments to the caller.

For example, if the process has input fields "first" (Text), "last" (Text), and "inputFile" (Attachment), the payload would be similar to the following:

POST /active-bpel/public/rt/Attachments_Test HTTP/1.1
Content-Type: multipart/form-data; boundary=----TheBoundary1234
------TheBoundary1234
Content-Disposition: form-data; name="first"
John
------TheBoundary1234
Content-Disposition: form-data; name="last"
Smith
 ------TheBoundary1234
Content-Disposition: form-data; name="inputFile"; filename="filename.png"
Content-Type: image/png
 ... binary image data ...
------TheBoundary1234--

The first part of the response should be a JSON document describing the response output fields. The JSON content will have the output field values (standard response).

If the output field is of type Attachment, the value will be a string containing the content-id (cid) of the part containing the attachment. For example, if the output fields are the "first" (Text), "last" (Text), and "inputFile" (Attachment), the response should look similar to:

Content-Type: multipart/mixed; boundary=----TheBoundary1234

------TheBoundary1234
Content-Type: application/json
{
"first" : "John",
"last" : "Smith",
"inputFile" : "cid:fc1c6030-4b90-4981-b9d8-ab1d0ba0e84e"
}

------TheBoundary1234
Content-Type: image/png
Content-Name: photo
Attachment-Created-At:1435182142837
Content-Id: fc1c6030-4b90-4981-b9d8-ab1d0ba0e84e
Content-Length: 1073
... binary image data ...

------TheBoundary1234--

If you do not enable Output field is whole payload
in the process properties and you have a single output field of type attachment, the response contains both the attachment data and the metadata, as shown here:

--Boundary
content-type: ...

cid:outputFile

--Boundary
content-type: image/jpeg

[binary data]

If you enable

Output field is whole payload

and you have exactly one output field of type Attachment, you can receive a single attachment (of type text or binary) without the metadata. If a third-party wants to access only the attachment, it is easier to consume. For example:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: length

[.. JPEG data ...]

Using Attachments in Service Connectors

You can define a service connector in order to submit an attachment from a process to a service connector's input or obtain an attachment from a service connector and submit it to a process as an attachment.

Attachments are sent directly to the service input (including Salesforce-based services) from

processes

and service connectors.

You upload or download content from services like Amazon S3 and propagate the attachment back to the main process under the name defined in the output mapping. With the Amazon S3 Connector, you can read or write the contents of an S3 object both as a Base64-encoded string and as an attachment. For more information, see the Amazon S3 Connector Guide
.

Using Multiple Output Attachments in Service Connectors

A service connector can handle a multipart response appropriately and create multiple attachments for different response parts. The part related metadata information is available in the attachment properties.

A service connector can also recognize the payload part. The first JSON/XML/Text part is used as the payload. You can extract data from the payload in the output field expressions of the action as you would normally do when you work with non-multipart responses. Note that the selected payload will not be available as an attachment.

In the

Output

tab, you can use the

Get from Attachments

option to work with multiple attachments and pass the entire list of attachments to the selected variable except the payload.

You can also use an expression to work with attachments in service connectors. When you open the Expression Editor, you can find the new functions in the

Functions

tab, under the

Output Attachments

section.

Using GET, POST, and PUT

You can define a service connector to use GET, POST, or PUT operations on a resource that does not support JSON or XML.

Note that:

The input parameters (Attachment type) must be uploaded to the destination from the binding URL (POST/PUT). Use a payload format based on the binding type and number of attachments.

If there are multiple attachment parameters and the binding is FORM, send all the parameters (including non-file parameters) as multipart/form-data.

If there are one or more attachment parameters and the binding is JSON, send files as multipart/form-data and combine non-file parameters into a single JSON element.

If there is exactly one file parameter, the binding is CUSTOM, and the binding payload is empty (no XML or JSON in a custom textarea), POST or PUT the raw file data as is.

If there are multiple attachment parameters and the binding is CUSTOM and the payload is XQuery, the HTTP outbound payload should be multipart/related. The first part is the CUSTOM (XQuery) content, followed by parts for each of the file/attachment input parameters.

You can assign input attachment fields to outputs or temp fields using an Assignment step. In that case, be sure that the target temp or output field is also of type Attachment.

Downloading multiple files (using multipart/mime attachment) is not supported.

Note
: The "sff" functions are available only in processes.

Using Functions

Download Guide

Watch

Comments

Cloud Application Integration Homepage