How to migrate incidents and jobs with REST Api

[Arne_Zelasko]

Hi community,

i try to migrate a camunda process with the rest api,but for someprocess instances i get the errors

“failures”:[“Process instance contains not migrated incidents: [a10a…]”

and

“Process instance contains not migrated jobs: [bb40…]”

How can i migrate incidents and jobs with the REST API ? I din’t find any example.

[Adisaid]

Migrating incidents and jobs using a REST API typically involves several steps, including identifying the API endpoints for incident and job management, preparing the data to be migrated, and using REST API client tools to execute the migration process. The specific steps may vary depending on the platform and API being used.

[aravindhrs]

Hi @Arne_Zelasko

When you migrate a process instance in Camunda using the REST API, the migration must also handle any active incidents and jobs (like timers or async continuations) that are tied to the instance. If they’re not properly mapped or migrated, you’ll get errors like:

• “Process instance contains not migrated incidents”
• “Process instance contains not migrated jobs”

Here’s how to deal with these issues and migrate them properly:

1. Understand Why This Happens
• Jobs (like timers, async tasks) are tied to specific activity IDs in the process definition.
• Incidents are typically linked to jobs or executions that failed.
• When migrating, if your migration plan does not map all activities, the engine can’t determine where those jobs/incidents should go in the new process definition.

2. Use updateEventTriggers=true in the Migration Plan

Jobs like timers or async continuations often need eventTrigger updates. When you create the migration plan, use:

POST /migration/generate
{
  "sourceProcessDefinitionId": "id-of-old-definition",
  "targetProcessDefinitionId": "id-of-new-definition",
  "updateEventTriggers": true
}

This helps Camunda know it should recreate timers and job definitions in the new model.

3. Explicitly Map All Activities Involved

Use the instructions array if auto-mapping fails or doesn’t catch everything. Example:

POST /migration/execute
{
  "migrationPlan": {
    "sourceProcessDefinitionId": "source-id",
    "targetProcessDefinitionId": "target-id",
    "instructions": [
      {
        "sourceActivityIds": ["userTask1"],
        "targetActivityIds": ["userTask1"]
      },
      {
        "sourceActivityIds": ["serviceTaskWithTimer"],
        "targetActivityIds": ["serviceTaskWithTimer"]
      }
    ],
    "updateEventTriggers": true
  },
  "processInstanceIds": ["a10a..."]
}

Map all steps with jobs or incidents, even if the ID hasn’t changed.

4. What If Incidents Are Still Not Migrated?

You have two options:

Option A: Fix or Resolve Incidents First

Use:

POST /incident/{id}/resolve

Or resolve the job (e.g., fix the underlying problem and retry it), then migrate.

Option B: Delete Incidents (Last Resort)

This avoids blocking the migration, but you lose error context. Only use if the incident is no longer relevant.

5. Double-Check with /job and /incident APIs

You can inspect jobs and incidents for the failing process instance:

GET /job?processInstanceId=a10a...
GET /incident?processInstanceId=a10a...

Check what activities they’re tied to, then ensure those activities are included in your migration plan.

[aravindhrs]

Hi @Arne_Zelasko,

Here’s how you can build a working migration plan with jobs and incidents in Camunda 7 using the REST API.

Step 1: Inspect Jobs and Incidents

Get jobs and incidents tied to the problematic process instance:

GET /engine-rest/job?processInstanceId=a10a...
GET /engine-rest/incident?processInstanceId=a10a...

Note the activityId or executionId each is tied to.

Step 2: Generate or Manually Define Migration Plan

Use /migration/generate if your activity IDs are mostly unchanged:

POST /engine-rest/migration/generate
{
  "sourceProcessDefinitionId": "old-def-id",
  "targetProcessDefinitionId": "new-def-id",
  "updateEventTriggers": true
}

Or define your own mapping with /migration/execute:

POST /engine-rest/migration/execute
{
  "migrationPlan": {
    "sourceProcessDefinitionId": "old-def-id",
    "targetProcessDefinitionId": "new-def-id",
    "instructions": [
      {
        "sourceActivityIds": ["taskA"],
        "targetActivityIds": ["taskA"]
      },
      {
        "sourceActivityIds": ["serviceTaskWithTimer"],
        "targetActivityIds": ["serviceTaskWithTimer"]
      }
      // Add more if jobs or incidents are tied to other steps
    ],
    "updateEventTriggers": true
  },
  "processInstanceIds": ["a10a..."]
}

If updateEventTriggers is false or missing, jobs like timers won’t be updated correctly and migration will fail.

Step 3: Resolve or Delete Incidents (Optional Cleanup)

If incidents block migration:

• You can resolve incidents that are no longer relevant or already fixed:

POST /engine-rest/incident/{id}/resolve

• You can also delete failed jobs if they’re obsolete:

DELETE /engine-rest/job/{id}