Why teams need Flowable process diagrams and when to generate them
Generating Flowable process diagrams means producing an image of a deployed process that marks where a particular instance is waiting, so people can see a request's position without reading engine data. It is worth building when operations staff, case workers or customers repeatedly ask where a request is and the answer currently comes from an engineer querying tables or from a status field someone must keep updated. A diagram can be supplied with the deployment as a fixed image, or generated from the BPMN diagram interchange (DI) information stored in the process model, with active activities highlighted for the instance being viewed. Choosing between those two routes is the first decision, and it shapes everything after it.
The supplied image is the simpler route. It needs no rendering code and no extra endpoint, but it shows the model only, never a running instance, and it can drift from the deployed definition whenever the model changes. Generated diagrams follow the definition that is actually deployed and mark the activities a given instance has reached, which is what most status questions require. They depend on the DI data being present in the BPMN file and on an API route that returns the image to your front end, so confirm both against your Flowable version before design starts. Flowable 8.0.0 moved the stack to Spring Framework 7 and Spring Boot 4, and the Flowable 8.0.0 release notes list the baseline changes your rendering and REST layers must match.
Building this is worth less when the audience only needs a text status, when instance volumes are low enough for staff to check the engine directly, or when the model changes so often that every change means regenerating and retesting the picture. The cost sits in three places: engineering time to build the endpoint and the front-end component, testing that highlights are correct across gateways and subprocesses, and upkeep when models change. Ask any partner which diagram sources they will support, whether CMMN case diagrams are in scope, where image rendering is hosted, and who maintains it after go-live. Confirm access rules too, because a picture of a customer's process can reveal more than a status field does. The Flowable getting started guide covers the embedding and REST options that determine where this endpoint runs.
Choosing between supplied diagrams, generated diagrams and REST images
This table compares three ways to show a Flowable process to users: diagram files shipped with the deployment, diagrams generated at runtime from BPMN diagram interchange data, and images served through the REST API. Read each row as a question to answer for your application, then check the chosen approach against the Flowable docs for your version before you commit to it.
| Approach | When it fits | What it depends on | What it does not cover |
|---|---|---|---|
| Diagram resources shipped with the deployment | Static process documentation, reviewers who want the exact file the modeler saved, and simple front ends that load a file from the deployment | A diagram file packaged with the process definition and a consistent naming convention for each version | Live state, so it cannot highlight the activities where a given instance is waiting |
| Diagrams generated from BPMN DI at runtime | Showing the current process model for a specific definition, with the engine's own layout data driving the drawing | BPMN diagram interchange (DI) elements in the deployed XML and a rendering step your application or a library controls | Active activity highlighting unless you add that logic yourself, and layout quality that depends on the source model |
| Images served through the REST API | Front ends that need an image without parsing BPMN, and clients that already call the REST API for tasks and instances | A REST endpoint for process definition images and an authenticated client, with the exact path confirmed in the docs for your version | Caller-specific highlighting in every case, so confirm what the response contains before designing the user experience |
| Highlighting active activities | Showing a user where an instance has stopped, such as a wait state or a user task | Access to the instance's active activity identifiers and a way to mark them on the chosen diagram | Business meaning, such as why a process is waiting, which still needs a task or variable view |
| Access control for diagrams | Limiting who can see process models or instance progress | Your application's authorization checks on the endpoint or page that serves the diagram | Authorization decisions, which the engine leaves to your application |
| Version handling | Showing the diagram that matches the definition a running instance uses | Matching the process definition version and the image or file to the instance | Automatic matching across versions, so test instances started before and after a redeploy |
| Testing and verification | Confirming that the right diagram and highlights appear for each definition | Fixtures with known deployments and a test plan for at least one instance per version | Visual quality checks, which usually need a manual review step |
Setting up diagram generation in a Flowable application
This sequence takes a Flowable application from an engine and starter choice to a verified diagram endpoint that highlights where a running process instance currently sits. Each step ends with a check your team or DeployOpen can run before moving on.
Confirm the engine and starter in use
Record how Flowable reaches your application: a Spring Boot starter for the BPMN engine, an embedded JAR in a Java SE or servlet container, or the Flowable REST application over HTTP. The Flowable getting started guide lists these embedding options, and the Spring Boot docs describe starters for the process engine and for REST. Diagram generation depends on which engine and API layer exposes the endpoint, so write this down before changing code. Confirm the exact Flowable version you run, since the 8.0.0 line moved to Spring Boot 4 and Spring Framework 7 and dropped Spring Boot 3 support. Done when the team agrees on the starter or JAR set and the version, and a build of the application starts with the engine initialized.
Keep BPMN DI intact in deployments
Diagram generation reads the diagram interchange (BPMN DI) information stored with each process definition, so the deployed BPMN XML must still contain the shape and edge coordinates. Check that your modeling tool exports DI, that build or packaging steps do not strip or rewrite the diagram section, and that any XML transformation keeps the bpmndi elements. Deploy a sample definition, then fetch it back through the engine and confirm the diagram elements for each activity are present. Done when a deployed definition returns its DI data unchanged and a process with a missing diagram is flagged in your pipeline rather than failing silently at runtime.
Decide where image rendering runs
Choose whether the diagram image is produced inside the application process, by a separate rendering service, or in the front end from the BPMN and state data. This decision affects memory use, font and library dependencies, and who can reach the rendering code. Record the choice with the platform team, since it determines the container image, network paths and scaling of the endpoint. Confirm the rendering approach against the Flowable version and the libraries your team is permitted to use under your license and security policy. Done when the rendering location, its owner and its resource limits are written in the design notes.
Expose the diagram endpoint behind authentication
Register the diagram generation route so it returns an image for a process definition or a running process instance, and place it behind the same authentication used for the rest of the Flowable API. Do not leave the image endpoint public, because it reveals process structure and, when instance-level, the position of individual cases. Use your identity provider or the authentication configured for the REST application, and restrict access to users who are allowed to see the process. Confirm that an unauthenticated request is rejected and that an authorized user receives an image. Done when both checks pass in a test environment and the access rule is documented.
Verify the active activity highlight
Start a process instance and drive it to a known wait state, such as a user task waiting for a candidate group, then request its diagram. Confirm the image highlights the active activity at that point and no other. Repeat with a second instance at a different point, for example after a gateway, to show the highlight moves with execution. Use a fixed test deployment so the expected position is known before the request. Done when each test instance's highlighted activity matches the activity you expected, and the test is kept in the suite so a later change to the model or rendering code is caught.
Check completed and multi-instance states
Extend the verification to cases that are harder to read: a completed activity, a parallel branch with more than one active token, and a subprocess that is currently running. Confirm the rendering shows each state the way your users need, and that the endpoint still responds correctly when an instance has finished and its runtime data is gone, which may require history data instead of runtime data. Compare the results against the history API for the same instance. Done when every state your users rely on produces an expected image and the team knows which data source the endpoint uses in each case.
Confirm the endpoint in your environment
Repeat the checks in the environment you operate, using a copy of production-like configuration, the same database type and the same authentication path. Database configuration and the identity service can change behavior, so the test should run against the real stack, not only the developer laptop. Confirm the image endpoint is reachable from the users' network path, that load and caching behave as planned, and that failures produce a clear error. Done when the checks pass in that environment and the results, configuration and owners are recorded for handover to operations.
How BPMN DI drives highlighted activities
Highlighting active activities depends on two things that must agree: the BPMN diagram interchange (DI) data stored with the process definition, and the definition the engine actually runs. The DI section holds layout only. It records where each shape and edge sits on the canvas, using elements such as BPMNShape and BPMNEdge that reference the element IDs in the process model. It does not define behavior. The engine executes the process from the BPMN model, then the diagram layer uses the same element IDs to place a highlight on the activities where each running instance currently waits or works.
The engine knows which activities are active by reading its runtime state for each process instance: the executions and the activity IDs they occupy, plus any open jobs and timers. A highlight is only meaningful when those IDs match shapes in the diagram. If someone edits a task ID in the model without regenerating or redeploying the matching diagram, the highlight silently lands on nothing or on the wrong shape. Renaming an element, removing a gateway, or adding a subprocess has the same effect. Treat the diagram and the deployed definition as one artifact, and check during build that every executable element in the BPMN has a matching shape in the DI.
A diagram must track the process definition version, not just the process name. Running instances stay on the version they started with, so an instance started last month may need the diagram from that version, while new instances use the latest one. Decide how your pipeline stores and serves each diagram against its definition key and version, and test an old instance against its original diagram before you retire it. Confirm in the Flowable docs for the version you run how diagram generation and image endpoints are exposed, since the supported approach and the REST resources for process images differ between major releases.
Securing diagram endpoints and what they reveal
A diagram with highlighted activities shows how a process is built and where a specific case currently sits, so the image endpoint needs the same care as the data behind it. The cards below cover the caller, the instance, the model file, and the request trail. Each one is a decision to make or a check to run before the endpoint leaves a test environment.
Authenticate every REST caller
Decide how callers of the diagram endpoint prove who they are before any image is returned. The Flowable REST application and any Spring Boot wrapper around it need an authentication layer that you configure and test, and the diagram route must sit behind the same gate as the rest of the API, not beside it. Ask the team to list every route that returns a PNG or SVG for a process instance, then confirm each one rejects anonymous requests. Flowable's security guidance describes the areas to review, and the engine's behavior should be verified in your own configuration.
Check the user may view the instance
Being authenticated does not mean a user may see the state of every process instance. A highlighted diagram reveals which step a specific customer, claim or application has reached, so the application should check that the caller is allowed to view that instance before it calls the diagram generator. Do not assume the engine applies this check for you. Write a test that requests the diagram for an instance owned by another user and confirm the response is refused, and include candidate-group and assignee cases in the same test.
Limit what the diagram exposes
The unhighlighted process model is often less sensitive than the live state, but it still shows routing rules, approval levels and the names of internal services. Decide which audiences may see the full model and which may only see a simplified view or the highlighted path. Keep images off public caches and shared links, and set a short lifetime on any URL that embeds an instance identifier. Review the decision in writing with the process owner, since they know which internal steps should stay private.
Review scripts and XML in definitions
Process definitions can contain script tasks, expressions and extension elements. Anyone who can deploy or edit a definition can change what the engine runs and what the diagram displays. Restrict deployment rights, review BPMN XML in version control before it reaches an environment, and disable or sandbox scripting where your policy requires it. Flowable's security documentation covers scripting and XML risks, and this review should be part of the same pipeline that deploys diagrams.
Keep the model and deployment under control
The diagram is generated from the deployed BPMN and its diagram interchange data, so the source of that file defines what users see. Keep definitions in version control, tie each deployed version to a reviewed commit, and confirm that the diagram endpoint serves the version that matches the instance. A mismatch can show users steps that the running process no longer uses, which makes support questions harder to answer and can mislead reviewers.
Log and retain image requests
Record who requested a diagram, for which instance, when, and whether the request was allowed or refused. These entries help investigate access to sensitive cases and show that the access check runs. Decide where the logs go, who reads them, and how long they are kept, and align the retention with your data protection rules. Confirm that the logs do not store the diagram content itself, since that content can carry the same data as the instance.
Questions teams ask before building Flowable diagrams
What makes a Flowable diagram feature cost more or less to build?
The rendering approach, the number of process definitions, the authorization model and the front-end integration drive most of the effort. Rendering diagrams from the BPMN diagram interchange data already in a deployment is a narrower job than producing a separate diagram per definition for every user. Each additional definition adds mapping and testing work, and each permission rule that decides who sees which instance adds design and verification time. A written quote should break these components out so you can see which ones you can reduce.
How long does a basic Flowable diagram build take?
Duration depends on scope, and no fixed figure applies to every environment. A basic build covers one or a few process definitions, a rendering approach, and a single front-end integration point. Larger builds add more definitions, custom highlighting for active activities, and access rules tied to your identity system. Ask any partner, including DeployOpen, for a timeline in the written scope, with the number of definitions, the rendering method and the test environments listed as assumptions.
What does our team need to provide before the work starts?
Plan to provide the BPMN process models that will be deployed, sample process instances with realistic variables, and a test environment connected to your identity provider or a representative test directory. You will also need to name the people who decide which users may see which instances. Engineers should expose the REST endpoints that the front end will call and confirm the Flowable version in use. Missing inputs usually show up as rework late in the build, so confirm each item in the scope document.
Can an internal developer build Flowable diagrams alone?
A developer who already knows Java, the Flowable engine and the REST API can build a basic version alone, especially when the diagram output needs only one definition. Teams without that background, or those needing authorization checks, front-end work and tests across several definitions, usually spread the work across more roles. Decide on the split of work before starting: who owns the BPMN models, who owns the rendering code, and who signs off on access rules. A partner can take on any part of that split under a fixed scope.
Which parts of the diagram feature need security review?
The sensitive parts are the REST endpoints that return images or process state, and the checks that confirm a caller may see a given process instance. Flowable leaves authorization decisions to your application, so the diagram endpoint must enforce them itself. Review the authentication setup for the REST API, the handling of default accounts, and any scripting or XML inputs in the models that feed the diagram. Your security team should test these paths before go-live.
How does the diagram feature affect ongoing operations?
Once live, the diagram feature needs the same care as other parts of the application: it must keep working through engine upgrades, new deployments of process definitions, and changes to the front end. Plan for regression tests on rendered output after each upgrade, and record which Flowable version and definition version each diagram was generated from. Ask any partner whether post-launch support is included or offered as a separate retainer.
Does Flowable's commercial product include diagram features we can use instead?
The open source engines are Apache 2.0 licensed, and Flowable describes its commercial products as built on the same engines with added low-code modeling and visual debugging. Whether a commercial product fits your needs is a licensing and scope question, not a technical one. Ask Flowable directly what each product includes, what it costs, and which features your diagram requirements depend on before choosing between building and buying.
What should we ask for in a written quote?
Ask for the scope in terms of process definitions, rendering method, supported Flowable version, front-end integration points and test environments. Request the assumptions behind the estimate, a list of deliverables, the acceptance criteria for rendered diagrams, and a statement of what is one-time and what recurs, such as support or upgrades. Ask how changes to scope are priced and who owns the code and documentation at the end.
Running and maintaining diagrams after go-live
The main ongoing risk with generated diagrams is drift between the deployed process definition and the diagram the user sees. Every time a team redeploys a BPMN model, the highlighting logic depends on activity IDs in the new XML and on the diagram data that comes with it. Treat the process model as the source of truth and make the diagram rendering a step in the same change process: when a modeler changes a task ID, renames a subprocess or moves a boundary event, someone should confirm that the highlighted image still points to the right activities. Keep a small set of reference instances, one for each major path through the model, and check their rendered images after every deployment. Ask your team to document which deployment pipeline owns this check, because diagrams that nobody owns tend to stop matching the model within a few releases.
Flowable version changes can alter rendering even when your model does not change. Rendering depends on the engine's diagram generation code, its fonts and layout handling, and the libraries it uses to produce images, so a minor or major upgrade can shift element positions, label placement or highlight colors. Before you upgrade, run a diagram regression check against a fixed set of definitions and instances, compare the output with images captured on the current version, and review the differences with a process owner. The Flowable 8.0.0 release notes list changes to the Spring and Jackson baseline that also affect the REST layer serving images, so include the endpoint in that test, not only the Java API. Confirm with your Flowable contact which rendering changes each release brings, because the release notes do not list them in detail.
Operational monitoring closes the loop. If diagrams are requested on every task view, image generation becomes a load source that grows with the number of concurrent users, so track response times and memory use of the REST endpoint that serves images and set limits or caching where the load justifies it. The Spring Boot starter exposes an actuator endpoint at /actuator/flowable for monitoring running processes, which helps you compare active instance counts with the traffic you see on the diagram endpoint. Check the endpoint's exposure settings as part of this work, since the actuator should not be reachable from user networks. Record the Flowable version, the diagram test results and the endpoint metrics together for each release, so the next upgrade starts from evidence rather than memory.
How DeployOpen scopes and delivers Flowable diagram work
DeployOpen approaches diagram work as part of the wider Flowable application, not as a standalone picture feature. We agree the scope in writing first, then build and document the diagram rendering inside your own infrastructure, so the people who run the engines can keep it working after handover.
How we scope
- Engagements are fixed-scope, with the diagram sources, rendering method and access rules agreed in writing before work starts.
- The written scope names which process definitions get diagrams, whether they come from deployed files or BPMN DI, and which users can view them.
- We confirm your Flowable version, deployment model and REST API access up front, because these decide how images are served.
How we build
- We build the highlighting logic that marks active activities for each running instance, tested against your own process models.
- We set up the REST endpoint that returns diagram images, with authentication and authorization checks defined by your application.
- We write automated tests that cover processes with parallel branches, subprocesses and wait states, not only the simple happy path.
How we hand over
- You receive the source code, configuration, test suite and a runbook describing how diagrams are generated and cached.
- The documentation explains which Flowable version the rendering was built against, so upgrades can be planned with that in view.
- Knowledge transfer sessions walk your engineers through the code and the decisions behind it before the engagement closes.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers once the diagram work is live.
- A retainer can cover re-testing after Flowable version changes, so diagram output keeps matching the running engine.
- Confirm response expectations, change handling and upgrade responsibilities in the written agreement before work starts.
