Skip to content

Add File – storing a file from an action

The command "Add File" stores a file in a file storage (Azure Blob Storage or S3) under an identifier. This page is for administrators who build actions that create documents, keep exports or store the content of an API answer as a file.

1. At a glance
Purpose Store content that an action has in a variable or computes in an expression as a file
Typical use Keep an export, a generated document or a downloaded file with a record
Where in the editor Toolbar menu "Files" → "Add File"
Needs a user interface No
Needs a current record Yes
Related Get Files, Get File Data, Remove File, Export Query

Summary

  • The content is given base64 encoded. Plain text has to be encoded first.
  • The file is queued on the current record and written to the storage when the record is saved.
  • Files are found again by their identifier alone, not by record.

2. Settings

The settings are on the tab "Settings". Like every command, the command also has "Display Name", "Description" and "Execution Condition" on the tab "General" (see Actions).

Setting Meaning Default / Required
"File Provider" The kind of storage: "Azure Blob Storage" or "S3 Storage" Required
"Credentials" The credentials of the storage. Once a file provider is chosen, the list only offers credentials of the matching kind ("Azure Blob Storage Credentials" or "S3 Storage Credentials"). Required
"File Name" Expression for the file name including its extension, for example invoice.pdf Empty: the file has no name
"Mime Type" Expression for the content type, for example application/pdf Empty: no content type
"Base64 Data" Expression that computes the content, base64 encoded – typically a variable Required
"Identifier" Expression for the identifier the file is filed under. Files form blocks, Get Files and the attachments of Open E-Mail Form find the file by this value. Required
"Save" Saves the record right after the file was queued Off

All expressions are evaluated against the record the action is working on at that point, and can use the variables of the action.

3. Behaviour

  1. Without a current record the command is skipped: it does nothing and the action continues. The same happens when "File Provider" or "Credentials" is not set or the credentials no longer exist. There is no default storage.
  2. The expressions are evaluated and the content is decoded from base64. Content that is not valid base64 is not stored; the reason is written to the log and the action continues.
  3. The file is queued on the current record, together with the record and the user as information about where it came from.
  4. With "Save" on, the record is saved at once, and the file is written to the storage. If the save fails, the action ends with an error. With "Save" off, the file is written with the next save of the record – if the record is not saved, the file is lost.
  5. A file whose identifier is empty is dropped when the record is saved; this is only written to the log.

Identifiers are not tied to a record

The identifier alone decides which files belong together. If every record uses the same identifier, for example contracts, every record shows the same files. To keep files per record, build the identifier from the record, for example contracts- followed by the record ID. Use the same expression wherever the files are shown or read again.

Adding a file never replaces another one. A second file with the same name and identifier is stored next to the first.

4. Examples

Keep a monthly export with a report record.

  1. Export Query with "Output Format" XLSX writes the open orders into the variable Export.
  2. "Add File" with
    • "File Provider" Azure Blob Storage, "Credentials" Document storage
    • "File Name" open-orders.xlsx
    • "Mime Type" application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
    • "Base64 Data" the variable Export
    • "Identifier" report- followed by the record ID of the report
    • "Save" on

A files form block on the report form with the same identifier expression shows the file.

Store the answer of an API as a text file. The response body of an HTTP Request is plain text. Use a Modify Value expression with the rule EncodeBase64 on the response variable as "Base64 Data" (see Value modification rules), and text/plain or application/json as "Mime Type".

5. Limitations

  • The command cannot run without a current record, for example in an action that runs without a record.
  • Errors while writing to the storage during the save are only written to the log. The action does not learn about them.
  • The command does not check whether the content matches the file name or the content type.