OS1 Services
File Management Service
20min
overview 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 use cases 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 using fms service 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 creating a folder 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 storing files 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 note the callback is provided as part of folder creation downloading files 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 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 searching files 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 managing and accesing files 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 configuring ttl (time to live) 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 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 json examples create folder 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 sample request request bodies are specified in json format the following example shows a request body to create a folder request { "name" "string", "description" "string", "callback" "https //fms requestcatcher com/test", "defaulturlexpiry" "22h 40m 3s", "ttlindays" 30 } sample response response { "data" { "id" "folder\ c59f0bcb 5f9b 43b5 b6d2 73b93c17caa2" }, "request" { "uri" "string", "querystring" "string", "body" {}, "method" "post" } } upload file to a folder to store a file in the file management service, call the upload file endpoint 📘 note 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 sample request the following example shows a request body to store a link to a file upload file request body { "file" { "type" "link", "data" "http //example fxtrt io" }, "description" "file description", "tags" \[ { "key" "name", "value" "default" } ], "filename" "test file" "id" "string" } sample response response { "data" { "id" "file\ c59f0bcb 5f9b 43b5 b6d2 73b93c17caa2" }, "request" { "uri" "string", "querystring" "string", "body" {}, "method" "post" } } limitation 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 api reference documentation for detailed information on the fms service apis, including endpoints, request/response formats, and additional configuration options, refer to the api documentation