File Upload Element

The File Upload Element allows a user to upload a file to you from within the form, which can be stored as a file or in a database.

Click on image above to display larger

At runtime, the Element displays a Browse button, along with some accompanying wording and the configured maximum file size. These are contained within a box with rounded corners and a dotted boundary line, as shown above. When the user clicks or taps the Browse button, a standard file browse dialog will be displayed for the user to locate and select the required file. In addition, a file can be dragged from an opened browse dialog box and dropped anywhere inside the Element's dotted boundary line.

After selecting a file by browsing or dragging-and-dropping, the Element will change to display the name of the selected file:

Click on image above to display larger

At this point the file is not actually uploaded and the user can delete their selection by clicking or tapping the button to the right of the file name. Alternatively, the Clear button can be clicked to remove the selected file. The file will be removed and the Browse button (along with the accompanying wording and configured maximum file size) will be displayed. The user can then make another selection, if desired.

The file will only be uploaded when the user submits the form, using a Submit Button, a Submit form or Update Datasource action within an Event, a call to submitForm or updateDatasource within custom JavaScript or by clicking on the Pay button in a Capita Pay360 Cart Element.

In addition, you must provide an output mapping for the File Upload Element - see the Value property below for more information.

When the form is submitted, the selected file will be uploaded to the web server running your form and either stored in a database or written to disk.

If you want to allow users to upload more than one file, you can add as many File Upload Elements as you need to your form - each Element will only allow a single file to be uploaded. Each Element is configured separately, allowing you to mix uploading to file and to a database on the same form, if required.

Whether you choose to store uploaded files as files or in a database, you will need two database tables to hold information about the files uploaded and, if storing the files in a database, to store the files as well:

The first table must be called NDLFXFile in a Database of the same name, NDLFXFile. We will refer to this database and table as the File Upload database and the File Upload table. When your form is submitted, Digitise Forms will automatically create a record in this table for each file uploaded from the form.

This table must contain the following three columns:
- FileId - the Primary Key with a data type of GUID (uniqueidentifier), which will uniquely identify each uploaded file record and will be used to link this record to the corresponding record in the second table, described below,
- Filename - which will contain the full file path and file name of the file, if the file is stored to the file system, or the file name of the file, without a file path, if the file is stored to the database. In either case, the name of the uploaded file will be changed to be a unique name in the format: <formname>_<FileId>.<fileextension>
  
  and
- FileData - which will contain the actual file contents if the file is stored to the database, or NULL if the file is stored to the file system.

The second, or sister, table and it's parent database can have any names. Your form must be configured to create a record in this table when the form is submitted, which will include a link for each file uploaded from the form to a corresponding record in the NDLFXFile table (this will be explained further shortly). Note, that there will only be one record in this table per form submission, but there will be a separate record in the NDLFXFile table for each file uploaded as part of that submission. This table is used by the File Download Element to locate previously uploaded files if you want to allow them to be subsequently downloaded to the same or a different form.

We recommend you use the form Dataset for this table which will allow you to include other data from the form in the one table, although you can create a separate table if your needs require it.

The table may contain any columns but it must include the following columns:
- A Primary Key with a data type of GUID (uniqueidentifier), which will uniquely identify each record in the table
  
  and
- A separate column, with a data type of GUID (uniqueidentifier), for each File Upload Element included on the form. This column will contain the Primary Key, i.e. the value in the FieldId column, from the corresponding record for the file in the NDLFXFile table. Note, however, that whilst these columns provide the link between the files recorded in the NDLFXFile table and any other data captured from the form, which is stored in this second table, the fields do not have a Foreign Key relationship.

