How to update process definition?


I’m struggling to figure out how I can update the XML of an existing process definition using the process engine. We are embedding a process engine and I am using the process engine APIs directly. I only see in the RepositoryService a method to create deployment. The only update methods I can see to process definition are to update the active/suspended state and not the XML.

I tried looking through all documentation and code for the redeploy rest endpoint, but that does not allow to specify new XML, it requires referencing existing resources. The documentation mentions versioning of process definitions, but I see no examples for how to successfully change the process definition.


1 Like

If you create a new deployment with the same Id/Key as a process already deployed on the engine it will automatically create a new version and all instances started with the startProcessInstanceByKey method will start on that new definition.
Take a look at the section of the docs on versioning for more detailed information.

1 Like

Hi @coopstah13,

in addition to versioning concept please also review migration guide


What if the user wants to change the ID/key though? I have a reference to the deployment ID and the process definition ID. Are you saying it cannot be changed? Or it will be mapped as a new deployment?

@Niall you also linked me the page that does not contain the necessary information. It says everything about “redeploying” but there is no information on how to accomplish the task. I understand the concept fundamentally but could not figure out how to implement.

Changing the ID/Key of a process definition will create a new definition, any running instances will not be affected. So there isn’t any problem with changing the Id/Key

If you’re interested in the specific API call to “update” a process, it’s exactly the same as deploying a new process.


The engine will update a definition to a new version automatically.

This is really not ideal for my use case. I was hoping that I could specify the old deployment ID/process definition ID to indicate that I was overwriting that one. I’ll have to figure out a way around it. Thanks for all the prompt responses.

What exactly are you trying to achieve?

We wanted to version the process definition even if the process key was changed. We’ve decided to not allow the process key to be altered which eliminates this trouble.


1 Like

Hi @Niall,

Is there a way to make old running process instances (where their process definition exists in old deployment) works on a new html forms (exists in new deployment)?

As sometimes there is a requirement to update already deployed html forms (for example use a different input type)…