Flowable history levels and audit trail

Choosing Flowable history levels and audit trail for your process applications

A regulated team that needs evidence of who did what and when has to decide three settings together: the history level the engine records, whether form submissions are tied to the authenticated user, and how long history is kept before it is cleaned. Set separately, they can produce a log that is either too thin to answer an auditor's question or so large that queries and cleanup jobs slow the platform down. Start by listing the questions your auditors and process owners will actually ask, such as who approved a step, which values were on the form at submission, and what the instance looked like on a given date. Those questions determine the minimum history level you need, and the retention period your policy requires determines how much history must be kept online.

Flowable's docs define history levels in ascending order of detail. The audit level is the one most often chosen for evidence: it archives all process instances and activity instances, keeps variable values in sync, and records submitted form properties so that user interaction through forms can be traced. Lower levels record less and may be enough for operational reporting, but they will not give you the form-level trail that audit questions usually require. Confirm the exact behavior of each level, and the performance cost of the one you pick, against the Flowable docs for your version before you write it into your configuration. Also confirm how your chosen level interacts with any custom history listeners, since those can add records of their own.

Form linkage and cleaning are where audit trails most often fail in practice. The docs state that if the authenticated user is set before form submission, that user is accessible in history, so your application must set the user in the security context before the engine handles the submission, or the trail will show a submission with no identified actor. For cleaning, the Spring Boot configuration uses flowable.enable-history-cleaning, flowable.history-cleaning-after and a cron cycle to remove history older than the retention window. Before you enable it, agree with compliance how long each class of process must be retained, export the evidence you must keep outside the engine if that period is shorter, and test the cleaning job in a non-production copy so you know what it removes.

Which Flowable history level fits which evidence need

This table compares the Flowable history levels by what each records, the evidence it can support and the storage and query load it adds. Read it by starting from the evidence an assessor or investigator will ask for, then choosing the lowest level that still records it. Confirm each level's exact behavior against the Flowable docs for the version you run before you set it.

History level	What it records	Evidence it supports	Storage and query load
None	No history is written by the engine	Only what your application stores itself, such as its own business records or logs	Lowest engine load, but no engine-held trail to query after completion
Activity	Process and activity instances, so you can see which steps ran and when	Sequence of steps for a case, useful for operational review and basic timing questions	Moderate growth in history tables, scaling with the number of activities per instance
Audit	Archives process and activity instances, keeps variable values in sync and records submitted form properties	Traceable user interaction through forms, with the authenticated user if it is set before submission	Higher growth, driven by variable updates and form data; plan retention and cleaning before go-live
Full	Everything the audit level records plus the most detailed history the engine offers for the version in use	Most complete reconstruction of engine activity, including detail for disputed decisions	Highest storage and query load; confirm which extra data it adds before choosing it for high-volume processes
Retention and cleaning needs	Depends on the level chosen and the cleaning schedule you configure	Evidence must still be available for the period your policy requires, so cleaning must not run earlier	Tables grow with volume until automatic history cleaning or your own archive process removes old data

How form submissions get linked to the authenticated user

The Flowable docs say that a form submission is attributed to a user in history only if the authenticated user is set before the submission happens. The engine does not look up who is logged in at the moment the history record is written, so the application must put the user identity on the current engine context before it calls the form submit operation. In a Spring application this usually means setting the authenticated user in the Flowable identity context inside the request filter or service method that handles the submission, then clearing it afterward so the value cannot leak into the next request handled by the same thread. Your team should confirm the exact setter and clearing calls against the version of the engine you deploy, and should check how your framework's security context is propagated to the thread that runs the submission.

Service accounts, scheduled jobs and delegated actions need separate treatment. A background job that completes a user task on behalf of a manager, a timer that submits a form, or an integration that posts a decision from an external system has no interactive session, so history will show either no user or whatever identity the thread happened to carry. Decide in advance which identity each path should record, such as a named service account for system actions and the original requester for delegated ones, and record that choice in your process design. Where a delegated action must show both the person who asked and the system that executed it, you will need to store the second identity in a form property or variable, because the engine's user field holds only one value.