The New Datasource from Form option provides a simple method to create these tables, but you can create them separately, e.g. using SQL Server Management Studio, if you prefer. If you use New Datasource from Form, Form Studio will automatically generate the NDLFXFile Datasource and its NDLFXFile Dataset and also generate a Form Datasource and Dataset containing the required data columns for the File Upload Elements along with columns for any other Elements which aren't output mapped to another Datasource. The File Upload columns will be given the same names as the Upload Elements themselves. New Datasource from Form will also automatically output map the File Upload elements to the appropriate Form Dataset columns. When you publish the form, the physical databases and tables will be created, if they don't already exist. If you are not using New Datasource from Form for any other data on the form, you can still use it to create the Datasets required for the File Upload Element(s). If you don't use New Datasource from Form to create the Datasets, you will have to manually output map the Upload Element(s) to the appropriate column(s) in the sister Dataset (see the Value property below).

Once you have created these Datasources and Datasets, you can view them in the Datasources tab of the Project Explorer as normal. Note, however, that if you use New Datasource from Form to generate the tables, the NDLFXFile Dataset will be greyed-out and cannot be opened or edited, although it can be deleted if no longer required or you want to regenerate the Project Datasource.

As with all Datasources, you will need to supply user access credentials for the NDLFXFile database, which we recommend that you do within the publish profile when publishing your form, rather than through the NDLFXFile Datasource's properties.

New Datasource from Form will, by default, use the same instance of SQL Server to store the NDLFXFile database as the Form Datasource. If you have multiple forms with File Upload elements and you specify the same instance of SQL Server for all of these forms, they will all use the same NDLFXFile database and table. You can specify a different instance of SQL Server to be used for the NDLFXFile database within the publish profile, when publishing your form, if you prefer.
If you use the same database for multiple forms and you import the NDLFXFile database as an Imported Datasource, you could potentially download file data from all forms using this file to a single form, which may or may not be desirable. Accessing previously uploaded files via a file upload sister table instead, will restrict access to files recorded in that table and won't give access to other form's files.

Storing uploaded files to disk

To store uploaded files as files, you need to set the Element's Destination property (see under Properties below) to FileSystem. You may also need to output map the Element to the appropriate column in the sister Dataset, if you don't use New Datasource from Form to create the Datasets (see the Value property below).

If you set the Destination property to FileSystem, an uploaded file will be stored in the form's Fileuploads folder below the form's web app root folder, e.g. C:\inetpub\wwwroot\<project name>\Fileuploads, with a unique file name as described above.

The user under which the IIS Application Pool, running your form, is running will need write permissions to this folder. If the Application Pool is running under the ApplicationPoolIdentity user refer to the FAQs for information on giving this user access to your specified folder. You may also need to check whether the folder has its Read-only attribute selected and if so deselect it. To check this attribute, right-click on the Fileuploads folder in Windows File Explorer and choose Properties. The Read-only attribute can be found under the General tab - make sure the check box is clear.

The file name and location of the file on the web server, will be stored in the NDLFXFile table, as described above, and the corresponding record in the sister table will have the FileId value from the NDLFXFile table record inserted into the column which corresponds to the File Upload Element from which the file was uploaded. In this way, you can link the record in the sister table with the related file upload record(s) in the NDLFXFile table, allowing you to match an uploaded file to any other the data from the form it was uploaded with. Remember that the name of the file on the web server includes the FileId value within it.

You can configure a folder path within the Publish Profile which allows uploaded files to be retained. This stops you having to copy files from within the default Fileuploads folder, then past them back in again after each re-publish. The Fileuploads folder is removed and files within it are deleted with each re-publish, so if uploaded files are saved to this location, they will need to be copied (before each re-publish) then pasted back in again.

In the Publish Profile under the Forms heading, enter a location where you would like your uploaded files to be saved in the Upload Folder column within the Forms table row. The path must be valid on the server you are publishing the form to. If this is the localhost, then the path must be valid on the local machine. Network locations can be used, but they must be accessible from the machine being published to. Alternatively, a folder on the local machine or local network share can be selected using the Browse button provided.

