@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.concepts.process-instance-creation.feel-context-variables-searching-and-filtering-by-business-id.md

@@ -0,0 +1,42 @@
+# Process instance creation — FEEL context variables — Searching and filtering by business ID
+
+Starting in 8.10, `businessId` is available across multiple entity types. Searchability varies by entity:
+
+| Entity                | Searchable | Visible | Notes                                                                               |
+| :-------------------- | :--------- | :------ | :---------------------------------------------------------------------------------- |
+| Process instances     | Yes        | Yes     | Available since 8.9.                                                                |
+| Decision instances    | Yes        | Yes     | Available since 8.10.                                                               |
+| User tasks            | Yes        | Yes     | Available since 8.10.                                                               |
+| Messages              | Yes        | Yes     | API only. Not shown in the Operate process instance details view.                   |
+| Message subscriptions | Yes        | Yes     | API only.                                                                           |
+| Jobs                  | No         | Yes     | Visible in job activation response. Not searchable, filterable, or shown in the UI. |
+
+#### Advanced filter operators
+
+The API supports the following operators for `businessId`. Operate and Tasklist expose a subset in their filter UI.
+
+| Operator  | Description                 | Wildcards                           | UI label  |
+| :-------- | :-------------------------- | :---------------------------------- | :-------- |
+| `$eq`     | Exact match                 | —                                   | Equals    |
+| `$neq`    | Does not match              | —                                   | API only  |
+| `$exists` | Field is set or absent      | —                                   | API only  |
+| `$like`   | Pattern match               | `*` (multi-char), `?` (single-char) | Contains  |
+| `$in`     | Matches any value in a list | —                                   | Is one of |
+| `$notIn`  | Matches no value in a list  | —                                   | API only  |
+
+#### API reference
+
+| Entity                | Endpoints                                                                                                                                                                                              |
+| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Process instances     | [Get](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/get-process-instance.api) · [Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-process-instances.api)   |
+| Decision instances    | [Get](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/get-decision-instance.api) · [Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-decision-instances.api) |
+| User tasks            | [Get](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/get-user-task.api) · [Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-user-tasks.api)                 |
+| Message subscriptions | [Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-correlated-message-subscriptions.api)                                                                                    |
+| Jobs (visible only)   | [Search](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/search-jobs.api) · [Activate](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/activate-jobs.api)                  |
+
+#### Retroactive visibility
+
+Business IDs assigned to process instances in 8.9 remain traceable because the business ID is stored on the process instance record. However, related artifacts — user tasks, decision instances, jobs, and message subscriptions — snapshot the business ID at their own creation time. Artifacts created before business ID visibility shipped for that entity type are not retroactively enriched and carry no `businessId` value.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.feel-context-variables-uniqueness-control.md