Treat this path as a control to test, not a configuration detail. Build a test for each submission route in your application (interactive, API, job and delegated) and assert the user recorded in history after each one, including a failed or concurrent submission to confirm the identity does not carry over between requests. Ask your auditors which evidence they will request for a given form, then confirm that the history query returns that identity for a sample of real instances in a non-production environment. Repeat the check after each upgrade, since changes to security integration or thread handling can silently break attribution.

How to set up history levels and automatic cleaning in Flowable

This sequence sets the history level for each process type, turns on automatic history cleaning with a retention window, and proves with test instances that evidence is recorded and that cleaning removes only the records it should. The result is a history configuration you can explain to auditors and operate without filling the database.

Classify processes by evidence need
The process owner, compliance lead and an engineer agree which process types need full evidence, which need only activity records, and which need little or no history. Write the decision down per process definition, with the reason and the retention period the business requires. Done when every deployed process type has a named history level and an owner who signed off on it. Confirm the retention requirement with your compliance function before you set any cleaning value, because the engine does not decide it for you.
Set the history level in the engine
The platform engineer sets the history level in the engine configuration, choosing from none, activity, audit and full. Audit level archives all process and activity instances, keeps variable values in sync and records submitted form properties, so it is the level most often used where user interaction must be traceable. If different process types need different levels, confirm with your engineers how the chosen engine setup applies that per definition before rollout. Done when a test deployment reports the configured level at startup and the configuration is in version control.
Set the authenticated user before form submission
The application developer ensures the authenticated user is set in the engine context before any form is submitted, so that the submitting user is attached to the history record. Without this step, form submissions may be recorded without an accountable person. Test this with a form submitted under a known account and check the history query for that user. Done when the test submission returns the expected user identifier from history, and a submission without an authenticated context is flagged as a defect in your test plan.
Configure automatic history cleaning keys
The platform engineer adds the Spring Boot keys flowable.enable-history-cleaning set to true, flowable.history-cleaning-after set to the retention window agreed in the first step, and a cron cycle such as 0 0 1 * * ? to schedule the job. Store these values in the same configuration repository as the rest of the engine settings, and review them in the same change process. Done when the application starts with the keys visible in its effective configuration and the cleaning schedule appears in the engine's job logs at the expected time.
Test that records appear in history
The QA engineer starts several test instances of each process type, completes tasks, submits forms and runs a few to completion. Then they query history for activity instances, variable values and form properties, and confirm the records match what the level promised. Compare the results against the audit requirement from step one. Done when every test case returns the expected history records with the correct authenticated user, and any gap is logged and resolved before cleaning is tested.
Verify cleaning removes only expired records
The QA engineer creates test instances with completion dates older than the retention window, plus instances that are still running or completed within it. They run the cleaning job, either on the schedule or through a controlled trigger in a non-production environment, and check that only the expired history is removed. Running instances and recent records must remain queryable. Done when the before and after counts match the expected outcome and the result is documented in the test report.
Document and monitor the configuration
The engineering lead writes the final configuration into the operations runbook: history level per process type, retention window, cron schedule, and the query used to prove evidence. The operations team adds monitoring of history table growth and of the cleaning job's logs so that a silent failure is noticed. Done when the runbook is approved, the monitoring alert is live in a non-production environment, and someone outside the build team can explain the retention decision to an auditor.

Querying history for evidence by audience

Auditors ask whether they can reconstruct what happened to a case, who acted on it and what data they saw at each step. They need a trail that is complete for the period under review, and they need to show that the trail itself was not altered or cut short by cleanup. For this group the history level, the retention period set by automatic history cleaning and the user identity recorded on form submissions matter more than query speed.

Reconstruction questions: Which instances ran for a given product or customer in a date range, which activities they passed through, and which decision outcome was recorded.
Actor attribution: Whether the authenticated user was set before each form submission, so the submitting person is visible in history rather than inferred.
Retention alignment: Whether the cleaning window covers the retention period the auditor expects, since records removed by cleaning cannot be queried afterward.
Read-only access: A query path that auditors can use without the ability to change process state or edit history rows.
Export evidence: Repeatable query output that can be kept with the audit file and rerun later to confirm the same results.

