Skip to main content
Version: 8.8 (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 variableRequiredDescription
AWS_ACCESS_KEY_IDYesAccess key ID used to interact with AWS S3 buckets.
AWS_REGIONYesRegion where the bucket is.
AWS_SECRET_ACCESS_KEYYesThe AWS secret access key associated with the AWS_ACCESS_KEY_ID. This will be used to authenticate.
Store variableRequiredDescription
DOCUMENT_STORE_AWS_BUCKETYesSpecifies the name of the AWS S3 bucket where documents are stored.
DOCUMENT_STORE_AWS_BUCKET_PATHNoDefines the folder-like path within the S3 bucket where documents are stored. This helps organize files within the bucket. For example, documents/invoices. If not provided, the application logic assumes a default value of "".
DOCUMENT_STORE_AWS_BUCKET_TTLNoRepresents 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. If not provided, the application logic ignores this.
DOCUMENT_STORE_AWS_CLASSYesio.camunda.document.store.aws.AwsDocumentStoreProvider

Example:

AWS_ACCESS_KEY_ID=AWSACCESSKEYID
AWS_REGION=eu-north-1
AWS_SECRET_ACCESS_KEY=AWSSECRETACCESSKEYGOESHERE
DOCUMENT_STORE_AWS_BUCKET=test-bucket
DOCUMENT_STORE_AWS_BUCKET_PATH=test/path
DOCUMENT_STORE_AWS_BUCKET_TTL=5
DOCUMENT_STORE_AWS_CLASS=io.camunda.document.store.aws.AwsDocumentStoreProvider
DOCUMENT_DEFAULT_STORE_ID=aws

AWS API client permission requirements​

To ensure seamless integration and functionality of document handling with AWS services, the API client utilized must be configured with the appropriate permissions. The following AWS Identity and Access Management (IAM) permissions are necessary for the execution of operations related to document handling:

PermissionDescription
s3:ListBucketThis permission allows the application to verify it has access to the specified S3 bucket. Lack of this permission does not prevent the application from starting, but it logs a warning on application start-up.
s3:GetObjectThis permission is required to retrieve contents and metadata of objects from Amazon S3. The API client will utilize this permission to download or access the contents of the documents that have been uploaded to the bucket.
s3:PutObjectTo upload documents to an Amazon S3 bucket, the API client must have this permission.
s3:DeleteObjectThis permission authorizes the API client to remove objects from the specified S3 bucket.

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
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.
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.
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.
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.
Google DriveSupports document upload and download.
Microsoft TeamsSupports sending documents to channels.
RESTSupports storing the response as a document.
SendGridProvides attachment support.
SlackSupports adding attachments and increasing template versions.