Merge branch 'main' into meg-26598-spring-sdk-test

docs/apis-tools/spring-zeebe-sdk/configuration.md

@@ -245,7 +245,46 @@ public void handleJobFoo() {
 
 ## Additional configuration options
 
-### Execution threads
+For a full set of configuration options, see [CamundaClientConfigurationProperties.java](https://github.com/camunda/camunda/blob/main/clients/spring-boot-starter-camunda-sdk/src/main/java/io/camunda/zeebe/spring/client/properties/CamundaClientProperties.java).
+
+### Auth
+
+Authenticate with the cluster using the following alternative methods:
+
+#### Username & Password
+
+You can authenticate with the cluster using username and password authentication.
+
+```yaml
+camunda:
+  client:
+    mode: self-managed
+    auth:
+      username: <your username>
+      password: <your password>
+```
+
+#### Keystore & Truststore
+
+You can authenticate with the cluster using Java's Keystore and Truststore.
+
+```yaml
+camunda:
+  client:
+    mode: self-managed
+    auth:
+      keystore-path: <your keystore path>
+      keystore-password: <your keystore password>
+      keystore-key-password: <your keystore key password>
+      truststore-path: <your truststore path>
+      truststore-password: <your truststore password>
+```
+
+### Zeebe
+
+You can use the following Zeebe-specific additional configuration options:
+
+#### Execution threads
 
 The number of threads for invocation of job workers. Setting this value to 0 effectively disables subscriptions and workers (default 1):
 
@@ -256,7 +295,7 @@ camunda:
       execution-threads: 2
 ```
 
-### Message time to live
+#### Message time to live
 
 The time-to-live which is used when none is provided for a message (default 1H):
 
@@ -267,9 +306,9 @@ camunda:
       message-time-to-live: PT2H
 ```
 
-### Max message size
+#### Max message size
 
-A custom maxMessageSize allows the client to receive larger or smaller responses from Zeebe. Technically, it specifies the maxInboundMessageSize of the gRPC channel (default 4MB):
+A custom `maxMessageSize` allows the client to receive larger or smaller responses from Zeebe. Technically, it specifies the `maxInboundMessageSize` of the gRPC channel (default 4MB):
 
 ```yaml
 camunda:
@@ -278,7 +317,18 @@ camunda:
       max-message-size: 4194304
 ```
 
-### Request timeout
+#### Max metadata size
+
+A custom `maxMetadataSize` allows the client to receive larger or smaller response headers from Camunda:
+
+```yaml
+camunda:
+  client:
+    zeebe:
+      max-metadata-size: 4194304
+```
+
+#### Request timeout
 
 The request timeout used if not overridden by the command (default is 10s):
 
@@ -289,7 +339,7 @@ camunda:
       request-timeout: PT20S
 ```
 
-### CA certificate
+#### CA certificate
 
 Path to a root CA certificate to be used instead of the certificate in the default store:
 
@@ -300,7 +350,7 @@ camunda:
       ca-certificate-path: path/to/certificate
 ```
 
-### Keep alive
+#### Keep alive
 
 Time interval between keep alive messages sent to the gateway (default is 45s):
 
@@ -311,7 +361,7 @@ camunda:
       keep-alive: PT60S
 ```
 
-### Override authority
+#### Override authority
 
 The alternative authority to use, commonly in the form `host` or `host:port`:
 
@@ -322,7 +372,7 @@ camunda:
       override-authority: host:port
 ```
 
-### REST over gRPC
+#### REST over gRPC
 
 If true, the client will use REST instead of gRPC whenever possible:
 
@@ -333,7 +383,7 @@ camunda:
       prefer-rest-over-grpc: true
 ```
 
-### gRPC address
+#### gRPC address
 
 Define client gRPC address:
 
@@ -344,7 +394,7 @@ camunda:
       grpc-address: http://localhost:26500
 ```
 
-### REST address
+#### REST address
 
 Define client REST address:
 
@@ -355,7 +405,11 @@ camunda:
       rest-address: http://localhost:8080
 ```
 
-### Default task type
+#### Defaults and Overrides
+
+You can define defaults and overrides for all supported configuration options for a worker.
+
+##### Default Task type
 
 If you build a worker that only serves one thing, it might also be handy to define the worker job type globally and not in the annotation:
 
@@ -367,7 +421,7 @@ camunda:
         type: foo
 ```
 
-### Configure jobs in flight and thread pool
+##### Configure jobs in flight and thread pool
 
 Number of jobs that are polled from the broker to be worked on in this client and thread pool size to handle the jobs:
 
@@ -380,13 +434,11 @@ camunda:
       execution-threads: 1
 ```
 
-For a full set of configuration options, see [CamundaClientConfigurationProperties.java](https://github.com/camunda/camunda/blob/main/clients/spring-boot-starter-camunda-sdk/src/main/java/io/camunda/zeebe/spring/client/properties/CamundaClientProperties.java).
-
 :::note
 We generally do not advise using a thread pool for workers, but rather implement asynchronous code, see [writing good workers](/components/best-practices/development/writing-good-workers.md) for additional details.
 :::
 
-### Disable worker
+##### Disable worker
 
 You can disable workers via the `enabled` parameter of the `@JobWorker` annotation:
 
@@ -426,7 +478,7 @@ camunda:
         enabled: false
 ```
 
-### Overriding `JobWorker` values via configuration file
+##### Overriding `JobWorker` values via configuration file
 
 You can override the `JobWorker` annotation's values, as you can see in the example above where the `enabled` property is overridden:
 
@@ -454,7 +506,7 @@ camunda:
 
 You could also provide a custom class that can customize the `JobWorker` configuration values by implementing the `io.camunda.zeebe.spring.client.annotation.customizer.ZeebeWorkerValueCustomizer` interface.
 
-### Enable job streaming
+##### Enable job streaming
 
 Read more about this feature in the [job streaming documentation](/apis-tools/java-client/job-worker.md#job-streaming).
 
@@ -479,7 +531,7 @@ camunda:
           stream-enabled: true
 ```
 
-### Control tenant usage
+##### Control tenant usage
 
 When using multi-tenancy, the Zeebe client will connect to the `<default>` tenant. To control this, you can configure:
 

docs/components/concepts/document-handling.md

@@ -0,0 +1,60 @@
+---
+id: document-handling
+title: "Document handling"
+description: "Learn more about integration, secure management, and efficient storage and retrieval of documents across development and production environments."
+keywords: ["document handling"]
+---
+
+Offering a more comprehensive approach to document handling, Camunda now provides efficient storage and retrieval of documents across both development and production environments.
+
+Whether you are working across Connectors, Modeler, or Tasklist, document handling may be beneficial for users who want the following:
+
+- Use the default cloud storage to support, track, and manage documents.
+- [AWS S3](https://aws.amazon.com/s3/) storage and bucket creation per cluster to securely store and retrieve documents in an external, scalable storage solution, and to ensure storage is properly isolated and managed for each environment.
+- Support for the local file system as a storage option for development and testing purposes to set up and manage documents in local environments.
+
+## Modeler
+
+A [form](/components/modeler/forms/camunda-forms-reference.md) can display documents with the [document preview component](/components/modeler/forms/form-element-library/forms-element-library-document-preview.md):
+
+![document preview for form](./assets/document-preview.png)
+
+With the [filepicker form element](/components/modeler/forms/form-element-library/forms-element-library-filepicker.md), you may also [upload multiple files at once](/components/modeler/forms/form-element-library/forms-element-library-filepicker.md#configurable-properties). This can be dynamically set using an [expression](/components/modeler/feel/language-guide/feel-expressions-introduction.md).
+
+## Connectors
+
+### Inbound (webhook) Connectors
+
+[Access created documents](/components/connectors/protocol/http-webhook.md) in both the response expression and the result expression, where the `documents` object contains the references for created documents.
+
+![example payload inbound webhook connector](./assets/inbound-webhook-document.png)
+
+### Outbound Connectors
+
+For the following outbound Connectors, you may include a **Request body** under **Payload** in the properties panel to send with your request:
+
+- [REST](/components/connectors/protocol/rest.md) - Supports storing the response as a document.
+- [Email](/components/connectors/out-of-the-box-connectors/email.md) - Supports sending Camunda documents as attachments, or storing incoming attachments as Camunda documents.
+- [Amazon Textract](/components/connectors/out-of-the-box-connectors/amazon-textract.md) - Can read the input document directly from the Camunda document store.
+- [Amazon Bedrock](/components/connectors/out-of-the-box-connectors/amazon-bedrock.md) - Supports consuming documents as inputs for conversations.
+- [Amazon S3](/components/connectors/out-of-the-box-connectors/amazon-s3.md) - Supports uploading documents from (or downloading documents to) the Camunda document store.
+- [Box](/components/connectors/out-of-the-box-connectors/box.md) - Supports uploading documents from (or downloading documents to) the Camunda document store.
+
+![example REST configuration](./assets/rest-outbound-document.png)
+
+## Tasklist
+
+Tasklist users may view and download files displayed in the task's form.
+
+:::note
+If you change the **Document URL** under **Download settings**, this feature will not work for public start forms because there is no valid session.
+:::
+
+![document preview settings](./assets/document-preview-settings.png)
+
+## Document limitations
+
+Document handling maintains the following guidelines:
+
+- **Maximum file size**: 10 MB per file.
+- **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.

docs/components/connectors/out-of-the-box-connectors/amazon-bedrock.md

@@ -126,3 +126,7 @@ The current implementation supports the assistant's responses only in text forma
 :::
 
 Ideally, the message's history must transit within the process and be the input of this `Converse` task with the new message.
+
+:::note
+Starting from version 8.7.0, the Amazon Bedrock Connector supports consuming documents as inputs for conversations. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::

docs/components/connectors/out-of-the-box-connectors/amazon-s3.md

@@ -92,6 +92,10 @@ The following JSON response is returned after a successful document upload opera
 - `key`: Echoes back the unique key of the uploaded document.
 - `link`: The document link.
 
+:::note
+Starting from version 8.7.0, the Amazon S3 Connector supports uploading documents from (or downloading documents to) the Camunda document store. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::
+
 #### Example Response
 
 The following example shows a successful send upload operation response:

docs/components/connectors/out-of-the-box-connectors/amazon-textract.md

@@ -119,6 +119,10 @@ The response from the **Amazon Textract Connector** mirrors the AWS Textract ser
 - **[Polling Execution Response](https://docs.aws.amazon.com/textract/latest/dg/API_GetDocumentAnalysis.html#API_GetDocumentAnalysis_ResponseSyntax)**: Returns chunks of data in a paginated format for multi-page or complex documents.
 - **[Asynchronous Execution Response](https://docs.aws.amazon.com/textract/latest/dg/API_StartDocumentAnalysis.html#API_StartDocumentAnalysis_ResponseSyntax)**: Used for batch processing where results are returned later through job completion.
 
+:::note
+Starting from version 8.7.0, the Amazon Textract Connector can read the input document directly from the Camunda document store. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::
+
 ### Use the Textract Connector response in your process
 
 The **Amazon Textract Connector** provides the same response structure as the AWS Textract API. You can map fields from the response to process variables, depending on your needs.

docs/components/connectors/out-of-the-box-connectors/box.md

@@ -48,6 +48,10 @@ The Box Connector supports two methods for locating items stored in your Box acc
 
 :::
 
+:::note
+Starting from version 8.7.0, the Box Connector supports uploading documents from (or downloading documents to) the Camunda document store. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::
+
 ### Create Folder
 
 Creates a new folder in your store.

docs/components/connectors/out-of-the-box-connectors/email.md

@@ -126,6 +126,10 @@ The task returns a JSON object containing detailed information about the email:
 - `attachments`: A list of all the email's attachments, provided as a document reference.
 - `receivedDateTime`: The email's reception datetime
 
+:::note
+Starting from version 8.7.0, the email Connector supports sending Camunda documents as attachments, or storing incoming attachments as Camunda documents. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::
+
 #### Example Response
 
 Below is an example of the JSON response returned when a specific email is read:

docs/components/connectors/protocol/http-webhook.md

@@ -387,7 +387,7 @@ newly create process instance key when accessing the `correlation` object:
 
 You can access created documents in both the response expression and the result expression.
 
-The `documents` object contains the references for created documents.
+The `documents` object contains the references for created documents. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
 
 **Example response expression**
 

docs/components/connectors/protocol/rest.md

@@ -213,10 +213,6 @@ Secrets are currently not supported in the body of a **REST Connector**.
 
 ## Response
 
-:::note
-Starting from version 8.7.0, the REST Connector supports storing the response as a document.
-:::
-
 The HTTP response will be available in a temporary local `response` variable. This variable can be mapped to the process by specifying the **Result variable**.
 
 The following fields are available in the `response` variable:
@@ -234,6 +230,10 @@ The following fields are available in the `response` variable:
     - **customProperties**: Custom properties of the stored document.
     - **contentType**: Content type of the stored document.
 
+:::note
+Starting from version 8.7.0, the REST Connector supports storing the response as a document. See additional details and limitations in [document handling](/components/concepts/document-handling.md).
+:::
+
 ## Output mapping
 
 ### Result variable

docs/components/modeler/forms/form-element-library/forms-element-library-document-preview.md

@@ -28,3 +28,5 @@ A form element to select files.
 - **Document URL**: A context key which contains the URL value used to get each document. This can only be an [expression](../../feel/language-guide/feel-expressions-introduction.md). The resulting value must be a string and it must contain the placeholder `{documentId}` which will be replaced with the document ID present in the **Document reference** data. By default this component will use the key `defaultDocumentsEndpointKey`, if you leave this field unchanged it will work without any extra configuration on Tasklist and you won't have inject this variable in the process instance context.
 - **Hide if**: [Expression](../../feel/language-guide/feel-expressions-introduction.md) to hide the file picker.
 - **Max height of preview container**: A number which will define the maximum height of each document preview. Any document with a bigger height will display a scroll bar.
+
+Refer to [document handling](/components/concepts/document-handling.md) for additional details and limitations.

docs/components/modeler/forms/form-element-library/forms-element-library-filepicker.md

@@ -20,3 +20,5 @@ A form element to select files.
 - **Columns**: Space the field will use inside its row. **Auto** means it will automatically adjust to available space in the row. Read more about the underlying grid layout in the [Carbon Grid documentation](https://carbondesignsystem.com/elements/2x-grid/overview/).
 - **Validation**: Given that one of the following properties is set, the form will only submit when the respective condition is fulfilled. Otherwise, a validation error will be displayed.
   - **Required**: File picker must have a selected file.
+
+Refer to [document handling](/components/concepts/document-handling.md) for additional details and limitations.

docs/components/tasklist/userguide/using-tasklist.md

@@ -91,3 +91,13 @@ The follow-up date defines the latest time you should start working on a task. T
 The priority defines urgency of a task in relation to others.
 
 ![tasklist-task-ordering](img/tasklist-task-ordering.png "Order tasks by dates")
+
+## Document handling
+
+Tasklist users may view and download files displayed in the task's form.
+
+:::note
+If you change the **Document URL** under **Download settings**, this feature will not work for public start forms because there is no valid session.
+:::
+
+See additional details and limitations in [document handling](/components/concepts/document-handling.md).