HowTo: Set up File Upload in the Essence Portal

In many cases it might come in handy to add a file attachment. For example, you have a Support Question and the user should be able to upload a screenshot. Or you have a Sales Contract and the user should be able to upload a PDF of the signed contract. In such cases you can enable the option to upload files.

With Essence, files can be uploaded in three different ways. First, let's explain the different ways and than let's see which way would be best for your case, and why.

  1. Saving files on disk
    To implement that the files are stored on disk a text field is required. Keep in mind that sufficient characters are used because Essence does extend the name of the file with the ID of the entity to ensure the filename will be unique (e.g. PolicyType1.txt will be changed into  PolicyType1_2235ee5a-9e8c-46ec-9c2a-9c6108077b09.txt).

    By changing the BaseEntityProperty Input Control Type into ‘File Uploader’ Essence automatically arranges that a file can be uploaded and that it will be stored in the Upload folder in the root of the Essence installation folder. For each entity that will save files a sub-folder is created.
    Note: The default supported file-types for upload are all Office types, pdf, image types, zip and rar files. To upload other file types you need to specify which file-types are allowed.





  2. Saving files in the database without download functionality
    It is not always necessary that uploaded files need to be downloaded again. For example a photo of a resource or a building. The purpose of those files is to share the photo in Essence. Downloading is not needed.
    To implement this situation a BLOB (binary large object) field in your database is required. By changing the Input, ‘Control Type’ into ‘File Uploader’ Essence automatically uploads the file in the database without any additional metadata.



    Based on this configuration Essence automatically will present images on the screen. Advised is to set the allowed type of files to upload to ensure images will be presented on the screen. The class EntityImage, in the stylesheet, determines where and how the images are shown.



  3. Saving files in the database
    The last option is to store the file in the database with the option to download the files again. For this two fields are required. A text field and a BLOB field. The text field will store the filename and is required to get the possibility to up and download the file. The BLOB field is the place where the file will be stored in the database. Don’t forget to make the connection between those fields by selecting the ‘Data Storage’.


Which way works best for your scenario?

Upload files to disk

The first option to upload files to disk is easy to implement and is always available. So if you work on a database that does not contain any BLOB fields and you cannot change the database model, this option can still be available.

However, you need to consider that the files are not included when you make a backup of the database. To make a backup of these files, you should do this using the general backup of the server itself.

You also need to consider that anyone who has access to that server, can access these files through the Windows Explorer. You might want to restrict access to the Uploads folder using Windows Security.

Upload using BLOB only

This is also an easy to implement option. Here you don't need to worry too much providing you have set up a database maintenance plan to create backups regularly.

The one thing to consider here though, is that the original filenames are lost. This means that if at a later point you do want to make file download possible, this will not work for files uploaded before you made that switch. So if you set up this scenario, do make sure that the download option is really not necessary. When in doubt, go for option 3.

Upload using Text and Blob

In most scenarios this is the option we would recommend. The only consideration here (and it goes for the previous option as well) is that your database could grow exponentially. Using a BLOB might therefor not be the best option if you expect that larger files (let's say 30 MB or more) would be uploaded often. In that case, option 1 should be considered.

The larger database would technically not even be the problem. But you might need to purchase a more expensive MS SQL Server license. If you would work on a Microsoft SQL Azure database for example, database storage is about 6 times more expensive than local file storage.