Document Management - `endpoints

Document Management exposes upload, download and list file endpoints. Endpoints are registered automatically on start-up.

For server code, it also provides a file existence check, an event sent after each file expiry sweep, and events that change a file's expiry.

File upload

To upload a file, send a multiform POST request to the following resource path: /file-server/upload.

To construct a multiform POST request, you must provide a key for the form data, and a value (the file content). The headers must also be set correctly:

Content-Type : multipart/form-data
Content-Disposition : filename=<filename>

If you are using an HTTP testing tool like Postman, it should set these header values for you.

File download

To download a file, send a GET request to the following resource path with the following query param /file-server/download?fileStorageId=<fileStorageId>.

List all files

To list all files, send a GET request to /file-server/all-files. This requires the FileStorageAdminAction right.

Checking whether files exist

Server code can check whether a set of files still exists in Document Management. Call checkFileExistence on FileStorageClient:

val fileStorageClient = inject<FileStorageClient>()

val existence: Map<String, FileExistenceStatus> =
    fileStorageClient.checkFileExistence(setOf(firstFileStorageId, secondFileStorageId), userName)

When Document Management runs in another process, this sends a REQ_FILE_EXISTENCE request to the process that hosts Document Management (FILE_MANAGER, or a compact process). When Document Management is on this process's classpath, the client reads FILE_STORAGE directly. The check reads the FILE_STORAGE records only, not the stored files. The result contains one entry for each requested id:

Status	Meaning
FOUND	The file exists.
NOT_FOUND	Document Management confirmed that the file does not exist.
AMBIGUOUS	No answer was obtained for this id. For example, Document Management could not be reached or the request failed.

Treat a file as gone only when its status is NOT_FOUND. Never treat AMBIGUOUS as missing.

Expiry sweep completed event

After each file expiry sweep, Document Management sends EVENT_FILE_STORAGE_EXPIRY_SWEEP_COMPLETED with empty DETAILS. The Reporting component handles this event to mark reports whose files have expired.

The event is sent once, to the process that serves it. If no process serves it, nothing is sent. A failed delivery is logged as a warning and does not affect the sweep, whose deletions have already been made.

Changing a file's expiry

Server code can change the expiry of a saved file with EVENT_FILE_STORAGE_UPDATE_EXPIRY_INTERNAL. Users with the FileStorageUpdateExpiry or FileStorageAdminAction right can send EVENT_FILE_STORAGE_UPDATE_EXPIRY. Both take a FILE_STORAGE_ID and an EXPIRES_AT date and time.

Always include EXPIRES_AT. Send it as null to clear the expiry. See File expiry.

Linking assets

To link assets (css, image files etc...), you need to define an eventHandler codeblock. This must insert one or more objects into the TemplateAsset table. Use the following as an example.

    data class LinkTemplateAssets(
      val templateId: String,
      val assetIds: List<String>
    )

    eventHandler<LinkTemplateAssets>(name = "LINK_TEMPLATE_ASSETS") {
        onCommit { event ->
            val details = event.details

            val templateAssets = details.assetIds.map {
                TemplateAsset {
                    templateId = details.templateId
                    assetId = it
                }
            }

            entityDb.insertAll(templateAssets)
            ack()
        }
    }

Once your event handler is registered, and you have uploaded both the template and asset file(s), you can send a POST request to EVENT_LINK_TEMPLATE_ASSETS with the following request body

{
  "MESSAGE_TYPE": "EVENT_LINK_TEMPLATE_ASSETS",
  "USER_NAME": "<USER_NAME>",
  "DETAILS": {
    "TEMPLATE_ID": "<templateId>",
    "ASSET_IDS": ["assetId","assetId"]
  }
}