Purge Tool

For Subscription editions only.
This tool is not available publicly. Use Bonita Customer Service Center to download it.

Bonita Purge Tool provides the capability to purge finished (archived) process instances from Bonita Runtime environment.

By default, all archives are preserved forever in Bonita runtime, but if your functional context allows you to remove old unused process instances (for example, if you only need to keep a history of last 6 months), use this tool to clean up your Bonita database.

The purge tool doesn’t delete documents (stored in the DOCUMENT table) from the platform. It will only remove the mapping between the archived cases and the document itself. If you need to reduce the size of the Document table in the engine database, please refer to the documentation: Delete documents of archived cases based on archive date

Pre-requisites

This tool requires a Java 17+ runtime environment to run.
This tool can be run on a Bonita runtime environment in a version greater than or equal to 7.7.0.

When deleting archives using the copy-truncate mode, the Bonita runtime connected to the database must be shut down when running this tool.

Configuration

Once downloaded, unzip it somewhere and go into the main directory.
Enter your database configuration properties in the file application.properties

Configuration example
# Database configuration
database.vendor=postgres
database.name=bonita
database.username=db_user
database.password=secret
database.host=localhost
database.port=5432

It is also possible to use environment variables to set these properties.

Environment variables example
DATABASE_PASSWORD=secret ./bin/bonita-purge-tool list --older-than 6m

Run Bonita Purge Tool

The Bonita Purge Tool is a command-line tool.
To run it, open a terminal and go to the directory where you unzipped the tool.

View the usage information by running the following command:

  • Unix

  • Windows

./bin/bonita-purge-tool --help
./bin/bonita-purge-tool.bat --help

list command

This command lists all existing process definitions that have root process instances archived for given date filter.

List process definitions with archived root process instances older than 6 months

  • Unix

  • Windows

./bin/bonita-purge-tool list --older-than 6m
./bin/bonita-purge-tool.bat list --older-than 6m

delete command

This command deletes archived process instances and their related archived elements (flownodes, data, comments, etc.) for given date filter.

Delete all archived process instances older than 6 months

  • Unix

  • Windows

./bin/bonita-purge-tool delete --older-than 6m
./bin/bonita-purge-tool.bat delete --older-than 6m
Delete archived process instances older than 6 months for a specific process definition

  • Unix

  • Windows

./bin/bonita-purge-tool delete --older-than 6m --process-definition-id 1234567890
./bin/bonita-purge-tool.bat delete --older-than 6m --process-definition-id 1234567890
Delete archived process instances before 5 July 2022

  • Unix

  • Windows

./bin/bonita-purge-tool delete --before-date 1656979200000
./bin/bonita-purge-tool.bat delete --before-date 1656979200000
The --before-date parameter must be in milliseconds since the epoch.

Delete modes

batch-delete

By default, the tool uses the batch-delete mode to delete rows in database tables.
This mode will be slower than the copy-truncate mode, but it doesn’t require the Runtime to be shutdown and can be stopped and resumed at any time.

In this mode, each deleted batch is committed in database.
The batch size and the timeout interval between each batch can be configured using the --batch-size and --timeout-interval options on the delete command.

Fine tune the batch size and timeout interval depending on your database configuration and the volume of data to delete. By default, the batch size is 5000 and the timeout interval is 0 ms.

copy-truncate

In this mode, the tool will copy the rows to keep in a temporary table, then truncate and drop the original table and rename the temporary table and recreate all required constraints and indices.

Due to the efficiency of the TRUNCATE command, this method should be faster in most cases, especially when the number of rows to delete is higher than the number of rows to keep in the table, but it requires the Runtime to be stopped during the operation.

Use the --delete-mode copy-truncate option to use this mode with the delete command.

delete-file-input command

Delete all archived contract file input values.
In other words, delete all rows in table arch_contract_data corresponding to contract data of type File (in Studio) or org.bonitasoft.engine.bpm.contract.FileInputValue in Bonita Engine.
These data are not used by Bonita and can take a large amout of space in your database, so deleting them is advised.

From Bonita 10.4, these data are no more archived, so it will not be necessary anymore to run this command.
Delete all archived contract file input content

  • Unix

  • Windows

./bin/bonita-purge-tool delete-fileinput-content
./bin/bonita-purge-tool.bat delete-fileinput-content
delete-fileinput-content command is not supported for SQLServer database.

Deletion strategy

You need to have in mind 2 precepts to understand how this tool works:

1) This tool will first delete all archived process instances (arch_process_instance rows) that are concerned by this purge. Then the tables containing associated elements will be scanned to remove all existing orphans.

2) All archived and running process instances (cases) will have at least one row in arch_process_instance table. This is due to the first initializing state (stateId = 0) of the process instance that is archived as soon as it is created.

Thanks to these facts, to identify the orphans we only need to query the arch_process_instance, which is more performant than querying both process_instance and arch_process_instance tables while we avoid removing data from running cases. For example, once all arch_process_instance rows matching the conditions (processDefinitionId and timestamp) have been deleted and when the tool deletes the arch_data_instance rows, the tool only needs to query the arch_process_instance table.

DELETE FROM ARCH_DATA_INSTANCE a WHERE
a.CONTAINERTYPE = 'PROCESS_INSTANCE'
AND a.tenantId = 1
AND NOT EXISTS (
    SELECT id FROM ARCH_PROCESS_INSTANCE b
    WHERE a.CONTAINERID = b.SOURCEOBJECTID
    AND b.tenantId = 1);

This strategy allows this tool to be more robust, it can be stopped at any given time, relaunching it will continue the deletion from where it stopped. However, this means that the time required to execute a purge will be the same when deleting a few elements or a lot of elements.

Database deletion volume testing reference

This reference page provides the tests run on all supported databases.