The File Management Service (FMS) is a storage service that allows you to create and store files within the Platform. You can use FMS to store and protect any data for a wide range of use cases such as licenses, invoices, warehouse receipts, Participant documents, billing, etc.
FMS provides management features so that you can organize your data, configure access to your data to meet your compliance requirements and provide a searchable database for quick retrieval.
You can store documents or URLs of documents on the Platform using FMS. It could be any file format, e.g. text, pdf, doc, audio, or video. Within FMS, you can store tags with documents that allow you to search for files in the file store. A tag consists of a tag key and a tag value. Tag keys and tag values are both required, but tag values can be empty (null) strings. For example, the key might be CONSIGNEE, and the value might be ADDRESS.
The files are organized in folders and stored either as a file on the Platform or as a link to a file stored elsewhere. Files are assigned a document ID that you use to retrieve the file. To retrieve the file you are sent a presigned link that has a configurable expiration time.
The following features are supported by the File Management Service:
Please note that File Management API requests that exceed the 375KB size limit will be rejected. Avoid passing large payloads to prevent exceeding this limit.
To create a folder, call the Create Folder endpoint and pass the following values in the request body.
A name for the folder that is unique within the Tenant.
The description of the folder.
Specifies a callback URL that is used to notify the calling of the result status of the call.
Length of time, in minutes, that the file download link is valid. Default value: 15
example: 22h 40m 3s
Request bodies are specified in JSON format. The following example shows a request body to create a folder:
The File Management Service allows you to add documents to the file store in two ways:
- File upload: Send the file in the multipart-form-request or provide the file data in binary format.
- URL upload: Supply a URL where the document is originally stored.
After uploading the file, the service generates a UUID to use as the document ID and returns it in the response. The file is asynchronously uploaded on a separate thread. In the case of a URL, the URL is stored in FMS and a document ID is generated and returned in the response.
Some metadata (name, description, tags, etc.) is stored along with the file and URL. Files are stored asynchronously and the status of the file upload is returned by the callback.
The callback is provided as part of folder creation.
To store a file in the File Management Service, call the Upload File endpoint.
Request bodies are specified in JSON format. The following example shows a request body to store a link to a file:
Valid values: FILE, LINK
Includes tag key and tag value.
The documents are retrieved from FMS by their IDs.
If the file is stored in FMS then the download is provided by a pre-signed link is provided. Users can download files using a pre-signed link. The presigned link will have one expiry time and if the link is expired, the user has to again make a call to get a new presigned link to download.
🚧 Note regarding expiry time:
The expiry time mentioned above is a property of the folder. Users have the option to configure it while creating a folder or by updating the folder property.
- If only the file URL is stored then during download file URL can be returned directly.
FMS provides features for auditing and managing access to your data. Access management is handled through Authentication And Authorization Service (AAA) integration. Since files are stored inside folders, you can provide access to folders for uploading or downloading files by creating resources and permissions in AAA.
When you upload a file, you have the option to add a tag along with it. These tags can be used to search and filter uploaded files. During the search, matching files or URL metadata is exposed to you. After that, you can download the file based on your ID.
For one tag there can be multiple docs available. During the search, the metadata for all matching documents is sent. After searching based on a tag, you are sent the metadata but you'll not be able to view the file content yet.
To view the content of the file, you need to make a separate request to download the file. After making a download request, you are checked for download access. If you have access, the file is downloaded and can be viewed.