File Uploads and Email Attachments in Workflow

When a form that includes file uploads interacts with a workflow process, files are stored using the Filestore worker and references to them are passed to your process instance.

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.

A list of all of the uploaded files is held in the _fileReferences process variable (see below).

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.

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.

• An array of explicit file identifiers (assuming you know them) could be added to the attachments property as: ["0a148876-c9c3-4e8f-9d3d-cfb476446540"]
• Named process variables generated by your form's upload fields can 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?

A Script Task to Check for Uploads

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:

The script task contains:

let fileuploads = execution.getVariable("_fileReferences");
if (!fileuploads) {
    execution.setVariable("attachments", "[]");
} else {
    let fileIDs = [];
    for (let x in fileuploads) {
        fileIDs.push(fileuploads[x].map(function(a) {
            return a.id;
        }).toString());
    }
    execution.setVariable("attachments", JSON.stringify(fileIDs));
}

The process variable set by the script is used in the attachments property of the mail task: