Flowable process definition cache settings: when they matter for your deployment
If you run dozens or hundreds of process definitions, several tenants, or a cluster of engine nodes, the deployment cache becomes a setting you need to understand before go-live. The deployment cache holds parsed process definitions (the in-memory form of deployed BPMN, CMMN and DMN models) so the engine does not reload and reparse them from the database on every request. Its size and behavior therefore affect memory use on each node, how quickly a new or updated definition takes effect, and how often the engine goes back to the database. The Flowable configuration docs describe this cache as part of the engine configuration, and the same engine code runs whether you embed it as a JAR in a Java SE, servlet, Spring or Java EE application or call it over HTTP through the Flowable REST application.
Start by counting what you actually deploy. Count active definition versions per engine, not just distinct process keys, because each deployed version is a separate cache candidate. Then count tenants, since each tenant can carry its own definitions, and note how often you deploy. Frequent deployments and many versions raise memory pressure and make cache churn more visible. In a cluster, each node holds its own cache, so a deployment made through one node must reach the others before they serve the new version. Ask your engineers how the chosen Flowable version invalidates or refreshes cached definitions across nodes, and test a rolling deployment against live traffic before you rely on it. The async executor coordinates nodes through database lock records, but that mechanism does not by itself describe definition cache consistency, so confirm the behavior separately.
Before you tune anything, confirm the exact property names, defaults and cache-related classes in the configuration documentation for your Flowable version, because they change between major releases. Read the Flowable configuration docs for the version you run, then check the upgrade notes for your target release. A custom cache is worth the effort only when measurements show definition loading or memory use limiting throughput or stability, and when you can test eviction, cross-node consistency and restart behavior. Otherwise, sizing the default cache for your known definition count and a realistic deployment cadence is usually the lower-risk step.
Which Flowable process definition cache settings fit which deployment shape
This table compares the four option groups a team can set for the process definition cache: size limits, enlargement for many tenants, node-local refresh after deployments, and custom cache implementations. Read each row against your deployment shape, then confirm the property names and defaults in the configuration docs for your target version before you size anything.
| Option group | When it fits | What it costs | What to verify for your version |
|---|---|---|---|
| Default cache limits | A small, stable set of process definitions on a single engine node | Memory held per node grows with deployed definitions and versions; reloads from the database happen when entries are evicted | The configuration docs for the cache size or count setting and its default in your Flowable release |
| Enlarged cache for many definitions | Many deployed versions or many tenants whose definitions are active at the same time | More heap per node; a cache too small for the working set causes repeated database reads for definition lookups | Whether the cache size setting applies per engine or per process definition type, and how it interacts with tenant deployments |
| Node-local cache refresh after deployment | Clusters where several engine nodes serve the same definitions and a new deployment must reach all of them | Nodes that have not refreshed can serve an older definition until their cache is updated, so routing and test steps must allow for that window | How the target version refreshes or invalidates the local cache across nodes, and what the advanced docs say about shared state |
| Custom cache implementation | A team needs cache behavior the built-in option cannot give, such as shared storage, metrics or a specific eviction policy | Your team owns the implementation, its thread safety, its failure handling and its upgrade path across Flowable versions | The configuration docs for supplying a custom cache, and whether the interface changed in the release you plan to run |
| Cache sizing review before go live | Any deployment that changes definition counts, tenant counts or versions | Load tests and database read monitoring take engineering time, recurring at each major change | Count of definitions and versions per node, and database query counts for definition lookups under realistic load |
How cache settings differ for single-tenant, many-definition and multi-tenant deployments
A single application with a small, stable set of process definitions is the simplest shape. The definitions are deployed by the application's release pipeline, the set rarely changes, and most of the cache holds the same handful of entries for the life of the process. Memory growth is small and mostly predictable from the number of deployed definitions and their versions. The main consistency question is whether every running instance of the application deploys the same definitions at the same time, because a node that has not yet loaded a new version can serve stale work until its cache is refreshed. A cache miss in this shape is usually a one-time cost after startup or a redeployment, when the engine parses the BPMN or CMMN XML again and rebuilds the process definition objects.
- Startup and redeploy cost: Measure how long the first execution of each definition takes after a restart, since that is where most misses occur.
- Version overlap: Check whether old versions remain deployed and still hold running instances, because they keep occupying cache entries.
- Node agreement: Confirm that all nodes finish deploying before traffic reaches them.
- Heap headroom: Record heap use after a full deployment cycle to see whether the default limits leave room for the application.
- Miss rate under normal traffic: Confirm that the miss rate stays near zero once the application is warm.
Before you change any limit, check whether your release process causes repeated cold starts that the current settings do not absorb.
A single platform that holds many process definitions, often with several versions of each, changes the cache problem. The number of entries grows with the catalog, and old versions stay in the cache while running instances still use them. Memory use then depends on the total definition count, the size of each model, and how many versions remain active. Consistency across cluster nodes matters because different nodes may hold different subsets of definitions in memory after a deployment. A cache miss here can be expensive when many distinct definitions are requested in a short window, because each miss means parsing and building a definition that the engine may have evicted. Repeated misses across a broad catalog can show up as latency spikes on the first request for each process.
- Catalog size: Count deployed definitions and active versions, and note which ones receive traffic.
- Eviction pattern: Watch whether frequently used definitions are evicted because rarely used ones fill the cache.
- Instance age: Identify how long instances of older versions run, since their definitions stay in use.
- Miss latency: Time the first execution of definitions that were recently evicted, compared with warm executions.
- Node divergence: Compare which definitions each node holds after the same deployment sequence.
Before you change limits, ask which definitions carry most of the traffic and whether your version retention policy keeps old definitions in use longer than you expect.
In a multi-tenant platform, each tenant deploys its own definitions, so the cache holds definitions owned by many parties with different release schedules. Memory growth follows the combined catalog of all tenants, and one tenant's large deployment can push out entries that other tenants need. Consistency becomes a per-tenant question: a tenant's new definition must reach every node that serves that tenant, while other tenants should not notice the change. Tenant isolation also affects which settings you can justify, because a limit that suits one tenant may starve another. A cache miss is tenant-specific and can look random to operators, since it depends on which tenant was active recently. Measurement needs to be broken down by tenant to show where misses and memory use come from.
- Per-tenant volume: Measure definition counts and execution rates for each tenant, not only platform totals.
- Noisy neighbors: Check whether one tenant's deployments or traffic evict entries that other tenants use.
- Cross-node visibility: Confirm that a definition deployed for one tenant appears on every node that serves that tenant.
- Miss attribution: Log cache misses with the tenant identifier so you can see which tenants pay the cost.
- Isolation requirements: Record any contractual or regulatory need to keep tenant data and deployments separate.
Before you change any limit or consider a custom cache, confirm how tenant identifiers are used in your deployment and which tenant-level metrics you can collect from the engine.
Setting up and verifying the deployment cache in a Flowable Spring Boot or embedded engine
This sequence takes a team from confirming its Flowable version to load testing the deployment cache with realistic tenant and definition counts, so the cache settings are chosen from measured behavior rather than defaults.
Confirm the Flowable version and starter in use
The platform or engineering lead records the exact Flowable engine version, whether the application uses a Spring Boot starter or an embedded engine built from the Java SE or servlet container setup, and the Spring Boot version it runs on. Flowable 8.0.0 requires Spring Framework 7 and Spring Boot 4 and does not support Spring Boot 3, so this check determines which documentation applies. Done when the version, starter artifacts and Spring Boot baseline are written into the change record and match the dependency tree.
Locate the cache settings for that version
The Java or platform engineer opens the configuration documentation for the same engine version and lists every cache-related property that governs process definition caching, including any that differ between the embedded engine and the Spring Boot starter. For Spring Boot, the starter-specific configuration is in the Spring Boot documentation, so the team reads that section before editing any property. Done when each candidate setting is listed with its default, its scope, and the file where it will be set, and the team confirms no setting is taken from a different major version's docs.
Record baseline memory and definition counts
In a test environment that mirrors production deployment shape, the engineer deploys a representative set of process definitions and tenants, then captures heap usage, the number of deployed definitions and the number of cached definition entries under steady load. The actuator endpoint at /actuator/flowable exposes monitoring data for running processes, and the team uses it alongside JVM metrics from its existing monitoring stack. Done when the baseline values are saved with the timestamp, the workload description and the JVM settings, so later measurements can be compared to them.
Change one cache setting in the test environment
The engineer changes a single cache property, such as the limit on cached definitions, and restarts the test node with no other changes. Changing one value at a time keeps any shift in memory or latency attributable to that setting. Done when the restarted node starts cleanly, the property value is confirmed in the running configuration or startup log, and the baseline capture is repeated under the same workload.
Deploy a new definition version and confirm nodes pick it up
The team deploys a new version of an existing process definition to a cluster with at least two nodes, then starts a new instance on each node and checks which definition version it uses. This confirms that the cache on every node reflects the new deployment and that a stale cached version is not used after the change. Done when each node reports the new definition version for new instances, and existing instances continue on their original version as the model requires.
Load test with realistic tenant and definition counts
The team runs a load test that matches expected tenant count, number of deployed definitions and the share of traffic that touches less frequently used definitions, because cache hit rates depend on that mix. The engineer records memory, definition lookups that miss the cache, and job latency against the baseline for each cache setting tested. Done when the results show whether the chosen limit keeps memory stable across the test window and whether the observed miss rate is acceptable for the expected workload.
Decide whether a custom cache is needed
The architect reviews the load test results and decides whether the built-in deployment cache settings meet the requirement or whether a custom cache implementation is justified. A custom cache adds code the team must maintain and test across Flowable upgrades, so it is only considered when the measured misses or memory use persist after tuning the supported settings. Done when the decision, the measurements behind it, and the settings to promote are recorded and reviewed with the operations team.
When a custom deployment cache is worth building
A custom deployment cache is worth building only when the built-in behavior fails a measured requirement, not because the default looks small on paper. The usual triggers are a very large number of process definitions that an engine node must hold, a tight memory budget per node that the default cache cannot respect, or eviction rules that depend on business context, such as keeping definitions for active tenants resident while retiring others. Before any design work, record the definition count per node, the resident memory each node uses at steady state, and how often definitions are reloaded from the database. If those numbers show no pressure, tuning the configured limits is cheaper and safer.
Owning a custom cache is an ongoing commitment. Flowable's documentation describes extending the engine through its configuration and service interfaces, and you should confirm which interfaces a given version exposes for cache replacement before you design anything, because the supported extension points change between major releases. Treat every upgrade as a potential rewrite of the cache layer, and budget for that work in the same plan that covers the Flowable upgrade notes. The custom code also has to be understood by whoever answers production incidents, which is a staffing question as much as a technical one.
Tests must come before and after the change. Before you replace anything, capture a baseline: cold-start time, definition reload counts, memory per node and latency of the first request after a deployment. After the change, run the same measurements, plus tests that deploy a new process definition version on one node and confirm every other node uses it within the expected window, that undeploy and version rollback propagate the same way, and that a node restart rebuilds its cache correctly. Include failure cases such as a database outage during deployment and a node joining mid-rollout. If propagation cannot be proven under these tests, the custom cache should not reach production.
Security and operational risks of changing the deployment cache
Changing how Flowable caches process definitions touches what every node serves, how deployments reach running engines, and what sits in memory. The cards below cover the risks that tend to surface after a cache change, each with a check you can run before and after the change. Confirm the exact cache behavior for your engine version with the Flowable configuration docs before you rely on it.
Stale definitions on one node
After a deployment, a node that does not refresh its cache keeps serving the previous process definition while others run the new one. Two nodes may then start the same process with different models, and running instances may hit different versions depending on which node picks up the request. Check that every node in your cluster reports the same deployed definition version after a deployment, and test a new instance start against each node before you release traffic. Confirm with the Flowable configuration docs how cache invalidation works across nodes in your version.
Memory pressure after limit increases
Raising the cache size limit lets the engine hold more process definitions in heap memory. On a node with a fixed heap, a larger cache can push the JVM into garbage collection pressure or an out-of-memory restart, especially when many tenants or versions are deployed. Before raising a limit, measure heap use under your real definition count, set an alert on heap and restart counts, and confirm the new limit leaves headroom for peak load. Record the limit and heap settings in the same change request so they are reviewed together.
Pipelines that bypass the refresh path
A deployment script that writes definitions straight to the database, or restarts only some nodes, can leave caches out of step with the repository. The engine then serves definitions that the pipeline and audit records do not match. Route every definition change through the engine's deployment API, and add a post-deploy check that compares the deployed definition keys and versions with the approved release manifest. Ask your team which tools can write to the deployment tables and restrict that access.
Deployment API access changes cache contents
Anyone who can call the deployment or definition APIs can add, suspend or replace what the cache holds. A custom cache that sits in front of those APIs widens this exposure if its inputs are not checked. Limit deployment and definition endpoints to a named service role, log each deployment with the caller identity, and review who holds that role on a schedule. Confirm the authorization model with the Flowable security documentation for your version, since the engine leaves many authorization checks to your application.
Definition details in memory dumps
Cached process definitions include model structure, task names, expressions and sometimes embedded configuration. A heap dump taken during an incident can expose that content to anyone with access to the dump file, which matters where models reveal business rules or integration endpoints. Restrict who can request heap dumps, store dumps in an encrypted location with access logging, and include dump handling in your incident runbook. Ask your security team whether definitions count as sensitive data under your classification policy.
Cache changes without metrics
If cache hit rate, size and eviction activity are not watched, a limit change can degrade performance for days before anyone links it to the cause. Missing metrics also hide stale-cache or memory problems until users report them. Expose the Flowable actuator endpoint in your monitoring stack, add dashboards for heap, garbage collection and definition-related errors, and set alerts with named owners. Review the Flowable Spring Boot docs for the monitoring endpoint your deployment uses.
What to confirm about your Flowable version and environment before tuning
Cache behavior depends on the Flowable release, the Spring Boot baseline, the database and how many nodes share it. Confirm these items first, because a setting that works on one version or topology can behave differently on another.
Flowable line and Spring Boot baseline
Flowable 8.x moved to Spring Framework 7 and Spring Boot 4 and does not support Spring Boot 3, while Flowable 7.x runs on Spring Boot 3 with Java 17 and Jakarta EE. Confirm which line you run, because the cache property keys and their defaults are documented per version. Check the release notes for your line before copying any setting from a blog post or an older project. Ask your team to record the exact version in the tuning ticket so results can be reproduced.
Database type and definition loading
Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and the database shapes how often definitions must be read back from storage. Confirm your database product and version, and whether a managed service sits in front of it. Ask the vendor or the configuration docs how definition lookups are handled for your database, and test cache misses against it rather than assuming behavior carries over from another database.
Node count and shared database
The number of Flowable nodes and how they share one database determine whether each node holds its own copy of cached definitions. Confirm how many application instances run the engine, whether they share a schema, and whether deployments happen through one node or all of them. Test a definition deployment on a multi-node setup and verify that every node resolves the new version, since stale entries in one node are the failure to rule out.
Exact cache property keys and defaults
Cache-related property names and default values differ between configuration styles, including plain engine configuration and Spring Boot properties. Record the exact keys your version reads from its configuration docs, and confirm the default for each before you change anything. Do not state limit values from memory. Write down the effective values at startup from your own logs or configuration dump, then compare them with what the docs for your release list.
Custom cache code and upgrade impact
If your team wrote a custom deployment cache or overrides engine classes, that code is tied to internal types that can change between major releases. Inventory every custom class, bean override and configuration hook that touches the cache. Ask whether any of them must be rebuilt for your target version, and run the custom code against a staging copy of the target release before the production upgrade.
Test evidence and rollback plan
Tuning claims need a baseline measured on your own workload, including the number of process definitions, tenants, deployments per day and the memory your JVMs use. Confirm that you can capture definition count and heap use before and after each change, and that you can revert the setting without a database change. Ask your team to agree on the pass criteria before testing starts.
What buyers ask about cache tuning, cost and effort
What drives the cost of Flowable deployment cache work?
The cost is mostly the team's time, not the configuration change itself. The main components are scoping the process definition inventory, setting up a test environment that matches your node topology, running load tests that show memory and lookup behavior, reviewing results, and writing up the settings you chose. If a custom cache is needed, custom code, its tests and its documentation add further effort. Costs go up with the number of definitions and tenants, the number of cluster nodes, and how many environments must be validated. Under a fixed-scope agreement, ask the quote to list each of these as a separate deliverable with its own acceptance check.
Can our own team tune the Flowable deployment cache?
Often yes, for the standard settings, provided the team can run realistic load tests and read heap and cache metrics. Changing configuration keys is a small step; proving the change is safe across nodes is the harder part. Teams with a strong Java and Flowable operations background usually handle sizing and verification in house. A partner adds value when a custom cache, a tenant-heavy layout or a shared cluster makes the trade-offs harder to test. Ask the partner to state which parts you would keep in house and which they would deliver, so ownership is clear before work starts.
How long does cache tuning take, and what changes the answer?
We cannot give a reliable duration without seeing your environment, so treat any single number with caution. The schedule depends mainly on access to a production-like test environment, the size and variety of your process definitions, the number of tenants, and how quickly test data can be created. Delays usually come from waiting for environments, approvals to run load tests, or missing definition inventories rather than from the tuning itself. Ask for a timeline that lists these dependencies and the dates on which you must supply each one.
What do we need to provide before cache work starts?
Prepare the inputs that determine the sizing and the test design. Confirm the Flowable version and the Spring or Java baseline in use, along with the database type. Provide an inventory of deployed process definitions, CMMN and DMN models, and the number of tenants. Describe the node topology, including how many engine nodes share the database and how they are deployed. Finally, provide a test environment with representative data and access for load generation and monitoring. The written quote should name each input, its owner and the date it is needed.
Does a custom deployment cache need maintenance through upgrades?
Yes, if you replace or extend the default cache. A custom implementation depends on engine internals that can change between major versions, so each upgrade needs a compatibility check, regression tests and a review of the cache code. The default cache avoids this burden but may need different limits after a version change. Ask whether the quote includes upgrade verification for the cache and whether support is handled under a separate retainer. Upgrade notes for each Flowable release should be reviewed before the cache code is reused.
How do cache changes interact with the async executor and history settings?
Cache changes affect the engine's memory profile, so they interact with the async executor and history settings through heap use and database load. A larger cache can reduce repeated definition lookups, but more threads in the async executor and heavier history writes compete for the same memory. Tune these together in the same test campaign, and change one setting at a time so results are attributable. Ask the quote to include a combined test plan covering the async executor, history level and cache limits, not three separate studies.
What should a written quote for cache work include?
A useful quote lists the scope in concrete items: the inventory review, the environments used, the load test scenarios, the number of test cycles, any custom code and its tests, the documentation delivered, and the handover session. It should state what is excluded, such as production changes, upgrades or ongoing monitoring. Ask for acceptance criteria for each deliverable and for the assumptions about environment access and data. Because DeployOpen works from written scope, the quote should be traceable to these items rather than to a general estimate.
Is cache tuning a one-time task or does it recur?
The initial sizing and verification are one-time work, but the settings need review when definition counts, tenant numbers, node counts or Flowable versions change. Growth in deployed definitions is the most common trigger. Plan for periodic checks in your operations routine and decide who owns them. If you want ongoing review, ask for it as a separate retainer with defined review points, rather than assuming it is covered by the initial engagement.
How DeployOpen scopes and delivers Flowable cache tuning
DeployOpen plans Flowable process definition cache settings as a written, fixed-scope piece of work inside your own infrastructure. We start from how many definitions and tenants your engines load, then agree what gets measured, changed, tested and handed over before any tuning begins.
How we scope
- Inventory deployed process and case definitions, tenants and nodes that share one database.
- Record current cache behavior, memory use and definition reload patterns under representative load.
- Agree in writing whether standard cache settings suffice or a custom cache is in scope.
How we build
- Apply and test cache limit changes in a non-production environment that mirrors your cluster layout.
- Verify behavior across cluster nodes, including how definitions reach each node after a new deployment.
- Build and test any custom cache implementation against the Flowable configuration points, with rollback steps.
How we hand over
- Document each setting changed, its reason, the measurements taken and the expected memory footprint.
- Provide runbooks for deploying new process definitions and for clearing or resizing the cache safely.
- Walk your platform and engineering teams through monitoring signals and the thresholds that should trigger review.
How we support
- Offer ongoing support, upgrades and re-tuning as a retainer when definition counts or tenant numbers grow.
- Review cache behavior again when you upgrade Flowable, since configuration details can change between major versions.
- Confirm the supported configuration keys and defaults for your exact Flowable version with the release documentation before each change.
