Process Migration Plan: Why are ActivityIds arrays?


I am working on migrating processes to a new deployed version using the REST API.

When I use the validate function (Camunda Platform REST API), the values of instructions.sourceActivityIds / instructions.targetActivityIds are arrays of string (as far as I can see).

Why are this arrays? Isn’t it true, that I have to tell the process engint, which source activity (singular) needs to be mapped to one target activity? Isn’t it a one to one relationship?

I hope someone can help me. :slight_smile:

Best regards,

Hello @Ironarrow ,

indeed, upgrading a process instance can lead to scenarios where the relations are n:m regarding activityIds.

For example, you have multiple activities that should become one.

But in general, you can also see in the example section that the mapping will be 1:1 in most cases.

I hope this helps


Thanks for this information!

1 Like

Hello @jonathan.lukas ,
thank you for your reply. You mean the following situation:

A process with a parallel gateway and three activities (A, B and C) and these activities should be mapped to one activity D. Right?

So the instruction would be [A,B,C] → [D].

Isn’t it possible to make three instructions?

[A] → [D]
[B] → [D]
[C] → [D]

Best regards,

1 Like

Hi @Ironarrow,

it depends if you want to join the 3 tokens of the source into a single one in the target process or keep the three tokens in a single activity.

Both states (single token/three tokens) could be valid.

Hope this helps, Ingo

Hi @Ingo_Richtsmeier

thank you for your answer. I think the best is to make some sample processes and have a look, what happens during the migration.

Btw.: There is “Migration on Deployment” example available (camunda-bpm-examples/migration/migrate-on-deployment at master · camunda/camunda-bpm-examples · GitHub)

As far as I can see / understand, this file will migrate the previous version to the latest version. If the activities have the same name (previous and latest version) it will work fine. If the migration is not that easy, it will fail / skip the running instances so I have to migrate them afterwards. Is this right?


Hi @Ironarrow,

migration can become very complex, depending on the changes that you have done in the new version.

As a vendor we cannot guarantee that each migration will be successful. But the current implementation is very flexible. I have done migrations back to older versions or from one processDefinition to another one, containing the same activity ids.

In the example, changed taskIds will not be covered in the migration. .mapEqualActivities() is defensive and picks only activities that can be migrated without any issues.

The implementations of .build() and .execute() throw exceptions if the migration could not be done.

Hope this helps, Ingo

1 Like

Hi @Ingo_Richtsmeier,

thank you for all the information. This will help me a lot.

Best regards and a nice weekend to all of you,