The selected folder will not be overwritten, and any files placed within the folder won't be removed. Each file will have a unique, auto-generated file ID assigned to it, comprised of the name of the form which contains the associated file upload element, followed by a string of alphanumeric characters separated by hyphens.

When the form is published for the first time, a warning message will appear advising you that a different uploads location should be used, rather than the default Fileuploads folder. You can select Continue to publish the form using the default folder, or click Close to dismiss the message and change the folder location as recommended. If you decide to keep the default Fileuploads folder, files will need to be copied from within it before the next re-publish, then pasted back in again once it has been re-created.

If you change the folder, you will need to manually configure its permissions. The user under which the IIS Application Pool, running your form, is running will need write access to this folder. If the permissions aren’t configured to allow write access, uploaded files will not be written to the folder. A warning message will not appear if the target folder hasn’t been configured correctly. The file upload won't place any files within the target folder, and the form will have to be re-published once the correct folder permissions have been applied.

Once you have changed the folder location for file uploads, when you re-publish the form a warning message will appear reminding you that write permissions need to be in place for the target folder for the user under which the IIS Application Pool is running. If the folder has been configured to allow write permissions, click Continue to carry on publishing.

If you have multiple forms with File Upload elements and you want to use the same instance of SQL Server for all of these forms, they will all share the same instance of the NDLFXFiles database and table.
If you use the same database for multiple forms and you import the NDLFXFile database as an Imported Datasource, you could potentially download file data from all forms using this file to a single form, which may or may not be desirable. Accessing previously uploaded files via a file upload sister table instead, will restrict access to files recorded in that table and won't give access to other form's files.

By default IIS restricts file uploads to a maximum file size of 4 MB.

Properties

Once you have placed a File Upload Element on a page, you can edit the Element's properties to configure the Element for your requirements. Select the Element on the page to display its properties in the Properties Pane.

The following properties are available:

Name and Code Name

Label

Allows you to specify text that appears to the left of the upload button. You can change the default label to provide a more meaningful description or option for your users.

Note that you can't change the text on the button itself as this is fixed by the browser.

Data Tab

Value

Allows you to specify data mappings for the Element.

If the File Upload Element is placed directly on the form, this property will automatically be completed when you run New Datasource from Form, as discussed earlier, and you shouldn't generally need to change it. If you don't use New Datasource from Form, you will need to specify an output mapping manually. In this case, you will need to output map the Element to its corresponding column in the file upload sister table (see above). You don't need an output mapping to the NDLFXFile Dataset, this table will be handled automatically by Forms.

There must be an output mapping specified, otherwise the file will not be uploaded.

If you specify an input mapping, to the same data field as the output mapping, after submitting the form, the value displayed in the File Upload Element will change to display the unique identifier assigned to the uploaded file, providing you are using a Submit Button or Capita Pay360 Cart to submit the form and you haven't selected the Reset Form on Submit property. If you leave the input mapping blank, after submitting the form, the Element will redisplay its Choose File button.

On the other hand, if you place the File Upload Element on the edit page for a Recordset, you must specify both input and output mappings for the Element. Both mappings should map to the same data field in the same Dataset and this should be the column in the file upload sister table containing the values which link the records in the sister table to the corresponding records in the NDLFXFile table. This data field will need to have a data type of GUID in the Dataset and uniqueidentifier in the SQL database table. In this situation, if you are displaying the mapped data field in your Recordset, when you return from the edit page, the column will display the name of the selected file and after submitting the form this will change to display the unique identifier assigned to the uploaded file, unless you have the Reset Form on Submit property selected.

In all cases, if you provide an input mapping and download data from the file upload sister table to the form, the File Upload Element or Recordset will display the unique identifier(s) (GUIDs) assigned to the uploaded file(s) rather than the original file names.

For more information about mapping properties to data items in a Datasource see Data Tab Properties.

Advanced Tab

Behaviour Category

Destination

