Uploading Files in Actions

Here is everything you need to know to configure action so that they can upload files.

General

In order to upload files through an action, either a public URL or a URL that is available in a Flow (e.g. the output of the CSV Helper) needs to be referenced to in a field with the key request_binary_url, which can be configured like this in the UI Form Schema Renderer:

{
  "request_binary_url": {
    "title": "File URL where the file is fetched from",
    "type": "text",
    "required": false,
    "info": "The file can come from a previous step of a Locoia flow or from a static location on the web"
  }
}

Only the key (request_binary_url) needs to be exactly as in the example, all other parameters can be set according to the action.

If that key is set and a valid URL is passed to it, the file will be converted to binary format and sent with the header value "Content-Type": "multipart/form-data".

The body consists of

• name which is by default file,

• filename which is based on the file name in the URL or if that cannot be retrieved file,

• Content-Type which is based on the file itself, and

• the file itself in binary format

and looks like this (without the file):

Content-Disposition: form-data; name="file"; filename="example-image.png".
Content-Type: image/png.

If the endpoint expects the file to be uploaded in that way, both the Request Body and Header Template need to be configured with {} only.

Body parameters

In addition to the automatically set body key-value pair, additional ones can be sent (which is e.g. required by HubSpot), by adding the parameters to the body like regular parameters. These will then be sent as form-data as well.

These parameters will then have the filename parameter, equal to the name of the Parameter. In case that is not desired or accepted by the API, the header should be set to:

{
  "Content-Type": "multipart/form-data"
}

File meta data

The following file meta data can be used in the body or header by referencing to binary_file.

• name

• content

• mime_type

For an example usage, see the Gmail action.

Alternative Content-Type header

To use a different Content-Type than the standard multipart/form-data, the Request Body Template needs to be left empty and the Content-Type that should be used needs to be set in the Request Header Template.

If the Request Header Template is left empty, no Content-Type header will be sent. This is e.g. needed for SharePoint file upload (and other Microsoft file upload endpoints.

Additional parameters

form_item_name

Some APIs, such as this one require that the name in the body is set to something else than the default file, in that case image. This can be configured directly in the UI Form Schema, by specifying the parameter form_item_name with the name that should be sent, e.g.:

  {
  "request_binary_url": {
    ...,
    "form_item_name": "image"
  }
}

upload

This parameter can be set to false if the file should not actually be uploaded, but only be converted to binary format and then uploaded in another format. This is for example needed to send emails with attachments with Gmail, where the request body needs to be built in the request body template and then base64 encoded:

{% set boundary = str(uuid(4)) %}
{% set raw = [
  'Content-Type: multipart/mixed; boundary="' + boundary + '"\n',
  'To: <' + to_email + '>\n',
  ...,
  '--' + boundary + '\n',
  'Content-Type: text/' + body_type + '; charset="UTF-8"\n\n',
  body,
] %}
{% if binary_file != None %}
  {% set raw = raw + [
    '\n\n--' + boundary + '\n',
    'Content-Type: ' + binary_file.mime_type + '; name="' + binary_file.name + '"\n',
    'Content-Disposition: attachment; filename="' + binary_file.name + '"\n',
    'Content-Transfer-Encoding: base64\n\n',
    binary_file.content | base64_encode
  ] %}
{% endif %}
{% set raw = raw + ['\n\n--' + boundary + '--'] %}
{
  "raw": "{{ raw | join | base64_encode("urlsafe") }}"
}

Upload as base64 string

Some Connectors expect files as base64 strings. In order to upload files like this, the upload parameter needs to be used.

So the Action setup would look something like this:

UI Form Schema

{
  "request_binary_url": {
    "title": "File URL where the file is fetched from",
    "type": "text",
    "required": false,
    "upload": false,
    "info": "The file can come from a previous step of a Locoia flow or from a static location on the web"
  }
}

Request Body Template

{
  "some_field_name": "{{ binary_file.content | base64_encode }}"
}

Uploading files using REST Helper

You can also upload a file using REST Helper.

1. Specify the API URL:

   • Determine the appropriate API endpoint you want to interact with.

2. Set Authorization Header:

   • Optional, if required by the API

   • More details

3. Select Content Type:

   • If you want to upload a file, you should select

   multipart/form-data

4. Set empty Body

   {}

5. File to Upload

   {{ some_pdf }}