Skip to main content
Version: 8.7 (unreleased)

Document handling

Store, track, and manage documents in Camunda 8 using the Camunda 8 API, Connectors, Forms, and Tasklist.

Offering more robust document handling capabilities within Camunda SaaS and Self-Managed, users can now efficiently manage large volumes of binary data such as PDFs and images across both development and production environments.

Storage integration and configuration​

There are several storage options:

  • A Google Cloud Platform bucket storage integration is configured for SaaS and handled by Camunda.
  • Use AWS S3 storage and bucket creation per cluster to securely store and retrieve documents in an external, scalable storage solution for Self-Managed, and to ensure storage is properly isolated and managed for each environment.
  • Documents can be stored in local folders, but this is not supported for production environments.
  • Documents can be stored in memory. If the application is stopped, the document will be lost. This is not supported for production environments.
note

GCP and AWS work with SaaS, and are supported for Self-Managed in production. Camunda does not provide local or in-memory for SaaS, but Self-Managed users may configure in-memory and local storage using Camunda 8 Run.

note

If no configuration is provided, the default document storage is in-memory. To change this to a different storage method, use the environment variables in the section below for every component using document handling. No additional configuration is required for in-memory storage.

To set what storage should be used, accepted values for DOCUMENT_DEFAULT_STORE_ID are aws, in-memory, gcp (for Google Cloud Platform), and local-storage.

Credentials variableDescription
AWS_ACCESS_KEY_IDAccess key ID used to interact with AWS S3 buckets.
AWS_REGIONRegion where the bucket is.
AWS_SECRET_ACCESS_KEYThe AWS secret access key associated with the AWS_ACCESS_KEY_ID. This will be used to authenticate.
Store variableDescription
DOCUMENT_STORE_AWS_BUCKETSpecifies the name of the AWS S3 bucket where documents are stored.
DOCUMENT_STORE_AWS_BUCKET_PATHDefines the folder-like path within the S3 bucket where documents are stored. This helps organize files within the bucket. For example, documents/invoices.
DOCUMENT_STORE_AWS_BUCKET_TTLRepresents the time-to-live (TTL) for documents stored in the S3 bucket. This could be used to set an expiration policy, meaning documents will be deleted automatically after a specified duration.
DOCUMENT_STORE_AWS_CLASSio.camunda.document.store.aws.AwsDocumentStoreProvider

Limitations​

  • One bucket per cluster is permitted with SaaS.
  • This storage integration is handled and configured by Camunda. While this is not dynamically configurable by the cluster, it is provided as environment configuration.
  • Maximum upload size for one or multiple files: 10 MB
  • File expiration time/time-to-live (TTL) policy: 30 days by default. Clients for Connectors and Forms may specify a custom expiration date when uploading documents.

Use cases and capabilities​

Document handling may be beneficial for several use cases. For example:

Upload a document via inbound webhook Connector​

Access created documents in both the response expression and the result expression, where the documents object contains the references for created documents. Below, review an example of a webhook configuration:

example payload inbound webhook connector

The document reference received as an output of one Connector should be stored in process variables by using the result expression or result variable.

To call the webhook sending a file, for example:

curl --location 'https://lpp-1.connectors.dev.ultrawombat.com/e424e404-39d2-4dcf-9937-a1ebde177d7c/inbound/uploadDocument' \
--form 'file=@"/path-to-file/file.pdf"'

The result variable will have the following structure:

{
 "request": {
   "body": {},
   "headers": {
     "host": "lpp-1.connectors.camunda.io",
     "x-request-id": "335843238a709273200e2055f89147ad",
     "x-real-ip": "109.78.172.42",
     "x-forwarded-host": "lpp-1.connectors.camunda.io",
     "x-forwarded-port": "443",
     "x-forwarded-proto": "https",
     "x-forwarded-scheme": "https",
     "x-scheme": "https",
     "content-length": "70484",
     "user-agent": "PostmanRuntime/7.43.0",
     "accept": "*/*",
     "cache-control": "no-cache",
     "postman-token": "b9d78973-b33f-43a4-8d55-c5ac8b2de656",
     "accept-encoding": "gzip, deflate, br",
     "content-type": "multipart/form-data; boundary=--------------------------300742796701946745140414"
   },
   "params": {}
 },
 "connectorData": {},
 "documents": [
   {
     "storeId": "gcp",
     "documentId": "130ad52a-f90a-4e07-9cfa-0d9abb0b6a68",
     "contentHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     "metadata": {
       "contentType": "application/pdf",
       "size": 70266,
       "fileName": "file.pdf"
     },
     "camunda.document.type": "camunda"
   }
 ]
}

Here, we use the configuration of the image on the initial steps and assign the portion containing the documents to userApplicationForms. This can be later used by the process to retrieve documents. For example, we could use the variable userApplicationForms to display the uploaded document in a user task using the document preview component.

Another Connector can also use this variable as an input. The format of inputs will depend on the Connector, as each Connector has a different input structure. Review the list of outbound Connectors below which currently support retrieving the document content to store in a third-party system.

Upload a document via form​

A form can display documents with the document preview component:

document preview settings

With the filepicker form element, you may also upload multiple files at once. This can be dynamically set using an expression:

document preview for form

For additional guidance on supported file formats, refer to the MDN Web Docs.

With Tasklist, users may then view and download files displayed in the task's form.

note

This feature will not work for public processes started by forms.

document handling in tasklist

Outbound Connectors​

The Connector SDK is enhanced to provide document support in property/variable bindings.

In most cases for the following outbound Connectors, you can include a Request body under Payload in the properties panel to send with your request:

example REST configuration

ConnectorDocument handling support
RESTSupports storing the response as a document.
EmailSupports sending Camunda documents as attachments, or storing incoming attachments as Camunda documents. These documents are automatically stored in the Camunda document store and available to map in the result expression.
Amazon TextractCan read the input document directly from the Camunda document store. Review the Document field in the properties panel where the document reference can be provided.
Amazon BedrockSupports consuming documents as inputs for conversations. Review the Document field in the properties panel where the document reference can be provided.
Amazon S3Supports uploading documents from (or downloading documents to) the Camunda document store. Review the Document field in the properties panel where the document reference can be provided.
BoxSupports uploading documents from (or downloading documents to) the Camunda document store. Review the Document field in the properties panel where the document reference can be provided.