Flowable history levels and when your audit needs set the level
Choose the Flowable history level from the questions you must answer later, not from the default you inherited. The history level is the main switch that decides how much audit detail the engine writes for every process instance, and so how fast your history tables grow. The four levels the Flowable configuration docs define are none, activity, audit and full. Start by listing what must be reconstructed after the fact: which task completed, who completed it, which variables held which values, and which decision table produced an outcome. Then map each item to the lowest level that captures it. Confirm the exact data captured at each level in the Flowable documentation for the version you run, because the data differs between levels and between releases, and the docs are the authority for your build.
The setting is a single configuration property, so the change is quick to make and easy to get wrong. Read the value in your Spring or plain engine configuration and check it against the environment that writes to production history. A level chosen for a test rig can quietly carry into production and grow the history tables without anyone deciding it. Also confirm whether any of your audit evidence depends on data that a lower level never writes. If a regulator or internal auditor will ask for who approved a step or what a decision received as input, that requirement belongs in the level decision, not in a later clean-up job. Document the decision with the process owners and the control owner so the reason survives staff changes.
Plan for the write volume before the database forces the question. Every additional level of detail adds rows for each instance, so a high-volume process at a more detailed level can outgrow its storage faster than the process owner expects. Pair the level with a history cleaning schedule that deletes or archives history beyond your retention period, and confirm how the Flowable docs describe that cleaning and its effect on the database. Ask your database administrator to size the history tables from a measured sample before go-live, and ask the implementation partner to show which tables each level writes. Hypothetical example, for illustration only: a team that needs approval evidence for a few case types may set the level for those flows and keep lighter settings elsewhere, if the engine version allows that split.
Flowable history level options and their cost
This table compares the four Flowable history levels, none, activity, audit and full, by what each records, how much it adds to database writes and table growth, and which audit questions it can answer. Read each row as a step up in detail, and confirm the exact record set for your engine version in the Flowable configuration docs. The main takeaway is that each higher level gives better reconstruction of past work, and the cost is paid on every transaction and in table size.
| Level | What it records | Write volume and table growth | Audit questions it can answer |
|---|---|---|---|
| None | No history rows for process instances, activities, tasks or variables | Lowest history writes, no history table growth | None after completion. Runtime state only while work is active |
| Activity | Process and activity instance starts and ends, with the path taken | Adds a row per activity instance, so growth follows flow steps | Which steps ran, when, and how long they took. Not who changed data |
| Audit | Adds task and identity records, plus the variable data the docs define for this level | More writes per transaction, with growth tied to tasks and variable events | Who completed tasks, what was decided, and key values at each step (confirm the record set) |
| Full | Everything the engine supports, including intermediate variable update history | Highest write volume and fastest table growth, with the heaviest cleanup need | Most detailed reconstruction, including intermediate changes, at higher storage and query cost |
| Write path (version 7 and later) | Async history was removed in version 7, so history is written synchronously | Each level adds database work to the same engine transaction as runtime changes | Confirm the write path and cleaning jobs for your version before sizing the database |
How history writes add load to the database
Every history level you choose adds rows to Flowable's history tables while processes run, so the write cost rises with three things: the number of process instances, the number of activities each instance executes, and the number of variable updates made along the way. A short approval flow with five activities and two variables writes far fewer history rows than a long-running onboarding case that loops through document checks and updates dozens of variables. Because those rows accumulate, table size grows steadily until something removes old rows, and the history cleaning schedule becomes part of the design rather than an afterthought. Before you pick a level, ask your Flowable team or partner to confirm, in your own environment, which history tables each level writes to and how the cleanup job selects rows for deletion.
The cost is not confined to the history tables. Flowable writes history in the same transactions that move work forward, so heavier history can slow the runtime path that creates tasks, completes activities and releases jobs. Each extra insert, index update and lock on a busy table adds time to a transaction that the engine also needs for the main execution tables, and that delay is felt most at peak load and at parallel joins where transactions already compete. Check the effect on the runtime tables under test, not only on the history tables, and watch for growing index sizes and longer cleanup windows as volume rises. The setting that matters most is the one you can measure in your own stack, so treat it as a tuning decision with evidence attached.
To size this, build a load test that mirrors your production process shapes: the same number of activities, parallel branches, timers, subprocesses and variable updates, along with realistic instance arrival rates. Run it at each candidate history level and record the rows written per completed instance in each history table, the transaction time on the runtime path, and the growth rate of the database over several cleaning cycles. Ask the reader's own engineers to confirm how they will reproduce the largest process definitions, because averages hide the instances that cause the most writes. The resulting per-instance row count is the number you will use to forecast storage and cleanup needs, and it should be recorded alongside the chosen level so future changes are judged against the same baseline.
How to set Flowable history levels step by step
This sequence moves a Flowable history level from a decision about audit needs to a tested production setting, with a check at each stage so the chosen level produces the history your auditors and reports depend on without writing more rows than the database can carry.
Confirm the audit questions with owners
Compliance leads, process owners and the teams that build reports list the questions the history must answer, such as who approved a step, when a task was completed, or which decision path an instance took. Each question is written down with the data it needs and how far back it must reach. The step is done when every question maps to a history type the team can name, and the list is signed off by the people who will rely on it. Questions that cannot be answered from history, such as business records held in other systems, are recorded separately so they do not drive the level choice.
Set the history level in a non-production environment
An engineer sets the history level in the engine configuration of a non-production environment, using the property names given in the Flowable configuration documentation, and restarts the application so the setting takes effect. The team records the exact level, the Flowable version and the database type in the environment's configuration repository. The step is complete when the engine starts cleanly and a test process instance writes the history rows expected for that level. Teams should confirm the property name and accepted values against the version they run, because the configuration docs are the authority for both.
Deploy a representative process set
The team deploys a set of process definitions that reflects production: the main BPMN processes, any CMMN cases and DMN decisions they call, subprocesses, parallel branches and timers. Where production uses multiple tenants or large variable payloads, the test set includes them too. The check is that every definition deploys without errors and that the representative instances exercise each path the audit questions depend on. A short list of expected paths is kept so later checks compare against it.
Run a load test and count rows written
The team runs a load test with volumes modeled on peak production traffic, then counts the rows written to the history tables and the runtime tables, and measures how database size grows per completed instance. Counts are compared across each history level under the same load, so the cost of a higher level is visible before promotion. The step closes with a table of rows per instance for each level, the growth rate, and the database observations such as write latency and lock waits. Figures from this run are the basis for the retention and cleaning decisions in the next steps.
Verify audit queries return expected data
Auditors and report owners run the history queries they actually need against the test database, such as reconstructing the path of a known instance, listing approvals with timestamps, or pulling decision outcomes. Each result is compared with a known test run, where the team already knows which tasks, users and decisions occurred. Any missing field, such as a variable or a task assignee, shows a level that is too low for the question. The step is complete when each query returns the expected records and the owners sign off on the output.
Plan the history cleaning schedule
Using the row counts and retention requirements from the earlier steps, the team defines how long history is kept and sets a history cleaning schedule that removes older records on a defined cadence. The schedule is tested on the non-production database, and the team checks that the cleaning job completes within its window and that the runtime tables remain responsive during the run. The output is a written retention rule tied to the audit questions, with the agreed cleaning settings recorded for promotion.
Promote the setting with a rollback path
The approved history level and cleaning schedule are promoted to production through the normal change process. The team records the configuration in version control, confirms the engine starts with the new setting, and runs a small set of live instances to confirm that history rows appear as tested. The step is done when a post-change check matches the non-production results, and the rollback procedure, including how to restore the previous setting for new instances, is documented and rehearsed. Changing the level affects instances started after the change, so the team confirms how existing instances behave before the change window opens.
Flowable history cleaning schedules by environment
The goal in development is fast feedback. Developers need to see that a process completes, that variables are written and that a failed step is visible, and they rarely need months of history. A lighter history level keeps the local database small, makes test runs quicker and avoids cluttering queries while a model is still changing. Retention here is a convenience setting, not a compliance one, so it does not need to match production policy. Cleaning can run rarely or be triggered manually, since local databases are often recreated.
- History level: Use the lightest level that still lets developers inspect the activities they are building, typically none or activity.
- Volume: Expect small datasets created by hand or by test fixtures, so cleaning rarely matters.
- Retention: Keep it short and document that it is not based on the organization's retention policy.
- Schedule: Run cleaning on demand or during test setup, not on a continuous timer.
- Data: Use synthetic data only, never a copy of production records.
Confirm in the Flowable docs for your version how the history cleaning job is configured, and check that your local settings do not diverge from the test environment in ways that hide defects.
The goal in test is realistic volume. Performance results, cleaning behavior and table growth only mean something when the history data resembles production in size and shape. Test is the place to find out whether the chosen history level and cleaning schedule keep up with the expected job load. The history level should match the one planned for production so that write costs are measured accurately. Retention should be set to the same value as the production design, so the cleaning job removes the same kinds of rows it will remove later.
- History level: Match the level planned for production, so write volume and table growth are measured accurately.
- Volume: Load a dataset sized from production process metrics, ideally a sanitized copy of production data.
- Retention: Mirror the production retention value once the organization's policy has set it.
- Schedule: Run the cleaning job on the same cadence as production and measure how long each run takes.
- Verification: Check that deleted rows match the retention rule and that active instances are untouched.
Before enabling cleaning in production, test it on a copy of production data and confirm the schedule and configuration against the Flowable docs for your version.
The goal in production is retained evidence. History is often the record auditors and business owners rely on to reconstruct what happened to a case, so the history level must capture what the policy requires. Retention periods come from the organization's policy, not from a Flowable default, and the policy should be agreed with compliance and records owners before the schedule is set. Cleaning keeps the database manageable, but a poorly timed or misconfigured run can remove evidence, so changes should be reviewed and monitored.
- History level: Choose the level that captures the audit detail your policy requires, accepting its write cost.
- Retention: Set the period from the organization's retention policy, and document who approved it.
- Schedule: Run cleaning during a low-load window, with monitoring of duration and database growth.
- Backups: Confirm that backups and any archive of history exist before retention deletes rows.
- Change control: Treat changes to the level, retention or schedule as controlled changes with a rollback plan.
Confirm the cleaning job settings for your Flowable version and test them on a copy of production data before enabling the schedule.
Security and data protection risks in Flowable history
Flowable history is a copy of runtime data kept for audit and reporting, so it often holds the same personal and financial details as the process itself. The cards below cover what history stores, who can reach it, what backups copy and how long it lives, and each one names the control your application or operations team must put in place.
Personal and financial data in variables
Historic process variables are written to history at the level you choose, so a customer identifier, account number or income figure set during a process can persist long after the instance ends. Review which variables you pass into processes and case instances, and keep sensitive values out of variables where a reference or token will do. Map each variable to a data category before you select an audit or full history level.
Access to history APIs
The history service and the Flowable REST application return historic instances, activities and variables to any caller the application allows through. The engine does not check whether a user may read a given instance's history, so the application must enforce that check on every query. Test that a user who can see a task cannot pull history for other customers' cases through the same endpoints.
Backups that copy history tables
Database backups include every history table, so a restore brings back data you may have already purged from the application's point of view. Confirm which history tables hold personal data, how long backups are kept, and who can restore them. Plan deletion so that retained backups fall within the same retention rules as live data, and document the backup window in your records.
Deleting history under retention rules
History grows with every instance, and deleting it is the only way to satisfy a retention limit that applies to historic data. Flowable provides history cleaning, but the retention period is a business and legal decision your organization must set. Confirm the period with your data protection lead, configure the cleaning schedule to match, and check that cleaning removes the records you expect.
Audit trail integrity
Audit levels record who did what and when, and that record is only useful if its timestamps are reliable. The configuration docs note that MySQL versions below 5.6.4 lack millisecond precision, which affects ordering of closely spaced events. Verify the database version and timestamp precision before you rely on history as evidence.
Questions buyers ask about Flowable history levels
What drives the cost of changing a Flowable history level?
The main driver is how much existing history data and how many running process instances the change touches. Moving to a higher level means the engine writes more rows per step, so the first question is how many processes and how much daily volume will be affected. Changing the level on a live system also needs a test run against a copy of production data to measure write growth, which adds analysis and test-environment work. Ask any partner to price the history review, the load test, the cleaning job design and the rollout separately, so you can see which part scales with your process count.
Can our own team set the history level and cleaning job?
Yes, if you have engineers who can change Flowable configuration and a DBA who can own the database side. The level is set in engine configuration, and history cleaning is a scheduled job that you define for your retention rules. The harder part is deciding the level per process, agreeing retention with audit and legal contacts, and proving the database holds up under your real volume. A partner can run that analysis alongside your team or hand over a documented approach, depending on the written scope.
How long does a history review and load test take?
The duration depends on the number of process definitions, the expected instance volume, how many audit questions must be answered, and how many environments you can use for testing. Reviews grow quickly when many processes need individual decisions, while load testing grows with the number of volume scenarios you want to prove. Your team should ask for a timeline in the written scope rather than a generic estimate, and confirm which production volumes the test will reproduce.
What do we need from our team during the engagement?
Expect to provide process owners who can say which history is needed for business decisions, a DBA who can review table growth and cleaning impact, and an audit or compliance contact who can define retention and evidence requirements. Engineers who maintain the Flowable deployment are needed to provide configuration, deployment pipelines and access to a representative test environment. Naming these people before work starts usually shortens the review more than any other single step.
Does changing the history level affect running process instances?
The history level controls what the engine records going forward, so a change affects how new activity is written and does not rewrite the history of completed work. Running instances may have partial history under the old level, which matters if an auditor asks about them. Before a change, confirm with your process owners how in-flight instances should be treated and test that behavior in a non-production copy. Flowable's documentation on configuration is the right starting point for checking the exact behavior of your version.
What risks should we check before we reduce history?
The main risk is losing evidence that a regulator, auditor or internal investigator later needs. Reducing history can also break reports or dashboards that query historic variables and task data. Check every consumer of history before reducing it, including monitoring, reporting and any compliance evidence collection. Keep a rollback plan, and confirm with your security and compliance leads which events must remain available and for how long.
Will the engagement include a written scope before work starts?
Most DeployOpen engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing before work starts. Ask for the scope to list the processes reviewed, the volume scenarios tested, the cleaning job design, the handover items and the people you must provide. That document is what you compare between quotes, and it should explain what is one-time work and what recurs, such as ongoing retention reviews.
Limits to confirm for your Flowable version and database
History behavior, framework wiring and database support all shape how much history Flowable writes and how cleaning behaves. Confirm each limit below with your Flowable version, your database administrators and your platform team before you choose a history level.
Async history on your version
Async history was removed in Flowable 7.0.0, so the history write path you read about in older guides may not exist in your release. Confirm which history settings your version still supports and whether history is written in the same transaction as the process step. Ask your Flowable engineers to verify this against the release notes for your exact version before you size any database. Also confirm whether your team depends on any older history configuration keys that were removed.
Spring Boot 4 configuration wiring
Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 and does not support Spring Boot 3, so history settings declared in older application properties may not bind as expected. Check that your history level, cleaning properties and datasource settings are read at startup by inspecting the running configuration, not only the files. Confirm the Jackson library in use, since Jackson 3 is the default. Your application team should own this check and rerun it after every framework upgrade.
Database support and precision
Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. On MySQL, versions below 5.6.4 lack millisecond precision, which can flatten history timestamps and distort duration reports and ordering of audit entries. Confirm your database engine version with your DBA, and confirm the timestamp column types Flowable creates in your schema. Plan to test duration and ordering queries against real history rows before you rely on them for audit evidence.
Cleaning job and table growth
History cleaning removes old history rows on a schedule, but the cleaning window, batch size and run time must fit your write volume and your maintenance window. Test the cleaning job on a copy of production volume with the same database engine, and measure how long a run takes and how table size changes over several cycles. Ask your DBA how indexes, purge locking and replication lag behave during a large delete. Record the results before you set the retention period for production.
Embedding and deployment mode
Flowable can run as a JAR inside a Java application, in a servlet container, inside Spring, or through the REST application, and each mode changes where history writes and cleaning jobs run. Confirm which mode your team uses and whether more than one node shares the same schema. Shared schemas need agreement on which node runs cleaning, so two nodes do not delete the same rows. Your platform team should document this topology alongside the history level decision.
Audit requirements from compliance
The history level you choose must match what your auditors and control owners expect to see, such as who started a process, when a decision changed, and which variables were set. Ask your compliance lead to list the evidence fields and retention periods they need before the engineers choose a level. Confirm with them whether history held in the Flowable schema counts as the system of record, or whether a copy must go to a separate log store. Independent auditors decide whether your evidence is sufficient, not DeployOpen or the engine.
How DeployOpen scopes Flowable history and cleaning work
DeployOpen plans Flowable history levels as part of the engine design, before the first process goes live. We set the history level from your audit requirements, measure the write load it creates, and put a history cleaning schedule in place that your database team can run and monitor.
How we scope
- We record which audit questions the business must answer and which process events each one needs.
- We map those needs to the none, activity, audit and full history levels and note the write cost of each.
- Engagements are fixed-scope, with the history level, cleaning schedule and deliverables agreed in writing before work starts.
- We confirm retention periods with your compliance and records owners before any cleaning job is configured.
How we build
- We configure the history level in the Flowable engine configuration and check the setting in each target environment.
- We test representative process runs at the chosen level and record table growth and database load per run.
- We build history cleaning jobs and test them against a copy of production data to confirm what gets removed.
- We check the history tables and indexes in your chosen database, such as PostgreSQL or Oracle, against expected volume.
How we hand over
- You receive the written history level decision, with the audit reasoning behind each choice.
- You receive the cleaning schedule, job configuration and runbook, written for your operations team.
- Your team receives walkthroughs covering how to change the history level later and what that change affects.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- We can review table growth and cleaning job results on a schedule agreed in the retainer scope.
- Changes to the history level after go-live can be scoped as a new fixed-scope piece of work.
