Why Flowable 8 Jackson 3 migration affects your process scripts
If your team runs Flowable 7.x and stores JSON variables, calls JSON methods in script tasks or uses JSON in expressions, the Flowable 8 default JSON library is Jackson 3, so those parts of your models need a deliberate plan before you move. The supported first step is to keep Jackson 2 by setting flowable.variable-json-mapper=jackson2 in Spring Boot, which Flowable 8 still supports. The Flowable 8.0.0 release notes recommend this setting as the starting point if you are unsure, so it is the safe default for a team that has not yet tested its scripts.
This migration sits inside the wider Flowable 8 upgrade, which also moves the platform to Spring Framework 7 and Spring Boot 4 with no Spring Boot 3 compatibility. Treat the Jackson decision as a separate, reviewable step. Keep the Jackson 2 setting while you upgrade the engine, application code and test suites, confirm that the process suite is green, and only then schedule the move to Jackson 3 as its own change with its own test run. Mixing the two in one release makes failures hard to attribute, because a broken script could come from the framework, the mapper or the JSON library.
What changes in Jackson 3 and what each change breaks
This table lists each Jackson 3 change in Flowable 8 that can affect process scripts, expressions and JSON variables, with the likely breakage and the action to take. Read it as a checklist: find the changes that match your models, then test each affected expression before choosing between Jackson 3 and the Jackson 2 mapper setting.
| Change | Impact on scripts and expressions | Action needed |
|---|---|---|
| Jackson 3 is the default JSON library in Flowable 8 | Script and expression code that relies on the default JSON mapper may now receive Jackson 3 objects, so behavior can change without any edit to the model | Confirm which JSON library your engine uses at startup and record it in your migration plan |
| Jackson 2 variables still supported | Existing JSON variables can keep working if the engine stays on the Jackson 2 mapper, so the change does not have to land in the same release | Review the flowable.variable-json-mapper setting and decide whether to keep jackson2 as a first step |
| flowable.variable-json-mapper=jackson2 setting (Spring Boot) | Keeps Jackson 2 for JSON variables, which the release notes recommend as a starting point if unsure | Set it explicitly during the first upgrade, then move to Jackson 3 in a separate, tested change |
| Package rename to tools.jackson.databind and tools.jackson.core | Imports of com.fasterxml.jackson classes in Groovy, Java delegates or custom listeners will fail to compile or resolve | Search all delegates, listeners and scripts for com.fasterxml.jackson imports and update each one |
| fields() and fieldNames() replaced | Expressions or scripts that iterate object fields with these methods will fail or return unexpected results | List every call site in expressions and scripts, then replace each with the Jackson 3 equivalent and test the loop |
| put(String, JsonNode) replaced | Scripts that build or modify JSON objects with this method will not run, which can break variable assignments mid-process | Find each put call on JSON objects, update it, and check the resulting variable values in a test |
Which scripts and expressions call JsonNode methods
Start the inventory by listing every place a Flowable model or Java class can run code that touches JSON, because JSON handling rarely sits in one obvious file. In a Flowable model, that includes script tasks, execution and task listeners, expressions on gateways and sequence flows, and service task delegates. Variables stored as JSON deserve their own line, since a script may read a JSON value from a process variable without any visible Jackson import in the BPMN file. CMMN case expressions and DMN decision logic that calls scripts belong on the same list, so the inventory covers every engine you run, not only BPMN.
Search in three places. First, search the BPMN, CMMN and DMN files in your process repositories for script elements, expression attributes and listener definitions that mention JSON-related variables or helper objects. Second, search your delegate classes and Spring beans for imports of com.fasterxml.jackson, which is the package Jackson 2 uses and the one that changes in Jackson 3. Third, search the same code for calls to the JsonNode methods the Flowable 8.0.0 release notes name as replaced: fields(), fieldNames() and put(String, JsonNode). Record each hit with the model or class, the engine, and whether the call runs in a script, an expression or Java code, because the fix and the test for each differ.
Treat the search as a starting point, not a complete list. Scripts can be loaded from external files or built from configuration, and a helper bean may hide the call behind a method name. Ask your team to confirm, for each hit and each variable it reads, whether the value is a Jackson object at runtime or a plain map or string, since only the first is affected by the method changes. Keep the inventory in version control next to the models so the test plan in the next section can point to each item.
Staying on Jackson 2 or moving to Jackson 3 now
This path fits teams whose process scripts, expressions and delegates call Jackson 2 APIs directly, or who cannot change those assets during the Flowable 8 upgrade window. Setting flowable.variable-json-mapper=jackson2 in Spring Boot keeps the variable JSON mapping on Jackson 2, and the Flowable 8.0.0 release notes recommend this as a starting point if you are unsure. It separates the engine upgrade from the library change, so a failure can be traced to one cause. It does not remove the Jackson 2 dependency from your application, and it leaves the migration debt in place for a later release.
- Engine and framework move first: Spring Framework 7, Spring Boot 4 and Flowable 8 still change, so the compatibility setting reduces the number of simultaneous changes rather than eliminating them.
- Dependency tree still carries Jackson 2: Confirm with
mvn dependency:treeor your Gradle equivalent which Jackson artifacts your application and libraries pull in. - Custom mappers stay on Jackson 2: Any
ObjectMapperbean you define keeps its current package and behavior. - Deferred work accumulates: Plan a dated ticket for the Jackson 3 move so the compatibility layer does not become permanent.
Before you choose this path, check the setting and its behavior against the Flowable 8.0.0 release notes and your own dependency tree, then test JSON variables end to end.
This path fits teams that already have a small, well-tested set of scripts and delegates, or that want a single upgrade with no long-term compatibility dependency. Jackson 3 is the default JSON library in Flowable 8, so this path matches the engine's intended configuration. The work is mostly mechanical in packages and method names, but JsonNode calls inside Groovy or JUEL expressions and delegate code fail at runtime if they are missed, so the scope of the search matters more than the size of the change.
- Package rename: Imports move from
com.fasterxml.jackson.databindandcom.fasterxml.jackson.coretotools.jackson.databindandtools.jackson.core. - Changed JsonNode methods: Calls to
fields(),fieldNames()andput(String, JsonNode)are replaced in Jackson 3, so every call site needs review. - Scripts are included in the search: Process scripts and expressions stored in BPMN and CMMN resources are not caught by the compiler, so search them as text.
- Mixed-library risk: Remove or align any Jackson 2 usage in shared libraries to avoid two mappers handling the same variable.
- Compatibility setting unused: Once migrated, you no longer need
jackson2for these assets, though you should verify this in your own configuration.
Before you commit, run process tests that read and write JSON variables, and confirm the library versions in your dependency tree match the Flowable 8.0.0 release notes.
How to sequence the Jackson 3 migration in a Flowable 8 upgrade
This sequence keeps JSON variable handling working at every point of the upgrade, so scripts and expressions move to Jackson 3 one model at a time with a known good state to return to.
Inventory every JSON touchpoint
Your developers list each place the application reads or writes JSON: script tasks, expressions, listeners, delegates, JSON variables stored in process and case variables, REST payloads that carry JSON, and any custom variable type or mapper. Record the file, model and the JsonNode or Jackson calls used. The step is done when every model that touches JSON appears on one list with an owner. Anything missing from this list will surface later as a runtime failure, so treat gaps as defects in the inventory rather than as later work.
Establish a baseline test run on Flowable 7.x
Before changing any dependency, run the full existing test suite against the current Flowable 7.x application and capture the results, including the JSON-related process tests. Store the outputs so you can compare them later. This baseline shows which failures already existed. If the suite cannot run on 7.x, record that fact now, because it changes how you verify the upgrade. Test suites still on JUnit 3 or 4 need a separate plan, covered in the sibling topic on moving process tests to JUnit 5.
Back up the database and deployed artifacts
Take a database backup that your DBA can restore, and keep the currently deployed application artifact and the exact set of deployed process, case and decision definitions in version control or an artifact store. Confirm you can restore both together. Include a note of the Flowable version and schema version. This is the rollback point for the whole sequence. Do not start the engine upgrade until a restore has been tested on a non-production copy, or until your team has documented why a test restore is not possible.
Upgrade to Flowable 8 with the jackson2 mapper
Move the engine and application to Flowable 8 while keeping Jackson 2 for variables by setting the Spring Boot property flowable.variable-json-mapper to jackson2. The Flowable 8.0.0 release notes recommend this as the starting point when unsure. Keep Spring Framework and Spring Boot changes in this same deployment only if your team has already planned them, since the release notes state there is no backward compatibility with Spring Boot 3. The step is done when the application starts, the schema upgrade completes, and the baseline tests run with the same results as Step 2, apart from failures you have explained.
Verify every JSON variable flow
Run each process and case flow that reads or writes JSON variables through the upgraded engine, using both the baseline test data and representative production-like payloads. Check variable reads, writes, serialization of stored values and any REST responses that return JSON. Compare the stored variable content with the pre-upgrade values for the same instances. The step closes when every flow in the Step 1 inventory has a recorded pass. If variable reads fail at this point, stop and restore the previous application artifact and database backup from Step 3 before any further change.
Migrate scripts and delegates one model at a time
Switch each model to Jackson 3 in its own change: update imports from com.fasterxml.jackson.databind and com.fasterxml.jackson.core to tools.jackson.databind and tools.jackson.core, then replace calls to methods such as fields(), fieldNames() and put(String, JsonNode) with their Jackson 3 equivalents. Confirm the exact replacement APIs in the Jackson 3 documentation and the Flowable 8.0.0 release notes. Test each model in isolation, then promote it. Keep the model's previous version available so that a single model can be rolled back without undoing the others. Each model is complete when its tests pass and its verified variable flow from Step 5 still holds.
Retire the Jackson 2 mapper after full verification
Once every model in the inventory runs on Jackson 3 and the full test suite and variable flow checks pass, change flowable.variable-json-mapper away from jackson2 in a separate deployment, and repeat the verification from Step 5. Confirm with your team that no remaining code depends on Jackson 2 classes before removing that dependency from the build. The step is done when the application runs on the default JSON library with no Jackson 2 imports left in process code, and the rollback artifact and backup remain on file for the period your change policy requires.
What to prepare before changing any JSON code
Most Jackson 3 breakage in Flowable 8 shows up in places the engine does not index: scripts, expressions, delegates and API consumers. The six items below establish what touches JSON, how to roll back, and who approves each change before anyone edits code.
Inventory JSON touchpoints
List every BPMN, CMMN and DMN model, script task, expression, listener and Java delegate that reads or writes a JSON variable or calls a JsonNode method. Search the code base for com.fasterxml.jackson imports and for scripts that call fields(), fieldNames() or put(String, JsonNode). Record the file, the owning process and whether the call runs at deployment, at runtime or in a test, so nothing is missed on the first pass.
Back up database and definitions
Take a verified database backup and export the deployed process, case and decision definitions with their deployment IDs before any upgrade step. Confirm you can restore both together, because running instances hold variables serialized under the JSON library in use. Ask your DBA to confirm restore timing, since a rollback without matching definitions can leave instances unable to resume.
Production-like test environment
Build a test environment with a copy or a masked extract of production data, including active instances with JSON variables of the shapes your models actually produce. Synthetic payloads often miss nested objects, nulls and arrays that break after a library change. Confirm with your data owners that masking preserves field structure, so JSON paths still resolve during tests.
Map REST consumers of JSON variables
Identify each client that calls the Flowable REST API and reads or writes variables holding JSON objects. Ask each consumer team to capture sample requests and responses from today's environment, then compare them after the upgrade. Any change in serialized output, field order or null handling will surface here first, so agree on who signs off before cutover.
Check dependency versions
Review the dependency tree for every Jackson artifact, including jackson-databind, jackson-core and any module pulled in by Spring. Mixing com.fasterxml and tools.jackson artifacts on one classpath can produce ambiguous bean wiring or duplicate classes. Confirm which Spring Boot and Spring Framework versions your Flowable 8 build resolves, and pin the compatibility setting explicitly in configuration.
Named owners for expression changes
Assign one engineer and one business owner for each process area that will change, and require their written sign-off before a rewritten expression or script reaches production. The reviewer should confirm the business result, not only that the code compiles. Record who approved each change so the trail stays available for later audits.
A test plan for models that touch JSON
Test every model that reads or writes JSON at four layers before you switch the default: delegate and script logic, full process runs, REST payloads and gateway expressions. Start with a baseline run on the current Flowable 7 build so that failures after the upgrade point to the change rather than to a gap that was already there. The first layer is unit tests for delegates, listeners and script tasks that call JsonNode methods. Where both mappers are on the classpath during the transition, run the same assertions against the jackson2 mode and the Jackson 3 default, so that any difference in how fields(), fieldNames() or put(String, JsonNode) behaves shows up as a named test failure.
The second layer is process tests that start instances with JSON variables and assert the values after each user task and service task, not only at the end of the instance. Checking after each step shows which node changed a value and makes a regression easy to trace. Process tests written on JUnit 3 or 4 must move to JUnit 5 first, because Flowable 8 removes support for those versions. The steps for that move are covered in the sibling topic on moving Flowable process tests from JUnit 4 to JUnit 5, so plan that work ahead of the mapper change and confirm the current test runner setup in your own build before you start.
The third layer covers REST contract checks for variable payloads. Record real request and response bodies from your current engine for each endpoint that returns or accepts JSON variables, then replay them against the upgraded build and diff the results. Also test gateway expressions that read JSON fields, using a fixed set of sample payloads that includes missing fields, null values and nested objects. Ask your engineering team to confirm which expressions evaluate JSON directly and which go through delegates, because that answer decides which tests need the most coverage.
What makes a Jackson 3 migration take longer
This table compares the factors that expand or shrink a Jackson 3 migration in Flowable 8, from script volume to test coverage. Read each row as a question to answer in your own codebase before you estimate the work. The main takeaway is that the count of JSON-touching scripts and the state of your tests matter more than the engine upgrade itself.
| Driver | Why it matters | What to check |
|---|---|---|
| Scripts and expressions calling JsonNode methods | Calls to fields(), fieldNames() and put(String, JsonNode) must be rewritten, and each call site needs a read-through because errors may only appear at runtime. | Search BPMN, CMMN and DMN files and Java delegates for JsonNode usage and list every call site by model. |
| Delegates in shared libraries | One shared delegate used by several applications turns a single code change into a coordinated release across all of them. | Identify which libraries are shared, which applications depend on each, and whether they can be upgraded together. |
| Custom variable types serialized as JSON | Custom types stored as JSON variables depend on Jackson annotations and mapper behavior, so changes in serialization can break existing stored values. | Confirm which mapper serializes each custom type and test reading values written by the current engine. |
| Test coverage of JSON paths | Thin coverage means JSON behavior changes may reach production undetected, which increases the time spent on manual verification. | Measure which process paths read or write JSON variables and whether tests assert on the resulting values. |
| REST clients that read JSON variables | External clients parsing variable payloads from the REST API may see output changes that the engine upgrade alone does not reveal. | Capture sample responses before and after the upgrade and compare field names, types and nesting with each client owner. |
| Spring Boot and JUnit versions already in place | Flowable 8 requires Spring Framework 7 and Spring Boot 4 with no Spring Boot 3 compatibility, and JUnit 3 and 4 support is removed, so older baselines add work before Jackson changes begin. | Record current Spring Boot, Java and JUnit versions and confirm whether the Jackson work can start before or only after those upgrades. |
Questions teams ask before a Jackson 3 migration
How much effort does a Jackson 3 migration take?
The effort depends mostly on how many scripts, expressions and delegates touch JSON variables and how many of them call JsonNode methods directly. A process model that only passes simple string or number variables needs little change. A model that builds or traverses JSON objects inside expressions needs each call site reviewed, because the package names change from com.fasterxml.jackson to tools.jackson and methods such as fields(), fieldNames() and put(String, JsonNode) are replaced. The Flowable 8.0.0 release notes describe these changes, so the first useful step is an inventory of every JSON-touching artifact. Ask any partner to base its quote on that inventory, not on a rough count of process files.
How long does the migration take, and what changes the duration?
No duration figure is supplied for this work, so confirm any estimate against your own inventory. The main duration drivers are the number of affected artifacts, whether scripts are compiled Java delegates or inline Groovy or JUEL expressions, how well the existing test suite covers JSON paths, and whether the team also moves to Spring Boot 4 and Spring Framework 7 at the same time. Running the Jackson 2 compatibility mode first separates the engine upgrade from the JSON library change, which usually shortens the critical path. Ask for a schedule that shows the inventory, test coverage work and cutover as separate phases.
What does the migration need from our engineers and testers?
Engineers need to know which process scripts and delegates read or write JSON variables, and they need to review each JsonNode call against the Jackson 3 API. Testers need process-level tests that exercise every model that stores JSON, including the edge cases where a field is missing, null or nested. Expect the work to span Java developers who own delegates, people who own the process models, and whoever owns the deployment pipeline for process definitions. Confirm early which of these roles sit inside your team and which you want a partner to cover.
Can our own team do the Jackson 3 migration in-house?
Yes, if the team has Java developers familiar with Flowable delegates, access to the process models, and a test suite that runs against a real database configuration. The work is well bounded: an inventory, a set of code and expression changes, and tests that prove the outcome. Teams usually find the risk sits in artifacts nobody remembers writing, such as expressions stored in BPMN files or scripts loaded from a database. A partner is most useful for that discovery step, for writing the test plan, or for working alongside your team during the cutover. Decide which part you own before you ask for a quote.
Can we stay on Jackson 2 after upgrading to Flowable 8?
Yes. Flowable 8 uses Jackson 3 as the default JSON library but still supports Jackson 2 variables. With Spring Boot, setting flowable.variable-json-mapper=jackson2 keeps Jackson 2, and the Flowable 8.0.0 release notes recommend this as a starting point if you are unsure. Staying on that mode lets you complete the engine and Spring Boot 4 upgrade first, then plan the switch to Jackson 3 as a separate change. Confirm with the project how long that compatibility mode is expected to remain available for your version before you set a long-term plan around it.
How do we find every script and expression that depends on Jackson?
Start with a search across your Java source for com.fasterxml.jackson imports, then search your BPMN, CMMN and DMN resources for expressions that call JSON methods on variables. Include scripts stored in the database or loaded from external configuration, because a repository search will miss them. Check any custom variable type handlers, REST clients that serialize variables, and test fixtures that build JSON. Record each hit with the model, the activity and the owning team, then mark which ones the compatibility mode covers. That record becomes the baseline for both the code changes and the test plan.
How DeployOpen scopes and delivers a Flowable Jackson 3 migration
DeployOpen starts by inventorying where your Flowable 8 application touches JSON, then agrees a written scope before any code changes. We work inside your own repositories and environments, keeping the Jackson 2 compatibility mode as a controlled first step.
How we scope
- Inventory every script task, expression, listener and delegate that reads or writes JSON variables.
- Confirm whether the application will stay on the jackson2 variable mapper first or move straight to Jackson 3.
- Agree in writing which models, test suites and integrations are in scope, with deliverables and timeline before work starts.
How we build
- Replace package imports from com.fasterxml.jackson to tools.jackson in your code and update calls to changed JsonNode methods.
- Rework scripts and expressions that call fields(), fieldNames() or put(String, JsonNode), and test each change against real process variables.
- Keep changes in version control so each migration step can be reviewed, reverted and repeated in staging.
How we hand over
- Deliver a test plan covering each process and case model that touches JSON, with the expected variable shapes for each path.
- Document the variable mapper setting, the remaining Jackson 2 dependencies and the decision record behind each change.
- Run a knowledge transfer session with your engineers so they can maintain the mapping and extend the tests.
How we support
- Ask your team which Flowable 8 minor releases and Jackson updates they plan to adopt, so the scope covers the upgrade path.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with your own change management process how migrated models will be promoted to production.
