File Pointer Properties
File Pointer Properties allow files to be stored as the value for certain properties which have the File or Filelist datatype. The files are stored in the File Store in the MongoDB repository and can be retrieved and downloaded locally through the Object Properties panel of the parent object.
They allow for operating manuals, documentation, images, icons etc. to be stored as property values, attached to objects and retrieved on-demand.
Adding Attachments in DataStudio
Most objects in the system have an Attachments property in the Common property compound of the Properties Panel.
In DataStudio, all File Pointer Properties can be managed using the File Manager Dialog to add delete and modify files. Click on the … icon to open the FileManager dialog.
File Manager
The File Manager table dialog allows you to manage the File Pointer Properties and add multiple attachments to the same object.
All the actions regarding File Pointer Properties follow the same workflow. For example, if you want to add a new file to the database, click on the + icon open the 'Select File' dialogue and the select the file which you want to attach to this object. Click open to confirm your selection.
At the bottom of the dialogue click OK to close it. Finally click Apply in the Properties Panel to execute your changes.
For other actions related to File Pointer Properties see the table below.
| Element | Function | Description |
|---|---|---|
|
Add File |
Opens the 'Select File' dialogue for uploading new files to the database |
|
Upload / Change File |
Opens the 'Select File' dialogue for uploading files to the database |
|
Download |
Opens the 'Save File' dialogue for saving to the local filesystem |
|
Remove Row |
Deletes the selected attachment. |
|
Preview |
Shows the selected attachment in the preview area (if possible) |
Upload Restrictions
Upload Restrictions for the filetype and/or the file size can be configured in the properties of the System object. There, in the FileStore > Upload Restrictions property compound, a maximum size for files can be specified and file extensions can be entered into a whitelist to allow or into a blacklist to disallow filetypes.
If both a whitelist and blacklist are specified, then only the whitelist is used. File Extensions have to be entered as comma separated lists - without dots (e.g. 'exe,bat'; not '.exe,.bat'). Extensions can include white space but need to begin and end with a non-white-space character as leading and trailing white space will be removed. The asterisk (*) character matches any non-empty extension, making all other entries in the list irrelevant. It must not be used as a wildcard to define a group of extensions! So, when the whitelist is set to an asterisk then any file with a file extension is allowed. If the blacklist is set to an asterisk, then only files without a file extension are allowed.
A Max File Size value of 0 means that no file size checks are carried out. Files which have already been stored in the system are not affected by changes in the Upload Restrictions properties.
How files are stored within the system
The file itself is stored in the MongoDB repository using the MongoDB GridFS specification. This has advantages over other MongoDB specifications as it does not run up against the size constraints for sending and receiving that are in place for other document types (for example the BSON documents used in the standard System Data Stores). Zero-length files are also allowed.
The file pointer property itself displays only the filename of the attached file.
Metadata
A File Pointer Property has accompanying metadata that contains a link (or 'pointer') to the actual stored file as well as information related to the file (such as the file name). This metadata can also contain custom user data.
For properties of the Filelist type the filename in the metadata is used to uniquely identify files.
| While the size of the actual file is virtually unlimited, the accompanying metadata is limited to 512 MB (this size limitation applies to all BSON documents exchanged between the Core and its clients (or in Store and Forward). |
| Metadata can be used in mass config scripts. However, the file digest is not guaranteed to be present when the script is executed and hence the actual file content might be lost |
Lua API functions - File Pointer Properties
As described above, file pointer properties consist of the binary file data itself and associated metadata.
File operations are synchronous and may take a long time. Clients are advised to execute such operations asynchronously, e.g. by using dedicated threads.
Support for file pointer properties is currently provided through the following Lua API functions:
See the associated Lua function documentation for more details on the table schema for file pointer properties and how to access them using the Lua API.