File Management Service
The File Management Service (FMS) is a service that allows you to create and retrieve files. You can use FMS to store files for a wide range of use cases such as licenses, invoices, warehouse receipts, and so on.
FMS offers features for organizing files, configuring access to meet compliance requirements, and providing a searchable database for quick retrieval of files. You can store both documents and URLs of various formats (e.g., text, PDF, audio, video) and assign tags to facilitate searching. Tags consist of a key-value pair, where both are required, though the value can be an empty string (e.g., key: CONSIGNEE, value: ADDRESS).
Files are organized in folders and can be stored directly as files or as links to external files. Each file is assigned a document ID for retrieval, and access is granted through a pre-signed link with a configurable expiration time.
- Folder Management: Create and organize folders..
- File Storage: Upload files directly or link to external URLs.
- FileRetrieval: Easily download documents using generated IDs.
- Access Management: Integrate with the Authentication and Authorization Service (AAA) for secure access control.
- File Searching: Utilize tags for efficient search and retrieval.
- Supported File Formats: FMS accepts multiple file formats including:
- Text
- PDF
- DOC
- Audio
- Video
- Tagging: Files can be tagged with key-value pairs to facilitate efficient searching. Tag values can be empty, but both keys and values are required.
File Storage: If you’re in logistics, you know how important it is to keep track of documents. Use FMS to store your shipping invoices, delivery receipts, and compliance papers. Just upload them, create folders, and tag everything so it’s easy to find later.
Short-term File Management: You often handle documents that are only needed for a limited time—like shipping details or time-sensitive contracts. With FMS, you can set a Time-to-Live (TTL) for these files, so they’re automatically deleted after a certain period. This keeps your storage organized and avoids clutter, ensuring you only keep what’s truly necessary.
Compliance and Audit: In logistics, staying compliant is a big deal. FMS lets you control who can see and edit sensitive documents. Set permissions for your team so only the right people have access. This is super important for audits and keeping everything secure.
File Retrieval: You generate a lot of data in logistics, and finding the right document fast is key. With FMS, you can tag and use metadata to search for documents easily. So when you need a purchase order or inventory list, you can grab it quickly without any hassle.
To utilize FMS, developers interact with its API endpoints for creating folders, storing documents, retrieving files, and managing access. Below are the key actions for integrating FMS into your application.
Before you create or upload files in FMS, it’s essential to create a folder to organize your files and data effectively.
FMS allows you to create a folder to organize your files and data:
- Specify Folder Details: When creating a folder, provide a unique name and a description to categorize the folder's contents.
- Optional Callback URL: You can include a callback URL to receive notifications about the folder creation status.
- Set Expiry and TTL: Optionally, configure a default URL expiry time for files in the folder and set a Time-to-Live (TTL) to automatically manage file retention.
After the folder is created, the service generates a unique identifier (ID) for the folder and returns it in the response. This ID can be used for future operations, such as uploading files or managing permissions. View Example.
FMS allows you to store files 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. View Example.
📘 NOTE
The callback is provided as part of folder creation.
The files 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
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 the file URL can be returned directly during the download.
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.
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.
With FMS, you can set a Time-to-Live (TTL) for files stored in folders, ensuring that temporary data is automatically cleaned up after a specified period. Here’s how to configure TTL:
- Set TTL During Folder Creation: When you create a folder, you can specify the TTL in days. For example, if you want files to be automatically deleted after 30 days, you would set the TTL to 30d in your API request.
- File Creation and Updates: When you upload files to the folder, FMS will automatically set the TTL based on the folder’s configuration. Each file will have its TTL based on the folder’s ttlInDays, ensuring that all files within that folder are subject to the same expiration rules.
- Automatic Cleanup: Once the TTL expires, the files will be automatically deleted from both FMS and associated storage (like S3). This helps you manage storage efficiently and ensures that old, unnecessary files don’t accumulate.
- Updating TTL: If you need to change the TTL for an existing folder, you can update it using the folder update API. However, this change will only apply to new files uploaded after the update; existing files will retain their original TTL unless individually updated.
📘 NOTE
If developers do not set a Time-to-Live (TTL) for files, those files will remain stored indefinitely. It's important to specify a TTL to ensure timely cleanup of unnecessary data.
To create a folder, call the Create Folder endpoint and pass the following values in the request body.
Parameters | Description | Validation | Data type |
name | A name for the folder that is unique within the Tenant. | pattern: [a-zA-Z0-9-_]{3,16}$ | string |
description | The description of the folder. | | string |
callback | Specifies a callback URL that is used to notify the calling of the result status of the call. | | string($uri) |
defaultURLExpiry (Optional) | Length of time, in minutes, that the file download link is valid. Default value: 15 | example: 22h 40m 3s | string |
ttlInDays | (Optional) Time-to-Live for folder files | Minimum: 1 day | integer |
Request bodies are specified in JSON format. The following example shows a request body to create a folder:
To store a file in the File Management Service, call the Upload File endpoint .
📘 NOTE
JSON FILE: Request Body should not exceed request size of 375 KB. MULTIPART FILE: File size should not exceed 2 MB.
Pass the following values in the request body.
Member | Description | Validation | Data type |
file>type | File type. | Valid values: FILE, LINK | string |
file>data | File data. | | string |
description | File description. | | string |
tags | Includes tag key and tag value. | | string |
fileName | File name. | | string |
id | id | | string |
The following example shows a request body to store a link to a file:
- The maximum request size is 375 KB, which means the total size of all the data you send in one request—like file data, descriptions, and tags—can’t exceed this limit. Ensure payloads remain within this limit to avoid rejection.
- The TTL value for folder files must be a minimum of 1 day.
For detailed information on the FMS Service APIs, including endpoints, request/response formats, and additional configuration options, refer to the API documentation.