Delete a process definition

Q&A: The One Where You Completely Delete a Process Definition

*Camunda Platform 8, our cloud-native solution for process orchestration, launched in April 2022. Images and supporting documentation in this post may reflect an earlier version of our cloud and software solutions.


Say you’re completely done with a certain process definition. You no longer run that process, and it’s cluttering up your deployment, so you want it gone.

First, be sure you want it gone. Once you delete it, it’s gone forever, and there is no getting it back! If you still have the .bpmn file you originally used to create the process, you can reload that, but all the history, statistics, etc., associated with that process will be gone.

So you’ve decided you’re done with the process, now what?

Well then, it’s time to delete it Again, let’s just check in one more time that you’re sure, like really, really sure that you never want to see this process again.

If you’re sure, then let’s proceed with deleting it.

7 steps to delete a process definition

Let’s first state up front that these steps are only available in Camunda Platform 7 Enterprise Edition. 

I’ve also added the required REST calls for those who are running Camunda Platform 7 Community Edition. When using the REST calls to delete the process, there are no safeguards to stop you from doing something catastrophic. It’s a good idea to read this whole post, so you’ll know what’s actually going to happen. 

Hint: If you’re running Camunda Platform 7 Community Edition, make sure you start it with the `enableSwagger` flag, so you can use the SwaggerUI interface.

1. Log in to Camunda Cockpit in Camunda Platform 7 and look for your process definitions. 

Cockpit dashboard

2. Click on Process Definitions for a list of all your process definitions.

Cockpit process definitions

Find the process you want to delete, and click on the trash can icon in the right-most column.

If you’re running Camunda Platform 7 Community Edition, you’ll need to run two REST calls (unless you already know the process ID). To get the process ID, you can execute:

curl -X GET 
"http://localhost:8080/engine-rest/process-definition?active=true" -H  "accept: application/json"

Which will return a JSON object containing all the currently deployed processes. You can find the process ID you’re interested in listed there. To narrow things down a bit, you can also try:

curl -X GET 
"http://localhost:8080/engine-rest/process-definition?keyLike=<partial-string>&active=false" -H  "accept: application/json"

Using a partial string of the process definition will help. 

Once you have that, you can then execute:

curl -X DELETE 
"http://localhost:8080/engine-rest/process-definition/key/<ProcessKey>" -H  "accept: */*"

If that returns a 204 status, you were successful. 

But wait, be careful If you only have one version of the process definition deployed, then you’re done. If you have multiple versions deployed, you’ll have to repeat that last command until it returns a 404 status, indicating there are no more processes with that key.

Cockpit definitions trash can

3. Click on the Trash Can icon. It’s still not too late to change your mind, but it’s getting close to the point of no return.

Cockpit delete process

4. Now, it’s time to actually delete the process. Click the Cascade button, just to be safe. “Cascade” means that the deletion process will delete every instance for every version of the model, no matter what. This is helpful because you’ll want to make sure you get everything the first time. 

Cockpit delete process cascade

5. We can safely ignore the Batch Process warning message, given there are no running instances of the process. Right? RIGHT?! Of course we can, because you already said you were no longer using it.

6. Once you hit the Delete button, the process will be permanently and irrevocably deleted. This is your very last chance to turn back.

Cockpit delete process cascade

7. Now that it’s deleted, return to your process list and note that the process definition is no longer listed.

Cockpit process list, minus your process

Mission Accomplished

Now it’s gone. Forever. And no, you can’t get it back.

Ready to get started?

Still have questions?