Before an audit window opens, confirm with your compliance lead which retention period applies and test one reconstruction end to end on a non-production copy.

Security and operational risks in recorded history

Recorded history is useful evidence, but it also holds personal data, access paths and background jobs that the operator must govern. The four risks below connect retention, access and cleaning, and each one needs a decision before the history level goes live.

Personal data outlives its purpose

At the audit level, Flowable archives process and activity instances and keeps submitted form properties, so names, contact details and free-text answers can end up in history tables long after the case closes. Decide which form fields and variables carry personal data, whether they must be recorded at all, and what retention period your data protection policy sets. Then confirm that flowable.history-cleaning-after matches that period, not a convenient default.

Cleaned history an auditor still needs

Automatic cleaning removes history older than the configured age, and it does not ask whether a regulator, internal audit or a dispute still needs that record. Before enabling cleaning, list the evidence each process must keep and where it is exported or archived. Test a restore or a query for a closed case from the oldest period you promise to support, so the retention setting does not silently break an evidence request.

Unauthorized readers of history tables

History tables hold task assignees, started-by users, variables and form submissions, which can reveal decisions and personal information to anyone with database read access. The engine does not apply your application's authorization rules to direct SQL. Limit read grants on history tables to the reporting and audit roles that need them, separate them from application service accounts, and log the queries that touch them.

Cleaning jobs competing with production

History cleaning runs as a scheduled job on the same engine that runs the async executor, so a large delete can contend with timers and asynchronous jobs for database resources and locks. Choose a cron window outside business peaks, such as the illustrative 0 0 1 * * ? pattern from the docs, and confirm it against your actual load profile. Monitor job execution during the first cleaning runs and check that lock expiration and job pickup still behave normally on every node.

Limits and what to confirm in your environment

History settings look simple in configuration, but their effect depends on your database, your retention obligations and the Flowable version you run. The cards below list the items to confirm with your team and your vendor before you rely on history as an audit record or set a cleaning schedule.

Database timestamp precision

Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. The configuration docs note that MySQL versions below 5.6.4 lack millisecond precision, so history timestamps can be coarser than the engine expects. Confirm your exact database version, check how ordering of closely spaced events behaves, and test it with a sample audit query before you treat timestamps as evidence.

Retention against legal obligations

The cleaning period set in flowable.history-cleaning-after is a technical setting, not a legal decision. Ask your legal, records and compliance owners which retention period applies to each process type, including any minimum periods and any deletion duties for personal data. Record the decision, then set the Flowable value to match it.

Coverage of every history table

Confirm whether automatic cleaning removes records from every history table used by the version you run, including activity, variable and form data, before you assume a full purge. Run cleaning against a copy of production first, count rows before and after, and check that runtime data is untouched. Repeat this check after each upgrade because table coverage can change between releases.

History growth and backups

At audit level, every process instance, activity and form submission is archived, so history tables can grow faster than runtime tables. Ask how much history your workload produces per month, how that growth affects backup duration, restore time and storage, and whether restores need the history tables to match the runtime state. Size your backup window with these numbers.

Authenticated user in forms

Form submissions are only linked to a person if your application sets the authenticated user before submission. Confirm how your identity provider passes the user into the engine, test a submission from each client path, including REST calls and background jobs, and check that service accounts are not recorded as the actor for human decisions.

Version-specific history behavior

History behavior and configuration keys are tied to the Flowable release you run. Before you rely on a setting, confirm it against the documentation for your exact version, and check the release notes for changes to history, async jobs or the Spring Boot baseline that affect cleaning jobs.

Questions buyers ask about Flowable history and audit trails

What drives the cost of setting up Flowable history and audit trails?

The cost depends mostly on how many process and case models need history decisions, how much form and user traceability your auditors expect, and how many environments must be configured and tested. Each history level, retention period and cleaning schedule adds a configuration and verification step. Ask any partner to price these as separate line items: discovery of retention rules, configuration per application, test evidence, and handover documentation. A quote should follow from a written scope, and DeployOpen works to fixed scope agreed in writing before work starts. Ongoing support of the history setup is a separate recurring item if you want one.