@@ -0,0 +1,26 @@
+# Process instance creation — FEEL context variables — Uniqueness control
+
+With uniqueness control, you can ensure that only one active root process instance exists for a given **process definition, tenant, and business ID**. This prevents duplicate processing of the same business case.
+
+Uniqueness is checked against **active root process instances**.
+
+- A **root process instance** is a process instance that was started directly, not created by a call activity. Child process instances created via call activities don't count toward the uniqueness check, even though they inherit the parent's business ID.
+- When uniqueness control is enabled, creating a root process instance is rejected if another **root** process instance of the same process definition is already active with the same business ID. The rejection returns an `ALREADY_EXISTS` error (HTTP `409 Conflict`).
+- Once a process instance is no longer active (completed or terminated), you can use its business ID to create a new process instance.
+
+**Note: Retroactive enforcement**
+Uniqueness control is **retroactive**. When you enable it, business IDs that were already assigned to active process instances _before_ the feature was turned on are taken into account. This prevents duplicate instances from being created after the feature is enabled, even if duplicates already existed before activation.
+
+Uniqueness control is opt-in. Enable it using the configuration property [`camunda.process-instance-creation.business-id-uniqueness-enabled`](https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/core-settings/configuration/properties#process-instance-creation). For SaaS, configure this in the cluster configuration via Camunda Hub. For Self-Managed, set it in the application config (for example, `application.yaml` or as an environment variable).
+
+**Note**
+When a business ID is specified, the partition for the new process instance is determined deterministically by **hashing the business ID**, rather than using the default round-robin distribution. This ensures that uniqueness checks occur on a single partition.
+
+Be aware that this may result in uneven distribution of instances across partitions if business IDs are not well distributed.
+
+#### Multi-tenancy scope
+
+In a multi-tenant environment, uniqueness is enforced **per tenant and process definition**. Process instances belonging to different tenants can use the same business ID and process definition without conflict. For example, two active root process instances in different tenants may share the same business ID and process definition.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.feel-context-variables-what-is-a-business-id.md

@@ -0,0 +1,30 @@
+# Process instance creation — FEEL context variables — What is a business ID?
+
+A business ID is a domain-specific identifier you can assign to a process instance. Unlike the system-generated process instance key, it represents a domain concept such as an order number, case reference, or customer ticket ID.
+
+A business ID does **not need to be unique** unless uniqueness control is enabled. See [uniqueness control](#uniqueness-control) for details.
+
+For example, consider a process that ships book orders where each order already has an identifier in your order management system. When you start the process to ship an order, you can use the order ID as the business ID. This lets you easily find all process instances related to a particular order.
+
+You set the business ID at process instance creation time via the `businessId` field in the creation request. The business ID is **immutable**; once set, it cannot be changed or removed for the lifetime of the process instance. The maximum length for a business ID is **256 characters**.
+
+Starting in 8.10, you can also set a business ID when starting a process instance from **Camunda Hub** or **Desktop Modeler**.
+
+   Create a process instance with a business ID via Orchestration Cluster REST API
+   
+
+```
+curl -L 'http://localhost:8080/v2/process-instances' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+-d '{
+  "processDefinitionId": "order-process",
+  "processDefinitionVersion": 1,
+  "businessId": "order-1234"
+}'
+```
+
+See the [API reference for process instance creation](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-process-instance.api) for more information, including additional request fields and code samples.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.feel-context-variables.md

@@ -0,0 +1,14 @@
+# Process instance creation — FEEL context variables
+
+Starting in 8.10, the process instance properties are accessible in [FEEL expressions](https://docs.camunda.io/docs/next/components/concepts/expressions) via the `camunda.processInstance` context, resolvable in any FEEL expression across the process:
+
+- `camunda.processInstance.key` — the process instance's system-generated key.
+- `camunda.processInstance.businessId` — the process instance's [business ID](#business-id), or `null` if none is set.
+
+These are the only `camunda.processInstance.*` context variables available in 8.10.
+
+
+## Business ID
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.md

@@ -0,0 +1,21 @@
+# Process instance creation
+
+Depending on the process definition, an instance of it can be created in several ways.
+
+Depending on the process definition, an instance of it can be created in several ways.
+
+Camunda 8 supports the following ways to create a process instance:
+
+- [`CreateProcessInstance` commands](#commands)
+- [Message event](#message-event)
+- [Timer event](#timer-event)
+
+
+## Commands
+
+A process instance is created by sending a command specifying the BPMN process ID, or the unique key of the process.
+
+There are two commands to create a process instance, outlined in the sections below.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.next-steps.md

@@ -0,0 +1,7 @@
+# Process instance creation — Next steps
+
+- [About Modeler](https://docs.camunda.io/docs/next/components/modeler/about-modeler)
+- [Automating a process using BPMN](https://docs.camunda.io/docs/next/components/modeler/bpmn/automating-a-process-using-bpmn)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.run-process-segment.md

@@ -0,0 +1,58 @@
+# Process instance creation — Run process segment
+
+The [`create and execute asynchronously`](#create-and-execute-asynchronously) and [`create and await results`](#create-and-await-results) commands both start the process instance at their default initial element: the single [none start event](https://docs.camunda.io/docs/next/components/modeler/bpmn/none-events/none-events#none-start-events). Camunda 8 also provides a way to create a process instance starting or ending at user-defined element(s).
+
+**Info**
+This is an advanced feature. Camunda recommends to only use this functionality for testing purposes. The none start event is the defined beginning of your process. Most likely the process is modeled with the intent to start all instances from the beginning.
+
+#### Start instructions
+
+To start the process instance at a user-defined element, you need to provide start instructions along with the command. Each instruction describes how and where to start a single element.
+
+By default, the instruction starts before the given element. This means input mappings of that element are applied as usual.
+
+Multiple instructions can be provided to start the process instance at more than one element.
+You can activate the same element multiple times inside the created process instance by referring to the same element ID in more than one instruction.
+
+#### Runtime instructions
+
+By default, the process execution continues normally until the end of the process. To change this behavior and end the process instance after a specific element completes or terminates, provide runtime instructions. Each runtime instruction specifies the ID of one element whose completion or termination ends the process instance.
+
+You can provide multiple runtime instructions to terminate the process instance after multiple elements—for example, when a process has multiple parallel flows.
+
+**Note**
+Start and runtime instructions have the same [limitations as process instance modification](https://docs.camunda.io/docs/next/components/concepts/process-instance-modification#limitations), e.g., it is not possible to start or end at a sequence flow.
+
+Start and runtime instructions are supported for both `CreateProcessInstance` commands. Both instruction sets can be used separately or together to achieve different scenarios.
+
+   Create a process instance with a start and a runtime instruction
+   
+
+The example below shows how to create a process instance that starts at a user-defined element and terminates after it, so that only the specified segment of the process is executed.
+
+```
+curl -L 'http://localhost:8080/v2/process-instances' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+-d '{
+  "processDefinitionId": "order-process”,
+  "processDefinitionVersion": -1,
+  "startInstructions": [
+    {
+      "elementId": "ship_parcel"
+    }
+  ],
+  "runtimeInstructions": [
+    {
+      "type": "TERMINATE_PROCESS_INSTANCE",
+      "afterElementId": "ship_parcel"
+    }
+  ]
+  "variables": { "orderId": "1234" }
+}'
+```
+
+See the [API reference for process instance creation](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/create-process-instance.api) for more information, including additional request fields and code samples.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-creation.tags.md

@@ -0,0 +1,58 @@
+# Process instance creation — Tags
+
+Process instance tags are lightweight, immutable labels you can attach when creating a process instance via the API or clients. Tags are inherited by all jobs created from that instance. They help downstream workers and external systems make quick routing or decision choices without inspecting full variable payloads.
+
+### Tag format and constraints
+
+- A tag is a case-sensitive string.
+- Format (regex): `^[A-Za-z][A-Za-z0-9_\-:.]{0,99}$`
+  - Must start with a letter (A–Z or a–z).
+  - Remaining characters may be alphanumeric, underscore (`_`), hyphen (`-`), colon (`:`), or dot (`.`).
+- Length: 1–100 characters.
+- Maximum of 10 unique tags per process instance (duplicates are ignored).
+- Order is not guaranteed; treat the set as unordered.
+- Tags cannot be modified after creation
+
+If validation fails during process instance creation (for example, too many tags, invalid pattern, or length), the create request is rejected with a 4xx error.
+
+### Semantics
+
+- Tags are included in process instance search responses and in activated job payloads.
+- Tags are immutable after creation - cannot be added, changed, or removed after process instance has been created.
+- Search filtering uses AND semantics: an instance must contain all requested tags (it may contain additional tags). Partial or wildcard matching is not supported.
+- Tags are exported with the process instance and with job entities starting in 8.8 by the default exporters.
+- Tags are not shown in web applications (such as Operate and Tasklist) — they are API/client-only metadata.
+
+### Use cases
+
+- Routing and prioritization (for example, `priority:high`)
+- Business or domain identifiers from internal or third-party systems (for example, `reference:1234`, `team:accounting`, `origin:crm`)
+- Cross-system correlation keys without exposing full variable payloads (for example, `trace-id:abcd-1234`, `crm-id:3004`)
+- Analytics segmentation (for example, `region:emea`, `channel:web`)
+- Feature rollout or experiment grouping (for example, `experiment:checkout-v2`)
+
+### Guidelines
+
+- Do not store secrets or PII; tags propagate with jobs and exports.
+- Prefer concise `key:value` or `key` patterns for consistency.
+- Use variables (not tags) for mutable or large data.
+- Establish internal naming conventions (for example, prefixes like `env:` or `dept:`) for governance.
+
+### Examples
+
+Create with tags:
+
+```bash
+curl -L 'http://localhost:8080/v2/process-instances' \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -d '{
+    "processDefinitionId": "order-process",
+    "processDefinitionVersion": 3,
+    "tags": ["channel:web", "reference:1234", "region:emea"],
+    "variables": { "orderId": "1234" }
+  }'
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-creation

package/.llms/chunks/components.concepts.process-instance-deletion.eventual-consistency.md

@@ -0,0 +1,41 @@
+# Process instance deletion — Eventual consistency
+
+Process instance deletion runs asynchronously. Depending on how many process instances you delete, it can take time for the data to be removed and for the process instance to disappear from Operate.
+
+
+## Technical details
+
+This section explains how process instance deletion is handled internally to help you understand timing and consistency behavior.
+
+Deleting one or more process instances uses [batch operations](https://docs.camunda.io/docs/next/components/concepts/batch-operations).
+
+The Zeebe engine queries [secondary storage](https://docs.camunda.io/docs/next/self-managed/concepts/secondary-storage/index) for process instances to delete. For each instance found, the engine writes a delete command to the log, which results in a deleted event.
+
+Exporters consume the deleted event and write a record to secondary storage to mark the process instance for deletion. An asynchronous scheduled task then deletes all data associated with each marked process instance.
+
+```mermaid
+sequenceDiagram
+    V2 API->>+Engine: Delete process instances with filter
+    Engine->>Engine: Create batch operation
+    Engine->>-V2 API: Batch operation create response
+    Engine->>+Secondary storage: Query process instances
+    activate Engine
+    Secondary storage->>-Engine: Return process instance keys
+    loop for each process instance key
+    Engine->>Engine: Write DELETED event for each process instance key
+    Engine->>+Exporter: Export DELETED event
+    deactivate Engine
+    Exporter->>-Secondary storage: Mark process instance for deletion
+    end
+    note over V2 API,Deletion job: Everything below this note happens asynchronously.
+    Deletion job->>+Secondary storage: Retrieve marked process instance keys
+    activate Deletion job
+    Secondary storage->>-Deletion job: Return process instance keys
+    loop for each process instance key
+    Deletion job->>Deletion job: Delete associated data
+    end
+    deactivate Deletion job
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-deletion

package/.llms/chunks/components.concepts.process-instance-deletion.limitations.md

@@ -0,0 +1,24 @@
+# Process instance deletion — Limitations
+
+You can delete only process instances in a completed or terminated state. This preserves consistency and integrity within the system.
+
+If a process instance is still active, cancel it first using the [cancel process instance API](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/cancel-process-instance.api).
+
+### Limitations with call activities
+
+When process instances are linked through call activities, deletion is scoped to the selected instance only. Related parent or child process instances are not deleted automatically.
+
+#### Delete a called process instance
+
+If you delete a process instance that was created by a call activity, the parent process instance is not affected. Only the called process instance data is deleted.
+
+In Operate, the parent process instance remains visible, but you can’t navigate to the deleted called process instance.
+
+#### Delete a parent process instance
+
+If you delete a parent process instance that contains a call activity, the called process instance is not affected. Only the parent process instance data is deleted.
+
+In Operate, the called process instance remains visible, but navigating to it shows an empty screen.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-deletion

package/.llms/chunks/components.concepts.process-instance-deletion.md

@@ -0,0 +1,16 @@
+# Process instance deletion
+
+Delete all data for a completed or terminated process instance.
+
+Use process instance deletion to permanently remove all data associated with a completed or terminated process instance.
+
+**Warning**
+Deletion is irreversible. Restore deleted data only by restoring a backup of your cluster.
+
+Delete a process instance using the [delete process instance endpoint](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/delete-process-instance.api), or multiple using the [delete process instances endpoint](https://docs.camunda.io/docs/next/apis-tools/orchestration-cluster-api-rest/specifications/delete-process-instances-batch-operation.api).
+
+**Note**
+You can also delete a process instance in Operate. See the [Operate user guide](https://docs.camunda.io/docs/next/components/operate/userguide/delete-finished-instances).
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-deletion

package/.llms/chunks/components.concepts.process-instance-migration.change-the-active-elements.md

@@ -0,0 +1,34 @@
+# Process instance migration — Change the active elements
+
+Sometimes your requirements change so much that the currently active element no longer exists in the new process version.
+
+Consider the following example: the process contains a completed exclusive gateway, taking the sequence flow to the service task `A` which is currently active.
+It did not take the sequence flow to service task `B`, so it is inactive.
+
+![The process instance is waiting at the active service task A while service task B is inactive.](assets/process-instance-migration/migration-active_before.png)
+
+Due to changed requirements, our process model no longer contains the exclusive gateway, nor the service tasks `A` and `B`.
+Instead, it only contains a new service task `C`.
+
+![The target process only contains a service task C.](assets/process-instance-migration/migration-active-elements-target.png)
+
+We can migrate the active service task `A` to this new service task `C` by providing a mapping instruction from source element ID `A` to target element ID `C`.
+
+![After migrating the process instance, it is waiting at service task C.](assets/process-instance-migration/migration-active_after.png)
+
+**Note**
+You cannot map an element to an element of a different type.
+An active service task of a process instance can only be mapped to a service task in the target process.
+It cannot be mapped to a user task as this changes the element type.
+
+Also note that the [jobs, expressions, and input mappings](#jobs-expressions-and-input-mappings) are not recreated.
+So, while service task `C` is active in the target process, the associated job still has the job type from when it was associated to service task `A`.
+
+**Tip**
+If you need to adjust the job type to its new element, you can use [process instance modification](https://docs.camunda.io/docs/next/components/concepts/process-instance-modification) to recreate the service task.
+Simply cancel the service task instance, and add a new instance of the service task.
+
+![The process instance can be modified to recreate the service task's job.](assets/process-instance-migration/migration-active_after-modification.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.correct-mistakes-in-a-process-instance.md

@@ -0,0 +1,25 @@
+# Process instance migration — Correct mistakes in a process instance
+
+Process instance migration can also be used to correct mistakes that led to an [incident](https://docs.camunda.io/docs/next/components/concepts/incidents) in a process instance.
+
+Let's consider an example.
+
+A user deployed a process with a user task `A`. The instance of that process always receives two variables (one boolean and one string).
+By accident, the string is used in the condition. To fix the problem, the process model should be updated to use the boolean variable instead.
+A process instance gets stuck at this user task, and an incident is created to inform the user of this problem.
+
+![After creating the process instance, an incident is created for the service task A.](assets/process-instance-migration/migration-process_instance_with_incident.png)
+
+To correct the problem in the process instance, the user can take the following steps:
+
+1. Correct the mistake in Modeler by creating a new version of the process definition.
+2. Deploy the new process version where the boolean variable is used in the condition.
+3. Migrate the process instance to the new process version.
+4. Resolve the incident.
+
+Afterward, the process instance will continue as expected:
+
+![After migrating the process instance, the input mapping is corrected and the incident is resolved by retry. Afterward, the process instance will continue as expected:](assets/process-instance-migration/migration-process_instance_with_incident_resolved.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-catch-events-add-or-remove-catch-events.md

@@ -0,0 +1,30 @@
+# Process instance migration — Deal with catch events — Add or remove catch events
+
+You can also add or remove catch events.
+
+Let's consider a process instance awaiting at a service task `A`.
+
+![The process instance is waiting at the active service task A without any boundary events attached.](assets/process-instance-migration/migration-boundary-event_before.png)
+
+You can migrate it to a process definition where a message event subprocess with message start event `M` is added to the process.
+To do so, you only have to map element `A` to element `A` in the target process.
+After migrating active element `A`, the process instance is newly subscribed to the message boundary event `M` (_a new subscription is opened_).
+
+![After migrating, the process instance is subscribed to the newly introduced message event subprocess start event.](assets/process-instance-migration/migration-catch-event-target-added.png)
+
+Likewise, you can migrate the process instance back to the previous process definition where no message event subprocess is defined.
+To do so, you only have to map element `A` to element `A` again.
+After migrating active element `A`, the process instance is no longer subscribed to the message start event `M` (_associated subscription is closed_).
+
+![After migrating back, the process instance is no longer subscribed to the message boundary event](assets/process-instance-migration/migration-boundary-event_before.png)
+
+Likewise, adding and removing catch events applies to all other supported catch event types as well.
+For instance, an intermediate signal catch event can be added or removed in the same way as the message event subprocess in the example above.
+
+**Tip**
+Currently, a mapping instruction must be provided between catch events to migrate message catch events if the target catch event has the same message name.
+Therefore, it is not possible to re-create message catch events with the same message name in the target process definition.
+While we're working on resolving this, you can migrate this case by providing a mapping between the boundary events.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-catch-events-compensation-boundary-events.md

@@ -0,0 +1,18 @@
+# Process instance migration — Deal with catch events — Compensation boundary events
+
+Compensation boundary events can be migrated similarly to other catch events, with one exception. If a compensation boundary event is added, a new compensation subscription is only opened for activity instances that are currently active, or haven't been started yet. For activity instances that have already finished, no new compensation subscription will be opened.
+
+Consider the following example where the instance is waiting on service task `A`:
+
+![The instance waiting on service task A.](assets/process-instance-migration/migration-compensation_before.png)
+
+The target process definition contains a compensation boundary event attached to service task `A`:
+
+![The target process definition contains a compensation boundary event attached to service task A.](assets/process-instance-migration/migration-compensation_after.png)
+
+If the process instance is migrated by providing mapping instruction between service tasks `A` -> `A`, the compensation subscription will be created on completion of the element `A`.
+
+However, if the process instance is migrated by providing mapping instruction between service tasks `A` -> `B`, then triggering compensation throw event afterward will not compensate `A`. This is because the subscription is only opened when completing a task with a compensation boundary event.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-catch-events-migrate-catch-events-2.md

@@ -0,0 +1,17 @@
+# Process instance migration — Deal with catch events — Migrate catch events (2)
+
+In the second scenario, there are changes between these catch events:
+
+Now, we want to reset the timer and wait for two weeks as in the target process definition.
+To achieve this for the example above, only a mapping between active user tasks `A` -> `A` must be provided.
+This will cancel the timer (_associated subscription is closed_) and create a new one (_a new subscription is opened_).
+After the migration the process instance will look as follows:
+
+![The process instance is waiting at the active user task A with a new timer boundary event attached.](assets/process-instance-migration/migration-catch-event-different-target-trigger-updated.png)
+
+Same as above, omitting the mapping instruction for catch events applies to other event types as well.
+For example, if you want to change the message name for a message event subprocess start event, you must omit mapping the message start event when migrating the process instance.
+Another example would be to update a signal name for an intermediate signal catch event, you must omit mapping the signal catch event when to the one in the target while migrating the process instance.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-catch-events-migrate-catch-events.md

@@ -0,0 +1,53 @@
+# Process instance migration — Deal with catch events — Migrate catch events
+
+Catch events can be migrated by providing a mapping instruction between the source and the target catch event.
+Providing a mapping between catch events ensures that the event subscription in the source process is preserved after the migration.
+In the following section we will discuss situations where mapping a catch event may or may not be useful.
+Let's explain both mapping and non-mapping scenarios with examples.
+
+#### A mapping instruction is provided between the catch events
+
+An active user task has been waiting for a timer boundary event.
+The timer boundary event is defined as a duration of one week.
+The user task has not been completed and has already spent five days waiting for the timer.
+
+![The process instance is waiting at the active user task A with a timer boundary event attached.](assets/process-instance-migration/migration-catch-event-source.png)
+
+Now we want to [change an inactive part of the process](#change-the-process-instance-flow-for-inactive-parts) by adding a user task after the timer boundary event.
+Instead of waiting for the full time defined by the target process' timer boundary event, we only want to wait for the remaining two days.
+To achieve this for the example above, the mapping between active user tasks `A` -> `A` and timer boundary events `Timer1` -> `Timer2` must be provided.
+This ensures the timer is migrated (_the associated subscription is migrated_) and the duration is preserved.
+Assuming that the timer boundary event is defined as 2 weeks duration in the target process, the process instance will look as follows after the migration:
+
+![The process instance is waiting at the active user task A with the migrated timer boundary event attached.](assets/process-instance-migration/migration-catch-event-different-target.png)
+
+Mapping catch events applies to other event types as well.
+For example, if you want to keep the message name the same for a message event subprocess, you should map the start event of the event subprocess when migrating the process instance.
+Another example would be to preserve a signal name for an intermediate signal catch event attached to an event-based gateway. In this case, you should map the signal catch event to the one in the target while migrating the process instance.
+
+#### No mapping instruction is provided between the catch events
+
+Before moving forward with the example, there are two important scenarios to consider because they affect the output after the migration:
+
+- The catch event in the source process is identical to the catch event in the target process.
+- There are changes between these catch events, for example, the message name is different in the target.
+
+Let's consider again the same example above:
+
+An active user task has been waiting for a timer boundary event.
+The timer boundary event is defined as a duration of one week.
+The user task has not been completed and has already spent five days waiting for the timer.
+
+![The process instance is waiting at the active user task A with a timer boundary event attached.](assets/process-instance-migration/migration-catch-event-source.png)
+
+In the first scenario, the catch event in the source process is identical to the catch event in the target process:
+
+This time we want to reset the timer and wait for the full week again.
+To achieve this for the example above, only a mapping between active user tasks `A` -> `A` must be provided.
+This will cancel the timer (_associated subscription is closed_) and create a new one (_a new subscription is opened_).
+After the migration the process instance will look like following:
+
+![The process instance is waiting at the active user task A with a new timer boundary event attached.](assets/process-instance-migration/migration-catch-event-identical-target-trigger-updated.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-catch-events.md

@@ -0,0 +1,16 @@
+# Process instance migration — Deal with catch events
+
+An exception to changing the process instance state is specific to catch events.
+This is necessary to ensure that the process instance can be executed according to the new process definition.
+It allows you to add or remove catch events from an active element.
+At the same time, you can leave an existing catch event unchanged.
+This section explains how to deal with catch events when migrating a process instance.
+
+You decide what happens to the associated event subscription through the mapping instructions for the catch events:
+
+- Migrate catch events: if a catch event is mapped, the associated subscription is migrated.
+- Remove catch events: if a catch event in the source process is not mapped, then the associated subscription is closed during migration.
+- Add catch events: if a catch event of the target process is not the target of a mapping instruction, then a new subscription is opened during migration.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration

package/.llms/chunks/components.concepts.process-instance-migration.deal-with-gateways.md

@@ -0,0 +1,36 @@
+# Process instance migration — Deal with gateways
+
+Process instance migration allows you to migrate several scenarios for gateways:
+
+- An active exclusive gateway with an incident can be migrated like any other active element.
+- Parallel and inclusive gateways can be involved in [additional scenarios](#migrate-joining-parallel-and-inclusive-gateways).
+
+### Migrate joining parallel and inclusive gateways
+
+Joining parallel and inclusive gateways with taken incoming sequence flows, and which are still waiting for more incoming sequence flows, require a mapping instruction similar to active elements.
+
+For migrating joining gateways, the following conditions must be true:
+
+- The joining gateway in the process instance must be mapped to the target gateway.
+- The target gateway must have at least the same number of incoming sequence flows as the source gateway.
+
+Consider the following example:
+The process instance is waiting at the joining parallel gateway, with an incoming sequence flow `flow1`, taken after the element `A` completes. Element `B` is still active and waiting at the user task.
+
+![The instance waiting on joining gateway.](assets/process-instance-migration/migration-joining-gateway-before.png)
+
+Then, the process definition is updated to include element `C` before the joining gateway.
+
+To migrate the process instance, provide the following mapping instructions:
+
+- From the active element `B` to the target element `B`.
+- From the joining parallel gateway instance `gateway1` to the target joining parallel gateway `gateway2`.
+- From the sequence flow `flow1` to the target sequence flow `flow2`.
+
+After the migration, the process instance will look like the following:
+
+In the example above, another element `C` is added before the joining gateway in the target process definition.
+After the migration, element `B` must still be completed for the process instance to continue through the gateway.
+
+---
+Source: https://docs.camunda.io/docs/next/components/concepts/process-instance-migration