The file upload field allows users to upload files as part of their form submissions. Any number of file upload field types can be added to any page of a form, and these field types provide the primary interaction between the user, the Forms Service, and the File Store Worker.
This article looks at the various services iCM and the API Server deliver when working with uploaded files, and offers some guidance on the best ways of interacting with them.
If you need to display files uploaded on one page of a form on a later page, for example, a Check Your Answers Page, you can use the Handlebars File Upload Helpers.
The File Store Worker and File References
The File Store is an internal service used by iCM and the API Server to handle uploaded files. It encrypts and stores files, and maintains file references to prevent them being deleted by other services.
File references allow more than one service to register that it is using a file. For example, a file could be uploaded as part of a form submission which starts a workflow process instance and saves form data to the iCM database. Both the workflow engine and the saved form data need access to the stored file, both could also attempt to delete the file.
By using a reference, the form data can safely be deleted. When the form data is deleted, iCM makes a delete call to the File Store that attempts to delete the file and remove the form data file reference. The file reference is removed, but because another reference exists the physical (encrypted) file is left in place while the workflow engine still has an interest in it. When the process instance ends it also makes a delete call. Because it has the only reference to the file both its reference and the file are deleted.
Unlike some services, such as the End Point Ajax Library or Postcode Worker, the File Store Worker is never exposed by the site frameworks. This means it can never be called in a browser and files cannot be retrieved directly from it.
File references are used by active workflow process instances, active form sessions (either while the form is being completed, or when saved as a long-lived session), iCM objects created by the database save action field, and in history data when form data is saved as part of an event (note that it is not the history service that adds the file reference, it's done by the form fields/actions that write to history).
Secure File References
There are times when you will need to access stored files, perhaps presenting them to a user and allowing them to be downloaded. Secure file references are generated by the File Store Worker to provide time-limited access to a file in the store, encrypted using various methods, including the name of the user allowed to access the file. Should a user attempt to use a secure file reference generated for another user to access a file, they'll receive an error.
Secure file references are generated automatically by the file upload field and GOSS products like Self Service and User Requests.
The first example form related to this page includes a file upload field. By navigating back and forwards through the form you can see how the field generates a secure file reference to access the uploaded file saved temporarily in the file store. The form also includes a save button. When you return to a previously saved form you'll see a secure file reference linking to the file that was uploaded before the form was saved.
Similarly when you view form submissions that have been saved to the iCM database as objects, the file upload fields on those forms will automatically generate secure file references you can use to access the saved files.
Working with Uploaded Files
When a form that includes uploaded files is submitted and the form session ends, the files will be deleted unless you decide to do something with them. You could attach them to an email so responsibility for the files becomes the recipient's. If you choose to save form data to the iCM database (either as objects or history), or start a workflow process instance, the files will persist in the file store and can be accessed in various ways.
Emailing Files
The email action field has a true/false property called Include uploaded files. If set as true all files uploaded as part of the form submission will be attached to the email that is sent. Remember that it's possible to have more than one email action field on a form, so not all recipients need be sent the files.
Saving Form Data
The database save action field turns a form submission into an iCM database object, with the fields of the form and their values saved as its properties. Saved data can be viewed using the form data browser.
When form data is viewed a file reference is generated and the files uploaded with the form can be viewed and downloaded in iCM.
The file will remain in the file store for as long as the saved form data exists in the iCM database.
Workflow
The workflow start action field has a property called Keep file references. If you don't keep the file references they (and the files themselves unless something else has a file reference for them) will be deleted once the initial workflow action has completed. If you do keep the file references, they will be passed to the process instance in a process variable and be available to use in your process model while your process instance is active.
The
{
"form_FILEUPLOAD": [
{
"id": "95B617B9-00D6-4908-8785-C450E37D98B8",
"filename": "formdatafileupload.png"
}
]
}
The upload field of the form, just like any other field, also has its value saved in a process variable, which is the file ID and name:
'file/95B617B9-00D6-4908-8785-C450E37D98B8/formdatafileupload.png'
The process instance example form related to this article shows how uploaded files appear during a process, how they can be accessed during a subsequent user task, and how to attach them to a workflow email activity.
The uploaded files will remain in the file store for as long as the process instance is active.
History Service
The history service does not create file references, but does hold a record of them. If your form or workflow action saves form data in a history event, and that form data includes a file upload field, you'll see an entry similar to the example below when you inspect the history.
{
"pos": [2, 3],
"event": {
"private": false,
"historyDescription": "File handling in workflow processes",
"description": "Summary",
"proxyUserId": null,
"formData": {
"data": {
"FILEUPLOAD": "file/7A09CB63-BC8B-45E1-B228-4EC8369A74D8/formdatafileupload.png",
"EMAIL": "support@gossinteractive.com"
},
"formName": "WORKFLOWFILEUPLOADSSTART",
"typeName": "FORM_WORKFLOWFILEUPLOADSSTART",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "SUMMARY",
"userRole": "workflowengine",
"userId": null
},
"fpos": [2, 3],
"timestamp": 1512664212737
}
The formData object includes the name of the file upload field and the file reference to the uploaded file in the file store. Note that the reference in the filestore is created by the Forms Service when it processes the form submission - manually creating a history won't automatically create a file reference.
If you choose to create self-service summary events (an option in the workflow action fields) form data will always be stored.
Remember that once written, an entry in the history service cannot be edited in any way. This means that if you save form data that includes any upload fields, file references will be present and files will remain in the file store, potentially forever. History records can be deleted, but they are deleted in their entirety - this is the only way to remove a file reference from the history service.
Storage and Access
There are several things to consider when working with uploaded files:
- When a file in the file store is no longer referenced by a form session, active workflow process instance, or saved form data (either as iCM objects or in the history service), it is deleted.
- Links to files in the store cannot be sent to users because the file store is not publicly accessible.
- Secure file references can't be posted as links to files, because they are time limited and can only be accessed by the user they were generated for.
Share this page