How long does it take to set up history levels and cleaning?

Duration depends on scope and environment, so no fixed timeline applies across all projects. The biggest factors are the number of applications, whether your retention rules are already written down, and how your databases and deployment pipeline are managed. A single Spring Boot application on one supported database is simpler than several engines spread across clusters with separate database owners. Confirm the expected duration in the written scope, and ask which environments (development, test, staging, production) are included and how long each review step takes on your side.

What does our team need to provide for this work?

You need to provide the business rules that define how long records must be kept, who must be identifiable in history, and which processes contain regulated or personal data. Your team also needs access to the target environments, the database administrators who own the schema and backups, and a named approver for retention decisions. Engineers should share the Spring Boot or Java configuration in use, and the process definitions that will run. Missing retention rules are the most common cause of rework, so settle them before configuration starts.

Can our own team configure Flowable history without a partner?

Yes, a capable Java team can set the history level and cleaning properties themselves, because the configuration is documented in the Flowable docs and uses a small number of keys. The harder work is the decision layer: deciding which level suits each process, proving that form submissions are linked to the right authenticated user, and showing auditors that cleaning does not remove records still required as evidence. Teams that lack a test strategy for history or no time for audit evidence often bring in a partner for that part only.

Which history decisions must be made before go-live?

Settle the history level for each application, the retention period before cleaning removes data, and whether cleaning runs on a schedule that avoids peak hours. Also decide how the authenticated user is set before form submission, since that user is only accessible in history if set in time. Record who approves retention changes and how exceptions are handled. Changing these later can leave gaps, so document each decision in the design before production deployment.

How do we check that history cleaning is working as intended?

Start by confirming the properties in your configuration, such as flowable.enable-history-cleaning, flowable.history-cleaning-after and the cron cycle, match the approved retention rules. Then run cleaning in a non-production environment with known test instances, and verify which records are removed and which remain. Keep the test results as evidence. Check table sizes and job logs after the first scheduled runs in production, and compare them with the expected retention window.

What are the main risks of choosing a history level too low or too high?

A level that records too little can leave auditors without the activity trail, variable values or submitted form data they need to reconstruct a decision. A level that records too much increases database volume, which affects performance and backup size over time. Both risks come from the same decision, so tie the level to documented control requirements rather than to default settings. Ask any partner to show how the chosen level and cleaning schedule were tested against your evidence requirements, and confirm the results with your auditors.

How DeployOpen scopes history, audit and cleaning work

DeployOpen plans, implements, documents and supports self-hosted Flowable engines inside your own infrastructure. For history, we start by agreeing which history level each process needs, then build and hand over the retention, form-user traceability and cleaning settings as written, tested and documented parts of the engagement.

How we scope

Inventory each process and case, and record the evidence questions its history must answer.
Agree the history level per application in writing, with the reasons for activity, audit or full.
Set the retention period and the cleaning schedule against your data protection and records rules.
Confirm which form submissions must carry the authenticated user and how that identity is supplied.
Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts.

How we build

Configure the history level and cleaning properties in your Spring Boot or engine configuration.
Verify that form submissions record the authenticated user before go-live, using test accounts.
Test cleaning runs on a copy of production-sized history tables to confirm timing and table growth.
Check that the audit level keeps variable values and form properties for the evidence queries you defined.
Review history queries against your audit questions so reports return the records the business needs.

How we hand over

Document each history setting, its owner, its reason and the environment where it applies.
Provide the evidence query set and an explanation of what each query shows and does not show.
Record the cleaning schedule, the retention period and how to change them through a controlled release.
Walk your operations and compliance staff through the history tables and the cleaning job logs.
Confirm with your auditors which history records they expect and whether they need further retention.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Review history volume and cleaning results after major releases or changes in process volume.
Retest the form-user and audit settings when the identity provider or application login changes.
Confirm with your team that cleaning does not remove records still needed for open cases or disputes.
Plan Flowable version upgrades so history settings and table changes are checked before rollout.

Flowable history levels, audit trail and history cleaning