@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.modeler.feel.cluster-variable.get-started.next-steps.md

@@ -0,0 +1,8 @@
+# Get started with cluster variables — Next steps
+
+Congratulations! You've successfully created and used your first cluster variable in a BPMN process.
+
+Now, [learn the fundamentals](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/overview#learn-the-fundamentals) and [explore further resources](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/overview#explore-further-resources).
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/get-started

package/.llms/chunks/components.modeler.feel.cluster-variable.get-started.step-2-override-for-a-specific-tenant.md

@@ -0,0 +1,52 @@
+# Get started with cluster variables — Step 2: Override for a specific tenant
+
+Now, create a tenant-specific override for your development environment. This allows you to use the same BPMN process in both environments without modifications.
+
+Replace `{tenantId}` with your actual tenant ID (for example, `dev-environment`):
+
+```bash
+POST /v2/cluster-variables/tenant/{tenantId}
+Content-Type: application/json
+
+{
+  "name": "PAYMENT_API_CONFIG",
+  "value": {
+    "endpoint": "https://api.payment.dev.example.com",
+    "timeout_ms": 30000,
+    "retry_count": 1
+  }
+}
+```
+
+**Note**
+Processes running in the `dev-environment` tenant automatically use the development API configuration, while all other tenants use the production configuration.
+
+
+## Step 3: Access the variable in Modeler
+
+Open Camunda Modeler and create or open a BPMN process. Add a service task to your process that calls the payment API.
+
+To use your cluster variable in a service task:
+
+1. Select the service task in your diagram.
+2. In the properties panel, navigate to the **Inputs** section.
+3. Add an input mapping.
+4. For the **Variable assignment value** field, enter the following FEEL expression to access the API endpoint:
+
+```
+= camunda.vars.env.PAYMENT_API_CONFIG.endpoint
+```
+
+5. For the **Local variable name** field, enter `apiUrl`. This creates a local variable for your service task.
+6. Add another input mapping for the timeout using the following expression:
+
+```
+= camunda.vars.env.PAYMENT_API_CONFIG.timeout_ms
+```
+
+7. Set the local variable name to `timeoutMs`.
+
+Your service task now has access to both the `apiUrl` and `timeoutMs` variables, which automatically resolve to the correct values based on whether the process runs in your production cluster or the development tenant.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/get-started

package/.llms/chunks/components.modeler.feel.cluster-variable.get-started.step-4-deploy-and-test-your-process.md

@@ -0,0 +1,16 @@
+# Get started with cluster variables — Step 4: Deploy and test your process
+
+1. Complete your BPMN diagram by adding any additional tasks and an end event.
+2. Click **Deploy** to deploy your process to the cluster.
+3. Create a process instance by clicking **Run** (or start it via API).
+4. Navigate to Operate to view your process instance.
+5. Inspect the process variables to see that the cluster variables were resolved correctly based on your tenant context.
+
+**What happens during execution**
+
+- If the process runs in the `dev-environment` tenant, it uses the development API endpoint (`https://api.payment.dev.example.com`) with a 30-second timeout.
+- If the process runs in any other context, it uses the production API endpoint (`https://api.payment.prod.example.com`) with a five-second timeout.
+- The BPMN file remains identical across all environments.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/get-started

package/.llms/chunks/components.modeler.feel.cluster-variable.metadata.md

@@ -0,0 +1,17 @@
+# Metadata
+
+Attach searchable key-value metadata to cluster variables so consumers can discover and filter them without inspecting their values.
+
+Attach searchable key-value metadata to cluster variables so consumers can discover and filter them without inspecting their values.
+
+
+## About metadata
+
+Each cluster variable can include optional metadata: a map of string keys to scalar values. Metadata is stored alongside the variable but kept separate from its `value`.
+
+You can use metadata to annotate variables with information that helps you find them. For example, you could annotate a cluster variable containing a country’s VAT rate with `category=TAX_RATE`, `region=EU`, and `year=2026`. You can then query for all tax rates for a given region and year without knowing the variables’ actual content.
+
+Camunda does not interpret metadata keys or values or assign meaning to missing metadata. You can provide empty metadata or omit it entirely.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/metadata

package/.llms/chunks/components.modeler.feel.cluster-variable.metadata.set-metadata.md

@@ -0,0 +1,26 @@
+# Metadata — Set metadata
+
+You can set metadata when creating or updating a cluster variable through the [Orchestration Cluster API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-global-cluster-variable.api). For example:
+
+```json
+{
+  "name": "DE_VAT_RATE",
+  "scope": "GLOBAL",
+  "value": { "rate": 0.19 },
+  "metadata": {
+    "category": "TAX_RATE",
+    "region": "EU",
+    "year": 2026
+  }
+}
+```
+
+Metadata is included in every get and search response.
+
+
+## Filter by metadata
+
+You can use the `metadata` filter to find cluster variables with specific metadata. For supported filters and request examples, see [search cluster variables](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-cluster-variables.api) in the Orchestration Cluster API reference.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/metadata

package/.llms/chunks/components.modeler.feel.cluster-variable.metadata.structure-and-constraints.md

@@ -0,0 +1,18 @@
+# Metadata — Structure and constraints
+
+When you add metadata to a cluster variable, it must meet the following requirements:
+
+- Keys must be strings.
+- Values must be **scalars (strings or numbers only)**. You cannot use booleans, arrays, or objects.
+- Metadata is limited to **100 entries** and and must not exceed the configurable maximum serialized size. By default, each key can contain up to 256 characters, and each value can contain up to 8,192 characters.
+
+The API rejects requests that exceed these limits or contain unsupported value types.
+
+
+## Metadata is not part of the runtime value
+
+Metadata is never exposed as part of the FEEL-accessible value. When a process evaluates `camunda.vars.env.<name>` (or the `cluster`/`tenant` namespaces), the expression resolves only to the variable's `value` field.
+Metadata keys are not included. See [how to use cluster variables](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/usage-guide) for FEEL access patterns.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/metadata

package/.llms/chunks/components.modeler.feel.cluster-variable.namespace-collisions.collision-types.md

@@ -0,0 +1,133 @@
+# Namespace collisions — Collision types
+
+The examples below show you common patterns and how to reason about them.
+
+### Process variable shadowing
+
+If you create a process variable using the cluster variable namespace, it completely shadows cluster variables.
+
+#### Scenario
+
+```
+GLOBAL: { API_ENDPOINT: "https://api.global.com" }
+
+Process Variable Created:
+camunda.vars.env.API_ENDPOINT = "https://api.override.com"
+```
+
+#### Result
+
+```
+camunda.vars.env.API_ENDPOINT → "https://api.override.com"
+```
+
+#### Why this happens
+
+Process variables [have the highest priority](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/scope-and-priority) in the resolution hierarchy. When you namespace a process variable under `camunda.vars.env`, it takes precedence over cluster variables.
+
+This allows intentional, runtime overrides of cluster configuration when necessary.
+
+**Tip**
+Use sparingly and document clearly. Prefer a different namespace for process variables to avoid confusion.
+
+### Structural collisions across scopes
+
+It happens when you define the same key with different data types or structures at different scopes.
+
+**Note**
+This is the most common source of unexpected behavior.
+
+#### Scenario
+
+```
+TENANT: { CONFIG_KEY: "simple string value" }
+GLOBAL: { CONFIG_KEY: { nested: "object", with: "properties" } }
+```
+
+#### Result
+
+```
+camunda.vars.env.CONFIG_KEY → "simple string value" (TENANT wins)
+camunda.vars.env.CONFIG_KEY.nested → null (trying to access property on string)
+```
+
+#### Why this happens
+
+Tenant scope has higher priority and returns a string, so the global object is never evaluated. Accessing properties on a string yields null.
+
+### Kind collisions across scopes
+
+A kind collision happens when the same key is defined at both scopes with a different [variable kind](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/data-types#variable-kinds).
+
+#### Scenario
+
+```
+GLOBAL: { API_CREDENTIALS: "camunda.secrets.PAYMENT_API_KEY" }  (kind SECRET_REFERENCE)
+TENANT: { API_CREDENTIALS: "camunda.secrets.PAYMENT_API_KEY" }  (kind JSON)
+```
+
+#### Result
+
+When an input mapping on a service task reads the key:
+
+```
+camunda.vars.env.API_CREDENTIALS
+→ the literal text "camunda.secrets.PAYMENT_API_KEY" (TENANT wins, kind JSON)
+
+camunda.vars.cluster.API_CREDENTIALS
+→ the resolved secret value (GLOBAL, kind SECRET_REFERENCE)
+```
+
+#### Why this happens
+
+Tenant scope has higher priority, so `camunda.vars.env` selects the tenant variable, and only that variable's kind is considered. A `JSON`-kind value is ordinary text, so its references are not resolved. The global variable's references are reachable only through `camunda.vars.cluster`, which bypasses tenant scope.
+
+This assumes the tenant variable has a non-empty value. If it's empty, `camunda.vars.env` skips it and falls through to global instead, so the global `SECRET_REFERENCE` variable wins — the opposite of the outcome above.
+
+To avoid this, give a key the same kind at every scope where you define it.
+
+### Detailed collision example
+
+#### Scenario
+
+```
+GLOBAL scope:
+{
+  KEY_1: {
+    KEY_2: "hello world",
+    KEY_3: "goodbye world"
+  }
+}
+
+TENANT scope:
+{
+  KEY_1: "tenant value"
+}
+```
+
+#### Results
+
+```
+camunda.vars.env.KEY_1
+→ "tenant value"
+✓ Works as expected, TENANT priority
+
+camunda.vars.env.KEY_1.KEY_2
+→ null
+✗ Unexpected! Trying to access property on string
+
+camunda.vars.cluster.KEY_1.KEY_2
+→ "hello world"
+✓ Bypasses TENANT scope, accesses GLOBAL directly
+
+camunda.vars.tenant.KEY_1
+→ "tenant value"
+✓ Direct TENANT access
+
+camunda.vars.tenant.KEY_1.KEY_2
+→ null
+✓ Correctly returns null (KEY_1 in TENANT is string)
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/namespace-collisions

package/.llms/chunks/components.modeler.feel.cluster-variable.namespace-collisions.md

@@ -0,0 +1,15 @@
+# Namespace collisions
+
+Understand namespace collisions in cluster variables, how scope priority affects variable resolution, and how to safely handle overrides to avoid unexpected behavior.
+
+Understand namespace collisions in cluster variables, how scope priority affects variable resolution, and how to safely handle overrides to avoid unexpected behavior.
+
+
+## About
+
+Namespace collisions occur when the same variable key is defined differently across scopes (process, tenant, global). While scope priority determines which value is used, mismatched data types or structures can cause unexpected results.
+
+This guide explains common collision types, shows real examples, and shares best practices to prevent or intentionally manage overrides.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/namespace-collisions

package/.llms/chunks/components.modeler.feel.cluster-variable.namespace-collisions.prevent-namespace-collisions.md

@@ -0,0 +1,71 @@
+# Namespace collisions — Prevent namespace collisions
+
+Avoid collisions by keeping structures consistent, separating fundamentally different data under different keys, and documenting what each key represents at each scope.
+
+### Keep data structures consistent
+
+Use the same data type and shape for a given key across all scopes.
+
+#### Example
+
+```
+GLOBAL: {
+  DATABASE_CONFIG: {
+    host: "global-db.example.com",
+    port: 5432,
+    timeout_ms: 5000
+  }
+}
+
+TENANT: {
+  DATABASE_CONFIG: {
+    host: "tenant-db.example.com",
+    port: 5432,
+    timeout_ms: 10000
+  }
+}
+```
+
+Both scopes use the same object structure, with tenant‑specific values.
+
+### Use distinct keys
+
+If the structures differ, store them under different keys to avoid type conflicts.
+
+#### Example
+
+```
+GLOBAL: {
+  DEFAULT_ENDPOINT: "https://api.global.com",
+  DEFAULT_CONFIG: { timeout: 5000, retry: 3 }
+}
+
+TENANT: {
+  TENANT_ENDPOINT: "https://api.tenant.com",
+  TENANT_CONFIG: { timeout: 10000, retry: 5, custom_header: "value" }
+}
+```
+
+### Detect collisions at runtime
+
+Add simple guards when accessing nested properties to avoid nulls if a higher‑priority scope supplies a different type.
+
+#### Example
+
+```
+if camunda.vars.env.CONFIG.nested_value != null
+  then camunda.vars.env.CONFIG.nested_value
+  else "default"
+```
+
+### Document your schema
+
+Maintain a schema registry or documentation that specifies:
+
+- Expected keys at each scope.
+- Data type and structure for each key.
+- Which keys can be overridden at the tenant scope.
+- Deprecation notices for keys being phased out.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/namespace-collisions

package/.llms/chunks/components.modeler.feel.cluster-variable.namespace-collisions.process-variable-namespace-best-practices.md

@@ -0,0 +1,24 @@
+# Namespace collisions — Process variable namespace best practices
+
+### Avoid using `camunda.vars` namespace
+
+To prevent shadowing cluster variables, avoid creating process variables that use the `camunda.vars` namespace.
+
+For example, instead of:
+
+```
+Set process variable: camunda.vars.env.TIMEOUT = 5000
+```
+
+Do:
+
+```
+Set process variable: processTimeout = 5000
+```
+
+### When override is intentional
+
+If you need to override a cluster variable at the process level, document the intent and scope in the process documentation so consumers understand why the override exists and where it applies.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/namespace-collisions

package/.llms/chunks/components.modeler.feel.cluster-variable.overview.get-started.md

@@ -0,0 +1,18 @@
+# Cluster variables — Get started
+
+Get started with cluster variables with the following tutorial.
+
+Create your first cluster variable
+
+
+## Learn the fundamentals
+
+Understand the fundamental concepts of cluster variables.
+
+
+## Explore further resources
+
+Dive into common use cases and the API documentation to extend your knowledge.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/overview

package/.llms/chunks/components.modeler.feel.cluster-variable.overview.md

@@ -0,0 +1,37 @@
+# Cluster variables
+
+Manage configuration values centrally across your Camunda cluster with cluster variables.
+
+Manage configuration values centrally across your Camunda cluster with cluster variables.
+
+
+## About
+
+Within your Camunda cluster, you can define [variables](https://docs.camunda.io/docs/next/components/concepts/variables) at two levels: globally for the entire cluster, or at the tenant level when multi-tenancy is enabled.
+
+Cluster variables allows you to maintain environment-specific configurations, API endpoints, feature flags, and other shared values without hardcoding them into individual process definitions.
+
+### Why use
+
+Cluster variables provide **centralized**, **flexible**, and **environment-aware configuration** for your processes. They allow you to:
+
+- Define configuration once and reuse it across multiple processes.
+- Use different values for development, staging, and production without changing BPMN models.
+- Support multi-tenant setups with tenant-specific overrides on top of global defaults.
+- Promote processes across environments without modifying process definitions.
+- Update configuration at runtime without redeploying.
+- Manage shared settings such as API endpoints and service URLs, feature flags, and integration credentials.
+
+### When not to use
+
+Consider alternatives for the following use cases:
+
+| Use case                                       | Recommended alternative          |
+| ---------------------------------------------- | -------------------------------- |
+| Process instance-specific data                 | Process variables                |
+| Values that change frequently during execution | Process variables                |
+| Sensitive credentials                          | Secrets management               |
+| Large payloads                                 | External storage with references |
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/overview

package/.llms/chunks/components.modeler.feel.cluster-variable.scope-and-priority.md

@@ -0,0 +1,41 @@
+# Scope resolution
+
+Learn how cluster variable scope resolution works, the available scopes, and how to access and use them.
+
+Learn how cluster variable scope resolution works, the available scopes, and how to access and use them.
+
+
+## About
+
+Cluster variables use a scope priority process to determine which value is used when the same key exists at multiple levels.
+
+This guide helps you understand this scope resolution to predict values in your processes and avoid unexpected behavior.
+
+
+## Scope levels
+
+Cluster variables exist at the **global** and **tenant** scope levels.
+
+### Global scope
+
+Variables defined at the global scope are available across the entire cluster and accessible by all processes, regardless of tenant context.
+
+**Info**
+Global-scope cluster variables are ideal for cluster-wide defaults and shared configuration.
+
+They have lowest priority in variable resolution and are managed via the global cluster variables API.
+
+### Tenant scope
+
+Variables defined at the tenant scope are specific to a particular tenant and only accessible within that tenant's context.
+
+**Note**
+Tenant-scope cluster variables are ideal for tenant-specific customization and overrides.
+
+They have higher priority than global-scope ones in variable resolution and are managed via the tenant-specific cluster variables API.
+
+**Important**
+They are available only when multi-tenancy is enabled.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/scope-and-priority

package/.llms/chunks/components.modeler.feel.cluster-variable.scope-and-priority.multi-tenant-considerations.md

@@ -0,0 +1,39 @@
+# Scope resolution — Multi-tenant considerations
+
+### Tenant isolation
+
+Each tenant's cluster variables are fully isolated. A process running in one tenant cannot access cluster variables defined for another tenant, even with explicit namespace access.
+
+### Global defaults pattern
+
+Define sensible defaults globally and override only what you need at the tenant level:
+
+```
+GLOBAL: {
+  RATE_LIMITS: {
+    requests_per_minute: 100,
+    burst_limit: 150,
+    concurrent_connections: 10
+  }
+}
+
+TENANT (premium): {
+  RATE_LIMITS: {
+    requests_per_minute: 1000,
+    burst_limit: 1500,
+    concurrent_connections: 100
+  }
+}
+```
+
+
+## Troubleshoot scope resolution
+
+1. **Check all three scope levels**: Verify values at global, tenant, and process levels.
+2. **Use scope-specific namespaces**: Test with `camunda.vars.cluster` and `camunda.vars.tenant` to isolate scope.
+3. **Verify tenant context**: Ensure the process is running in the expected tenant.
+4. **Look for shadowing**: Check for process variables that might shadow cluster variables.
+5. **Validate structure**: Ensure objects have consistent structure across scopes.
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/scope-and-priority

package/.llms/chunks/components.modeler.feel.cluster-variable.scope-and-priority.resolution-priority.md

@@ -0,0 +1,81 @@
+# Scope resolution — Resolution priority
+
+From highest to lowest priority, the cluster variable resolution order is:
+
+1. Process variables.
+2. Tenant-scope cluster variables.
+3. Global-scope cluster variables.
+
+Resolution priority is the same for every [variable kind](https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/data-types#variable-kinds). The `camunda.vars.env`, `camunda.vars.tenant`, and `camunda.vars.cluster` namespaces select a `SECRET_REFERENCE`-kind variable exactly as they select a `JSON`-kind one. The kind of the variable that wins is what decides whether its `camunda.secrets.<name>` references are resolved.
+
+### Process variables
+
+Variables defined on the process instance always take precedence over cluster variables. This includes:
+
+- Variables set during instantiation.
+- Variables created or updated during execution.
+- Variables passed from parent to child processes.
+
+**Note**
+If you create a process variable with a key that matches a cluster variable path (for example, `camunda.vars.env.API_URL`), the process variable will shadow the cluster variable completely.
+
+### Tenant-scope cluster variables
+
+When multi-tenancy is enabled, tenant-scoped variables:
+
+- Override global scope variables with the same key.
+- Are visible only to processes in that tenant.
+- Enable tenant-specific customization without affecting other tenants.
+
+### Global-scope cluster variables
+
+Global cluster variables provide cluster-wide defaults and baseline configuration. These variables:
+
+- Are accessible to all processes across all tenants.
+- Serve as fallbacks when no tenant-specific override exists.
+- Provide consistent defaults for new tenants.
+
+### Resolution examples
+
+#### Basic scope override
+
+```
+GLOBAL:  { API_TIMEOUT: 5000 }
+TENANT:  { API_TIMEOUT: 10000 }
+PROCESS: (none)
+
+Result when accessing camunda.vars.env.API_TIMEOUT:
+→ 10000 (TENANT value)
+```
+
+#### Partial override
+
+```
+GLOBAL:  { API_CONFIG: { timeout: 5000, retry: 3, url: "https://api.global.com" } }
+TENANT:  { API_CONFIG: { timeout: 10000 } }
+PROCESS: (none)
+
+Result when accessing camunda.vars.env.API_CONFIG.timeout:
+→ 10000 (TENANT value)
+
+Result when accessing camunda.vars.env.API_CONFIG.retry:
+→ null (TENANT defined API_CONFIG as a different object)
+```
+
+**Warning**
+When you override a key at the tenant scope, the entire value at that key is replaced, not merged.
+Partial object merging does not occur.
+
+#### Process variable override
+
+```
+GLOBAL:  { MAX_AMOUNT: 1000 }
+TENANT:  { MAX_AMOUNT: 5000 }
+PROCESS: { camunda.vars.env.MAX_AMOUNT: 10000 }
+
+Result when accessing camunda.vars.env.MAX_AMOUNT:
+→ 10000 (PROCESS variable)
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/modeler/feel/cluster-variable/scope-and-priority