facilioo does not store file contents directly within its API or database. Instead, it provides pre-signed, time-limited URLs for uploading and downloading files. These URLs enable secure and efficient direct interaction with the underlying file storage (typically AWS S3) without routing file data through the facilioo backend.

File Types

Files are classified by type, which is part of the system’s API and managed as relatively static data. Examples include PDF documents, images, and other formats. File types can be fetched via the API to ensure correct categorization when creating or updating file metadata.

Flows

There are different flow possible in terms of files. Essentially, they behave all very similar, as the API builds the bridge between the client and the actual file storage. Furthermore, it maintains a metadata shell to link files to documents, process feeds, etc.

Uploading Files

The file upload process consists of several steps:

Obtain File Type ID: Retrieve the file types available in the system via API to identify the appropriate type for your file (e.g., PDF → id = 1).
Create File Metadata: Create a new File entity in facilioo via the API, including details such as the original file name, file type, and optional external identifiers.
Request Upload URL: Call the endpoint PUT /api/files/{id}/upload to obtain a pre-signed, time-limited upload URL. This URL is not an API endpoint but a direct, authorized link to the external file storage.
Upload File: Use the obtained upload URL to upload your file via an HTTP PUT request directly to the storage service.

📘
Note
To ensure uniqueness and privacy, filenames are hashed before storing in the external file storage system.

Downloading Files

For file retrieval, facilioo provides time-sensitive download URLs:

You can request a download URL via the API, which grants temporary, secure access to the file in external storage.
This mechanism ensures efficient delivery without the file passing through the API servers.
Download URLs expire after a short period to maintain security.

Thumbnails and Image Support

For image file types, facilioo automatically generates thumbnails. Hint: This is a background service, so be sure to fall back to the primary image, if the thumbnail is not available (yet).
Thumbnail URLs are similarly time-limited and can be retrieved through the API.
These thumbnails enable quick previews in the UI without requiring full file downloads.

Security and Authorization

All upload and download URLs are time-sensitive and unique per request to prevent unauthorized access.
Files are always associated with metadata entities linking them to parties, units, contracts, or other domain objects.
Access to file URLs respects the system’s access control and sharing settings.

Computed File Metadata

fileSize and pageCount are computed automatically by facilioo after a file has been uploaded. This applies to both new uploads as well as re-uploads for the same file id, either by obtaining a new or by re-using a still valid pre-signed upload URL.

These fields are not part of the upload request and are populated asynchronously based on storage events.

Clients should treat these fields as read-only.

If fileSize or pageCount are missing, this usually indicates corrupted files.

Content Type Handling

When uploading files via a pre-signed S3 URL, providing the correct Content-Type header is essential.

The file type selected when creating a file in facilioo determines:

the file extension used when downloading the file
how the file is expected to be opened later

facilioo does not infer the file type from the uploaded binary. Instead, it relies on:

the file type chosen during file creation
the Content-Type header provided during upload

A mismatch between file type in facilioo and the content type header used when uploading may result in incorrect downloads or files that cannot be opened reliably.

Troubleshooting

Missing fileSize or pageCount

If fileSize or pageCount are missing:

Verify that the upload was completed successfully
Ensure the correct Content-Type header was properly used during upload

Re-uploading the same file might solve the problem, but is usually not required and not recommended.

File cannot be opened correctly

In most cases, this is caused by a mismatch between the file type defined in facilioo while creating a File entity, the Content-Type header used during upload, and the actual file type of the file uploaded.

Example 1: PDF created, image uploaded

A file is created in facilioo as a PDF, but an image is uploaded.

Result:

The file is downloaded with a .pdf extension
The response uses an image content type

Whether the file opens correctly depends on the client application.

Example 2: PDF uploaded with wrong content type

A valid PDF is uploaded, but with an incorrect content type (e.g. application/json).

Result:

The file is downloaded as .pdf
The response uses the incorrect content type

Some viewers may fail to open the file or interpret it incorrectly.