Toggle menu

File Uploads and Attachments in Workflow

When a form that interacts with a workflow process includes file uploads, the form's workflow action field controls what happens to any files included with the form submission.

File References

File references are records of files held in the secure file store, managed by the File Store worker. As described in Handling File Uploads, file references allow you to retrieve files, and when all references to a file have been deleted, the file itself is deleted.

Keeping File References

By default, when a process instance starts, the files uploaded will be available to your workflow process for as long as your process instance exists. You'll be able to use either of the methods described below to work with files in tasks and activities.

File references are held in the _fileReferences process variable.

Not keeping File References

If you don't want the workflow to keep any file references, use the workflow action field's process variables function to set "_keepFileReferences": false

If you don't keep file references, the files are still uploaded, but they are only kept during the initial processing of your process instance. This means they are kept for the duration of the first foreground job (the first transaction) defined in your model.

For example, if you choose not to keep file references, the first mail task in this workflow would be able to attach uploaded files to its email, the second wouldn't.

Mail Tasks and Foreground Jobs

There's more information about foreground jobs in the Workflow Transactions - Foreground and Background Jobs article.

Process Variables

Each upload field on your form creates a process variable. The process variable holds a single file reference in the format file/95B617B9-00D6-4908-8785-C450E37D98B8/formdatafileupload.png

If you choose to keep file references, the _fileReferences process variable includes all of the filenames and IDs for each upload field:

  "form_FILEUPLOAD1": [
      "id": "8E8F9EE4-DAB8-4A34-BA7D-0D9648291CA0",
      "filename": "handlebars.PNG"
  "form_FILEUPLOAD2": [
      "id": "4A243AED-FE57-4CDF-9982-6786D1F3E8E8",
      "filename": "hot-air.jpg"

The Mail Task

You can attach a file to the email generated by the mail task in several ways.

A single explicit file identifier could be added to the attachments property as: ["0a148876-c9c3-4e8f-9d3d-cfb476446540"]

The values of upload form fields could be added as: ["${form_UPLOADFIELD1}","${form_UPLOADFIELD2}"]

The problem with both of these approaches is that should the file identifier or process variable not exist, the mail task will fail with an error. You should only use these methods if you know the files will be there - in practice this means your form's file upload fields must be set as required.

But what if uploads are not required, or you have a variable number of upload fields?

Scripting the Attachments

You can actually reference any process variable you like in the mail task's attachment property, as long as that variable resolves to a value that contains a file identifier. This means you can use a script task to check for the _fileReferences variable, loop through the upload fields, construct an array of the IDs, add the array to a process variable, then add that variable to your mail task.

For example:

Scripted Attachments

The script task contains:

var fileuploads = execution.getVariable("_fileReferences");
if (!fileuploads) {
    execution.setVariable("files", "[]");
} else {
    var attachments = [];
    for (var prop in fileuploads) {
        attachments.push(fileuploads[prop].map(function(a) {
    execution.setVariable("files", JSON.stringify(attachments));

The process variable created at the end of the script is used in the attachments property of the mail task:

Attachment Property

Last modified on 23 January 2024

Share this page

Facebook icon Twitter icon email icon


print icon