Allows you to specify whether the uploaded files will be stored in a database or as files in the web app's Fileuploads folder. To store uploaded files as files, select FileSystem, to store uploaded files to database, select Database instead. By default, this property is set to FileSystem.

Accepted File Types

Allows you to specify which types of files the user can upload. You can choose between allowing all file types, images only, audio only or videos only. If you want to specify a different set of file types, you can select Custom here and then specify the files you want to allow in the Custom Accept Expr property below.

Custom Accept Expr

This property is only relevant if you have selected Custom in the Accepted Files Type property above and allows you to specify which files users will be able to upload. You can specify allowable files by file extension, IANA Media Type or category of file. To specify multiple allowable files enter a comma separated list. The list can include any combination of specific file extensions (including full stop, e.g. .gif, .txt, .doc, .mp4), valid IANA Media Types (with no parameters) and any of the following 'all file' category values:

audio/* - all audio files

video/* - all video files

image/* - all image files

Configuration Category

Max File Size

Allows you to specify the maximum file size, in megabytes, you will accept. IIS restricts file upload sizes and the value you enter in this property will not change the IIS limit, which by default is 4MB, but can be used to impose a smaller limit if required.

Styles Category

File Upload, Label, Drop Area and Error Message

These properties allow you to assign a style to the Label, the edit box and invalid data error message text, respectively, e.g. to set the font type, size and colour.

Upgrading from an earlier version

If you have upgraded a project created using a version of Digitise Forms earlier than Digitise Forms - 2021 Spring Update but not upgraded the Elements on the form, existing File Upload Elements will continue to work as before.

If you have upgraded the Elements on the form, existing File Upload Element(s) will again continue to work as before. The Destination property (see above) will be displayed in the Properties Pane but is ignored and you cannot opt to save files to the database. The NDLFXFile database won't be created and records of the uploaded files will be output to the same data field as before.

In both cases, however, the file names of uploaded files will now be stored in the output mapped data field with a full path and won't just be the file name, in order to make the files accessible to the File Download Element. Note that you can also make files uploaded from earlier versions of the form available to the File Download Element, by editing the existing records and changing the stored file name to a fully qualified file path and file name.

Whether you have upgraded existing File Upload Elements or not, if you add a new File Upload Element to your form, this Element will behave as described in this topic and will allow you to choose to store files to the database, if you want to. The NDLFXFile database and table will be created, if necessary, when you next publish your form and records of files uploaded from this Element will be stored in the NDLFXFile and the sister tables.

If you want an existing File Upload Element to work in the new way, you will need to delete the existing File Upload Element and replace it with a new version from the Elements gallery. This includes the ability to add File Upload Elements to a Recordset's Edit Page.

If you replace an existing File Upload with a new one, once you have dropped the new copy of the Element on to the form, you will need to reconfigure it as the previous property settings will be lost when the original File Upload is deleted. If you are storing records of the file uploads in the form Dataset, you will need to run New Dataset from Form again to add a new column to the Dataset for the new File Upload Element. The previous column used by the original File Upload Element will not be deleted in order to preserve previously stored data.

If you allow users to save and restore a form which contains File Upload Elements, the file selections cannot be saved because of restrictions due to browser security. When the form is restored, File Upload Elements placed directly on the form will be empty and display the Choose File button instead of the previously selected file name(s). The user will need to reselect the required files. After restoring the form, the form will display the first page containing any File Upload Element marked as Required.

File Uploads performed from a Recordset's edit page, however, will still appear to have the data saved in the Recordset after the restore. However, the file names associated with the records displayed in the Recordset will have been lost from the File Upload Elements themselves and the user will need to re-edit each row and reselect the file to be uploaded. On the edit page any File Upload Elements will be empty and will display the Choose File button. If you only have File Upload Elements in Recordset edit pages, the form will not display the first page containing a File Upload Element after a restore.

If you have any File Upload Elements on your form, a warning message telling you that File Upload Elements are not supported with Save and Restore will be displayed when you publish the form, to remind you.