The Document Field allows the user to upload a document into a specific field in a record from an external source . The document can then be downloaded by other users viewing the record.
This differs from the general Attachments area of the record which allows the same, but does not have the properties detailed below to allow App Builders to reference properties of the file.
Document fields will be shown as an icon within a record. They have a number of properties which can be referenced, and they can be used as part of workflow to email as attachments.
The default Maximum file size allowed for document fields is 10Mb and is a site setting. This can be increased to 30Mb upon request but there may be charges if total file storage exceed acceptable levels
Configuring a new Document Field
To create a new Image Field, you must first be in the 'Fields' section of AppStudio, here you will be able to click the 'Add Field' button in at least one of the highlighted locations below.
This will open the following page where you can scroll down and select the Document Field tile or search for it in the top right bar:
Once selected you will be presented with the configuration options below:
- Label: Visible in the App above the entry box it makes clear to the user what the document relates to.
- Identifier: This should reflect the label. The identifier is a system ID for referencing a Field. This ID must be unique per Field and must contain only letters and numbers starting with a letter. It must also be a minimum of three characters.
- Type: The sort of Field that is being configured - This will be a Document Field.
- Required: Does this Field need to have data in it before the Record can be created? If this is set and a record created where this field is left blank a Validation Error will occur preventing the Record from creating / updating.
- Read Only: Is this field editable when shown to the user in a record.
- Expressions: These are logic statements that are capable of determining the value for a Field and can perform an extremely wide range of tasks. For more information see here. The document field is a special type of field which CAN be exposed in expressions.
- Include in Free Text Quick Filter: Makes the Field searchable from within a Report in order to filter down Records. When a user enters a search phrase, this record will be returned if the document name contains the search phrase. NOTE: the contents of the document will not be searched.
- Exclude This Field From Templated Record Copies?: If toggled, the data in this field will be excluded from future copies of Records, whenever 'Template Copy' is selected for the copy.
*You must click 'Save' to commit the configuration to the system.*
As the document is a special type of field, it comes with it a number of additional "Backing Fields" which can be referenced in expressions and reports. These are as follows:
DocumentFieldID_FileName - this is the name of the file, and will be shown in the field on the record.
DocumentFieldID_FileType - this is the industry standard official file type (referred to as the MIME type) you would normally see as the extension of the file when looking in a file explorer, e.g. "doc", "ppt", "xls" - for the full list see here - List of MIME File Types.
DocumentFieldID_FileSize - this is the size of the file, in Bytes.
The above backing fields can be referenced in other fields as expressions, or added to reports in the same way. [DocumentFieldID] can be used in expressions to take the document from one field and show it in another, which is useful for Parent / Child Expressions and in workflow to attach the document as part of email workflow through a templated email export
Testing for the presence of a document in an expression
To test whether a document is present in an expression, use:
- If(DocumentFieldID_FileSize] > 0, 'there is a document loaded', 'There is NO document')
We will be working on the following future extensions to this field over time:
- Allow the App builder to restrict the file types allowed within the field
- Allow the AppBuilder to change the filename on upload based on an expression
- Allow some document types to have a preview, such as a video, pdf, image fields
- Allow documents uploaded to the document field to be visible in the list of attachments
If you would like to increase the size of the documents you can upload please contact firstname.lastname@example.org with the request
Make sure to click the 'Save' button when making any changes in order for them to be added to the next app version. Once you have made all the changes you need to an application you are then ready to publish it to workspace.