File Service
This service is intended for blob storage and can store different files as binary data and metadata.
Last updated
This service is intended for blob storage and can store different files as binary data and metadata.
Last updated
This service is intended for blob storage and stores files as binary data together with metadata. You can use this service to store files like e.g. CT-scans, ECG recordings, pdf reports, log files, ... and much more. You can access uploaded files directly from within your frontend applications.
Tip: If you need to store structured data we recommend that you take a look at our Data Service. This service has additional features to define actions when your data changes.
Uploading new files to the file service is easy. You can use our Javascript SDK and examples provided below or use our REST API by visiting our OpenAPI Specifications
For each file you upload, the service will store metadata and one or more associated tokens. These tokens can be used afterwards to retrieve the file binary data and metadata.
The size of the files you can upload is limited for performance and user experience reasons. Please visit our Usage and Performance page for more information and what's needed in case you need a limit increase.
You will receive a response representing the metadata of the file. The service generates one token object granting full access. The customer’s application must store the included token for future access to the file's binary data and metadata. Subsequently, this (and any other) full-access token can be used by the customer’s application to generate additional full-access or read-only token objects.
Tip: The customer’s application can link these tokens to other entities that provide context to the files. For example, documents in the Data Service can have a reference to “attachment(s)” that are stored in the File Service.
Field | Type | Description |
---|---|---|
While utilizing the SDK to upload a file, developers have the capability to monitor the upload progress. This can be achieved by creating an upload progress callback within the host application and passing it as an option to the SDK.
The upload progress callback should receive an object with two properties: loaded
and total
. These parameters represent the amount of data that has been uploaded and the total size of the file being uploaded, respectively. Both values are measured in Bytes. Developers can then calculate the upload percentage based on these input parameters, according to their specific requirements.
The upload progress callback is supported for browser applications only
Files and their metadata can be retrieved with either a read-only or full-access token.
Using a file token that is attached to the file you can retrieve the content of that specific file.
This example will retrieve the file and will return to you a Buffer with the binary data.
You can use the retrieveStream
function in case you are working with streams.
When a user has read-only access, this function does not return the tokens attribute of the FileMetaData object.
You can use the following function to retrieve the metadata of a file.
Any user can add a file, but files can only be removed by means of a token with a full access level. This action results in removing the binary data, the FileMetadata object, and all associated tokens
Deleted files will permanently remove the file from our service. There will be no way to revive the file after this action is performed.
Files and their metadata can be accessed via multiple, unique access tokens. This provides you with two advantages:
Different users do not have to share the same token, access to one user can be denied easily without removing access for the other users.
Tokens can grant different levels of access, enabling the owner of a file to safely invite other users to view but not remove their data.
Managing the tokens associated with a FileMetadata object requires a token that grants full access to that specific file. This can be the initial token, or any full-access token created later on. The number of (read-only or full-access) tokens that can be generated is unlimited. Deleting a token object renders the token stored by the customer’s application invalid.
As discussed, tokens can receive different access levels. currently there are two access levels defined.
Requires a token with full a full access level
Requires a token with full a full access level
In the request to delete a token, token
and tokenToDelete
can have the same value as long as at least one other Token object with full access remains associated with the FileMetaData. This prevents that a File becomes inaccessible.
This request provides a list of the available FileMetadata objects, including the corresponding tokens. It can be used by an administrator, for example to regain access to a File when tokens are lost.
Retrieving a list of uploaded files is only intended for Administrator use. Only users with the global VIEW_FILES permission can use the following functions.
Using Resource Query Language (RQL) you can search for files with specific tags or other attributes.
If you need to find a file with a specific fileName you can use the findByName function.
When your query is intended to find one file you can ask the SDK to return the first result.
With the global VIEW_FILES
permission, a user gets access to all attributes of each FileMetadata
object in the system, including the tokens. The latter can be used to retrieve or remove the actual file, i.e. the binary data. Grant this permission to a specific Role with caution.
Available since v1.1.0
The File Service has some general settings that can be used to change the behaviour of the service.
By default the File Service enforces files to be downloaded rather than displayed in a browser, preventing potential XSS vulnerabilities.
You can allow specific MIME types to be displayed in a browser by adding them to the disableForceDownloadForMimeTypes
setting.
The value "*/*"
can be used to allow any file to be displayed by browsers, but we strongly advise against it.
Field | Type | Description |
---|---|---|
Access level | Description |
---|---|
name
string
The name of the file
mimeType
string
An identifier existing of two parts used to represent the format of the file. E.g. "application/pdf" or "text/csv". The service derives the type from the user agent if not provided during the upload.
creatorId
string
The userId of the user who created or uploaded the file.
size
number
The size of the file represented by the number of bytes.
tags
string[]
A list of strings or tags that can be used to annotate a file.
tokens
Token[]
A list of tokens attached to the file.
creationTimestamp
string
A string in date-time notation of when the file was uploaded or created in the service.
updateTimestamp
string
A string in date-time notation of when the file was last updated.
token
string
The string token that can be used to access the file
accessLevel
string
The access level of the token. Can be full
or read
full
Provides permission to read, remove and manage tokens for the file.
read
Provides only permission to read the file