File upload and download

Overview

ACE introduces file references as a convenient abstraction layer for propagating files through flows.

Files uploaded in ACE produce IDs known as file references. The file reference can be used to reference the file in other steps.

For example, the REST step can recognize a file reference passed as a File field, resolve it and send it as a form field in a multipart/form-data REST request.

File reference lifetime

File references are valid for the duration of the API request calling the flow. The file and file reference will live as long as the operation, and be terminated as soon as the operation terminates.

caution

Storing the ID and referencing it in the context of a separate API request is not supported.

File upload to ACE

info

See tutorial uploading form files to backend service for an end to end example.

Multipart request

ACE handles multipart/form-data API endpoint calls by making the received multipart/form-data text fields available in the flow document. File fields will produce file references which can be accessed from the document node with the same name as the file field. For example, the file in form field myFileField will also populate the document node myFileField with a file reference.

These variables also contain meaningful information about the uploaded file, such as size and content type:

• id - can be used to reference the file in other steps.
• fieldName - is the multipart/form-data field the file was defined in, can be shared by multiple files
• fileName - the sent file name
• extension - final name part, e.g. myFile.test.yaml -> .yaml
• contentType - the content type of the file as defined in the multipart/form-data
• size - size of the file in bytes
• detectedExtension - detected file extension, empty in case detection failed or file is text based
• detectedMimeType - detected file mime type, empty in case detection failed or file is text based

file reference

{
  "id": "pointer to the referenced file",
  "fieldName": "myFile",
  "fileName": "fileName.yaml",
  "extension": ".yaml",
  "contentType": "text/yaml",
  "size": 999,
  "detectedExtension": "",
  "detectedMimeType": ""
}

Storage considerations

The uploaded files are saved locally in a temporary directory or in memory depending on configuration and are cleaned up as soon as the operation terminates. Storage has to be taken into account when handling multipart/form-data files.

File download from ACE

It is possible to create an API endpoint via ACE so that it triggers a download of the file reference. To do this, specify the document level property responseType as file and place the file reference into the result property of the flow. Any API endpoint with a flow where the doc level node responseType is set to file will act as a file download endpoint. Any file download endpoint returns the content disposition header by default - Content-Disposition: attachment; filename="name-of-the-file.pdf".

caution

Keep in mind, while file might be downloaded successfully, some formats cannot be previewed in the 'Try it out' view. This depends on the specified content type and encoding of sent/received data.

The following document can be used as an example for what a flow should return to trigger download.

Sample file download flow

{
  "result": {
    "id": "my-generated-id", // the file reference,
    "contentType": "application/json", // (optional) override the content type header
    "fileName": "myFile.json" // (optional) override the filename in the Content-Disposition header
  },
  "responseType": "file"
}

Note, since the result property is occupied by the file reference object, result property configuration such as errorHandler and responseHeaders can be specified at document level (e.g. { "result": { "id": "file-id" }, "responseHeaders": { "Content-Disposition": "inline" } }).

File reference content type detection

Files uploaded to ACE will go throught signature checks and will try to provide detectedExtension and detectedMimeType fields in returned file reference object.

For example, a executable file posted to ACE as a picture will be available as file reference inside the document:

Picture post example

{
  "content": {
    "id": "c619a88b-deac-43d7-98fa-9e582b771f56",
    "contentType": "image/png",
    "size": 2589872,
    "extension": ".png",
    "fileName": "i-am-picture.png",
    "detectedExtension": "exe",
    "detectedMimeType": "application/x-msdownload"
  }
}

Note that extension, contentType are provided from form-data or execution context, but in this case actual file was detected as executable windows file.

This can be used to validate files during flow execution. ACE doesn't enforce in any means, for example, for extension to match detectedExtension, so its up to the user to decided if such fields are useful in flow development.

Possible values for detectedExtension and detectedMimeType can be seen here.

In case a text file is uploaded, detection will return empty string as it only works for binary/complex files.

File type validation example

This example assumes that file is submitted in content field in multipart/form-data request.

Using Code step with error handling

Flow example

tags: []
sampleInputSchema: ""
sampleData: {}
description: ""
steps:
  - name: Step jsonata
    description: ""
    config:
      maps:
        - jsonata: '"Valid picture uploaded"'
          targetPath: result
    stepType: jsonata
    condition: ""
  - name: Step code-ivm
    description: ""
    stepType: code-ivm
    condition: '{{ !["png", "jpg"].includes(content.detectedExtension) }}'
    config:
      codeBlock: |-
        return {
        "errorHandler": true,
          "errorResponse": {
            "statusCode": 400,
            "response": "Invalid file type"
          }
        };
      targetPath: result

In case of incorrect extension:

Flow result

Invalid file type

In case of valid extension:

Flow result

Valid picture uploaded