When teams call Flowable decisions over REST
Choose a decision service when several applications need the same business rules and you do not want each one to carry its own copy of the DMN engine. Flowable's engines are Java libraries, and the Getting started guide describes two ways to use them: embed the engine as a JAR in a Java SE application, servlet container, Spring application or Java EE server, or call it over HTTP through the Flowable REST application. The REST option gives you one running engine, one set of deployed decision tables and one place to change rules. The engines are licensed under Apache 2.0, so the decision to run a shared service is a question of architecture and operations, not of license terms.
Three situations usually favor a decision service over embedding. The first is polyglot callers, where some consumers are not on the JVM and can only reach rules through HTTP. The second is central rule ownership, where a risk, pricing or eligibility team must approve changes that several products depend on, and those changes should not wait for each application's release train. The third is a separate release cadence, where the rules change weekly while the calling applications change quarterly. If none of these apply to your estate, embedding the engine in the calling application is simpler to deploy and test. Before you commit, confirm which Flowable REST application version your team will run, since the REST application ships with the engine release you choose and the release notes for each version describe platform requirements.
Write down the callers, the rule owners and the expected change frequency before you pick a topology. Ask your architecture team to list every application that would call a shared decision, the identity each one uses and the latency and availability the callers expect from it. Then confirm with the Flowable documentation and your own platform team how the REST application is hosted and secured in your environment, because a shared decision service becomes a dependency for every caller. That dependency is the main trade-off: a central service concentrates rule governance and reduces duplicate logic, but an outage or an unsecured endpoint affects every application that calls it.
Embedded engine or REST decision service
This table compares three ways to run Flowable DMN decisions: embedding the engine as a JAR, running the Flowable REST application, and using Spring Boot starters. Read each row against your own team structure, language mix and security review process to see which model fits. The main takeaway is that embedding gives the tightest coupling and fewest network hops, while a REST service gives other applications a language-neutral entry point at the cost of running and securing another service.
| Option | When it fits | Who owns deployment | Trade-offs in coupling, language and security |
|---|---|---|---|
| Embedded JAR in Java SE, servlet or Java EE | The calling application is already Java and decisions run in the same process as the business logic | The application team builds, releases and patches the engine with its own code | Tightest coupling: a rule change ships with the host application, and any caller must be JVM-based |
| Embedded in Spring applications | The organization standardizes on Spring and wants the engine managed as application beans | The application team, with platform engineers owning the database connection and runtime | Configuration lives in the application; the Flowable 8.0.0 release moved to Spring Boot 4, so Spring Boot 3 applications need a planned upgrade |
| Flowable REST application | Non-Java applications or several separate systems need to call the same decision service over HTTP | A platform or operations team deploys and runs the REST application as a shared service | Language-neutral access, but every caller depends on the service's availability and API contract |
| Spring Boot starter for the REST engine | Teams want the REST API hosted inside their own Spring Boot service with standard starter configuration | The team that owns the Spring Boot service, which also owns its patching and endpoints | Ties REST exposure to one application's release cycle; confirm the starter's endpoints and authentication before exposing them |
| Spring Boot starter for the DMN engine | A Java service needs decision evaluation without a separate HTTP layer | The application team, including database setup and engine version pinning | Lowest network exposure, but other services cannot call decisions without a new integration point |
| Authentication and access control | Any option that accepts requests from other applications | The team that deploys the endpoint, not the decision author | Default accounts and open endpoints are the main risk; confirm which authentication the chosen deployment enforces before go-live |
| Database and history storage | All options share the same engine database and decision history settings | The team that runs the database, with backup and retention set by the owner of the data | Shared database access can couple callers to schema changes; confirm supported database types against the configuration docs |
| Monitoring and operations | Production decision services need visibility into failures and latency | The operations team for the chosen runtime | The Spring Boot actuator endpoint at /actuator/flowable covers running processes, so confirm what it exposes for decisions in your version |
How to set up the Flowable DMN REST service
This sequence takes you from a supported database to a running Flowable REST service that deploys a decision table and returns its result, with a check at each stage so you know the decision is reachable before any application depends on it.
Choose and prepare a supported database
Pick one of the databases the Flowable configuration docs list as supported (H2, MySQL, Oracle, PostgreSQL, DB2 or Microsoft SQL Server) and create an empty schema with a dedicated account for the engine. Confirm the database version against the configuration docs before you start, because the docs note that MySQL versions below 5.6.4 lack millisecond precision, which affects timestamps in the engine. Done means the engine account can connect and create tables in the target schema, and you have recorded the connection settings for the next step.
Deploy the REST application or starter
Choose how the REST service runs in your environment: the Flowable REST application deployed as a web application, or a Spring Boot starter for the REST and DMN engines if your team already builds Spring services. Your platform team or DeployOpen configures the datasource, the context path and the bind address, and confirms the Flowable version you pin matches the Java and Spring baseline in the release notes for that version. Done means the service starts without errors in the logs and responds on its health or management endpoint.
Confirm the engine schema and DMN engine are active
Check that the engine created its tables on first start and that the DMN engine is enabled in the configuration you deployed. If you use the Spring Boot starters, the actuator endpoint at /actuator/flowable gives a view of the running engine for this check. Done means the schema exists in the database, the service logs show the DMN engine initialized, and no startup errors remain.
Deploy a decision table file
Deploy a test DMN file through the deployment endpoint of the REST API. Use a small decision table with a clear key and two or three rules so that results are easy to verify by hand. Take the exact endpoint path and multipart request format from the Flowable REST API reference for your chosen version, not from memory or older examples. Done means the deployment response returns a deployment ID and the decision definition appears in the list of decision definitions.
Confirm the decision key and version
Query the decision definitions endpoint and check that your decision key appears with the version number the engine assigned. Record both values, because the execute call in the next step references the key and the engine's version handling determines which definition runs. Done means the key matches the DMN file you deployed and the version is the one you expect, including after a second deployment of the same key if you test versioning now.
Execute the decision with test inputs
Call the execute endpoint for the decision key with a request body containing input variables for one or more of your test rules. Take the path and request body structure from the Flowable REST API reference for your version, since input variable naming and the shape of the body are version-specific. Done means the response contains output values that match what your decision table yields for those inputs when you work through the rules by hand.
Verify results across the rules and error cases
Run inputs that match each rule, a case that matches no rule, and a case with a missing or wrongly typed input. Compare the responses with your expected outputs and note how the service reports a missing input or no match, because calling applications must handle those responses. Done means each test input gives the expected output or a documented error, and the results are saved as your baseline before you secure access or connect other applications.
Passing input variables and reading decision results
The core job of this section is to get the request right before the decision runs: each key in the request body must match an input expression in the decision table, and each value must arrive in the type that expression expects. In the Flowable DMN REST API, the execute call takes the decision key in the path and a JSON body that carries input values, and the engine evaluates the table against those values. Flowable does not guess types for you. A value sent as the string "5" against an input column that compares numbers, or a date sent in a format the table does not parse, can produce a non-match that looks like a business outcome. Before go-live, have the integration team send one request per input column with a known value and confirm the output, and record the exact JSON shape in the caller's contract. Check the REST endpoint details in the version you run, because request and response fields are part of the API surface you will depend on. The Flowable open source page is the starting point for confirming which engines and APIs ship with your release.
The hit policy decides the shape of what comes back, and your calling code has to handle that shape. A single-result policy such as FIRST or UNIQUE should return one object for a matching request, so the caller reads one value. A collecting policy such as COLLECT or RULE ORDER returns a list, and a caller written for a single value will fail or silently take the first item. Confirm the hit policy of every decision the service exposes and write the response parser to match, and do not rely on a result shape you have not tested against your own tables. Rule logic itself, including which hit policy fits which overlap pattern, belongs in the hit policy page of this group, and the way a process reads the output belongs in the business rule task page. This section stays on the wire format.
An empty result is a normal outcome, not an error the engine always raises. When no rule matches, the caller must decide what that means for the business: a default decision, a refusal, or a referral to a person. Define that behavior in the caller's contract and test it with a request that matches no rule, because the response for no match can differ from the response for a match with empty output. Ask your Flowable partner or the engine documentation which response Flowable returns in your version for a no-match case on each hit policy, and write a test that asserts it. Also decide whether missing input keys are rejected or treated as null, since a missing key can either fall through to a default rule or match the wrong row. Make these choices explicit, because a null path that reaches an approval decision is a control gap auditors will question.
Securing decision endpoints for other applications
Once the DMN engine answers over REST, every calling application becomes a potential path into your rules and data. The cards below cover the controls that sit around the engine: how callers authenticate, how identities are resolved, how traffic is restricted, and how each execution is recorded. Authorization per decision is not built in, so the choices you make here decide who can run what.
Authenticate every caller at the REST layer
The REST application must sit behind an authentication mechanism before any decision endpoint is reachable. Confirm how the Flowable REST application you deploy handles credentials, and confirm whether default accounts exist in your release and are removed or rotated before go-live. Do not expose the engine directly to the internet. Test that an unauthenticated request to a decision execution endpoint fails in every environment, including staging, since test shortcuts often reach production.
Map callers to identities
The Flowable docs say identity management can be replaced by overriding IdmIdentityServiceImpl or by implementing the IdmIdentityService interface, with an LDAP implementation provided as a reference. Use this override to connect the engine to the directory your organization already runs, so that each calling application or service account resolves to a known identity. Confirm with your engineers which interface your Flowable version expects, because the override changes how users and groups are read.
Restrict network paths to decision services
Limit which networks and services can reach the decision endpoints. Place the engine on an internal network segment, allow only the calling applications through firewall rules or service mesh policy, and route external traffic through a gateway that enforces the same allow list. Document each permitted caller with its source address or service identity, and review that list whenever a new consumer is added.
Grant callers least privilege
Give each calling application only the access it needs. Because the engine does not decide per decision key whether a caller may run it, the check must live in your application or gateway. For example, an illustrative gateway rule might allow a credit pre-screening service to call one decision key and deny every other path. Write these rules down, test them with negative cases, and confirm with your vendor which permissions the REST API itself enforces.
Validate inputs before execution
Decision inputs arrive as variables in the request body, and malformed or oversized values can produce unexpected results or errors. Validate types, required fields, and value ranges at the gateway or calling service before the request reaches the engine. Reject unknown input keys where your rules do not expect them. Test boundary values against the decision table so that a bad payload cannot silently select a permissive rule.
Log who ran which decision
Record the caller identity, decision key, decision version, timestamp, and outcome for every execution request. Confirm which of these the REST layer logs by default and what the engine's DMN history stores, then fill any gap at the gateway. Keep these logs in a store your security team controls, set retention to match your policy, and alert on unusual volume or repeated failures from one caller.
Questions teams ask before exposing decisions over REST
How much effort does it take to set up a Flowable decision service?
Effort depends less on the REST call itself and more on what surrounds it: the decision tables, the input and output contract, the identity model and the deployment pipeline. Exposing one decision for one internal caller is a small task. Exposing many decisions to several applications, each with its own authorization rules, is a larger one. The Flowable REST application runs over HTTP alongside the engines, so the engineering is mostly configuration, testing and governance. Ask any partner to size the work from a written list of decisions, callers and security requirements, and to separate one-time setup from ongoing change requests.
Can our in-house team expose Flowable decisions over REST without a partner?
Yes, a team with Java and Spring experience can do this, provided it has someone who understands DMN and can test hit policies and rule overlaps. The harder parts are usually non-technical: agreeing who may call which decision, keeping decision versions aligned with callers, and recording who approved a rule change. Teams that already run Flowable engines and their own identity provider typically have most of the skills in-house. Teams without a Flowable runtime or without an identity contact should weigh a partner for the first release, then decide whether to keep the work internal.
What does the work need from our people?
Three groups matter most. DMN owners, usually business analysts or risk staff, must confirm rule logic, expected outputs and test cases. Identity contacts must supply how calling applications authenticate, such as service accounts or OAuth2 clients, and which roles map to which decisions. Infrastructure staff must provide the runtime, database connectivity, network paths from callers, and the deployment pipeline that publishes decision files. Agree these named contacts and their time commitments in writing before work starts, because delays in any group usually delay the release.
What drives the cost of a decision service?
Cost is driven by scope and integration count. The main components are discovery of the decisions and their input contracts, building the REST access and authorization layer, integrating with each calling application, testing, and handover. Costs rise with the number of decisions, the number of distinct callers, the complexity of identity integration, and any requirement for audit records of each call. Costs fall when inputs are already documented and callers share one authentication pattern. Ask for a quote that itemizes these components, marks which items are one-time, and lists any recurring support or retainer terms separately.
How long does it take with many decisions and callers?
Duration grows with the number of decisions, the number of callers and the number of approval cycles for rule changes. A single decision called by one application can often be released in a short cycle, while a catalog of decisions with several callers adds integration testing and sign-off per caller. Dependencies also matter: an identity provider change, a database connection request or a change board can take longer than the engineering. Ask for a timeline that is tied to a written list of decisions and callers, with milestones for business sign-off and environment access.
Which Flowable REST endpoints should we expose to other applications?
Expose only what callers need. Decision execution is the primary use case, but deployment and listing endpoints are administrative and should normally stay behind internal network controls and a separate role. Engineers should confirm the exact endpoints, paths and request formats against the Flowable documentation for the version they run, because endpoints differ between major releases. Create a short allow list of decision keys per caller, and test that a caller cannot reach decisions or deployment functions outside its list.
Should we build this ourselves or hire a partner?
Build in-house when your team already runs Flowable, owns identity integration and can keep rule testing under its own control over time. Consider a partner when the first release has tight deadlines, when no one on staff has run a Flowable runtime in production, or when compliance evidence for access and rule changes must be prepared quickly. A fixed-scope engagement works well for a defined set of decisions and callers, and a retainer suits ongoing changes. Whichever path you choose, keep ownership of the decision logic and the access policy within your organization.
What to confirm before you rely on the REST decision service
The REST decision service depends on details that change between Flowable releases and deployments, so none of them should be assumed. The cards below cover the version, the endpoint contract, the runtime baseline, the database, the throughput and the access model. Confirm each one against your own version and environment before other applications depend on the service.
Exact endpoints and payloads for your version
Confirm the decision execution and deployment endpoints, the request body that carries input variables, and the response shape for the exact Flowable release you run. Do not copy paths or JSON from an older example or blog post. Ask the vendor for the REST API reference matching your version and test each endpoint with a representative payload, including empty inputs, missing inputs and a decision key that does not exist, so you know how errors are reported to callers.
Spring Boot 3 compatibility change
Flowable 8.0.0 moves to Spring Framework 7 and Spring Boot 4 and does not stay backward compatible with Spring Boot 3. If your decision service runs on Spring Boot 3, plan the upgrade of the host application as a separate change, not as a side effect of the Flowable upgrade. Confirm with the vendor whether a supported path exists for your current Spring Boot line before you schedule the move.
Jackson 3 default JSON behavior
Flowable 8.0.0 uses Jackson 3 as the default JSON library and provides a Jackson 2 compatibility layer. Request and response serialization of dates, numbers and nulls can change in ways that break calling applications that parse results strictly. Confirm which library your deployment uses, whether the compatibility layer is enabled, and run contract tests from each client application against the new service before cutover.
Supported database for your deployment
Confirm that the database you plan to use appears in the Flowable configuration documentation for your release. The documented options include H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. For MySQL, check the minimum version, since versions below 5.6.4 lack millisecond precision, which affects timestamps in decision history. Ask the vendor to confirm driver and version support for your chosen database and its high availability setup.
Throughput under your load
The REST service shares the engine's database, job execution and locking behavior with your processes and cases. Measure decision latency and request concurrency with your own rule sets, input sizes and history settings, not with generic figures. Check how the async executor and lock handling behave when several nodes serve decision calls at once, and set capacity limits and timeouts at the gateway so one burst of callers cannot starve other engine work.
Authentication and caller access
The REST application needs authentication before it accepts decision calls from other systems. Confirm which authentication mechanism your release supports, how service accounts are created, and whether authorization checks per decision key are done by the engine or must be added by your application or gateway. Identity management can be replaced with a custom identity service, so confirm how your directory, such as LDAP, maps to the roles that may execute or deploy decisions.
How DeployOpen scopes a decision service
A decision service over REST is scoped as a fixed piece of work, with the deliverables agreed in writing before implementation starts. DeployOpen plans, implements, hardens and documents the self-hosted Flowable DMN engine inside your own infrastructure, so the scope document should name each endpoint your applications will call, the decision keys they will call them with, and the environments (development, test, production) where the service will run. The written scope is also where you decide who owns the decision tables themselves, since DeployOpen builds the service around them but your business owners author and approve the rules.
The scope usually covers four areas. Endpoint design defines which deployment and decision execution calls are exposed, how input variables are named and typed, and how results are returned to callers. Identity integration sets how calling applications authenticate, which identity provider issues their tokens, and which roles may deploy definitions versus execute decisions. The deployment pipeline controls how a new decision file reaches each environment, and verification covers functional tests against deployed decisions, negative tests for unauthorized callers, and a documented runbook. Ask for each of these as a named deliverable with an acceptance check, not as a general statement of intent.
Confirm the items that move cost and schedule before you sign: the number of calling applications, whether your identity provider already issues tokens the service can validate, whether the REST application will run in containers or on virtual machines, and which database Flowable will use in your environment. Each one changes the work. DeployOpen does not estimate its own fees here, so ask for a quote that lists each deliverable, the environments in scope, the testing and documentation effort, and any work your own team must provide, such as network access or identity configuration.
How DeployOpen delivers Flowable decision services
DeployOpen plans, builds and hands over Flowable DMN decision services that other applications call over REST inside your own infrastructure. Each engagement starts from a written scope covering decision keys, input and output contracts, deployment flow and access controls, so the service your applications depend on is defined before any code is written.
How we scope
- Engagements are fixed-scope, with decisions, endpoints and deliverables agreed in writing before work starts.
- We list every decision key, input variable, output field and calling application the REST service must support.
- We confirm where Flowable runs, which database it uses and which identity provider issues tokens for callers.
How we build
- We configure the Flowable REST application or Spring Boot starter for decision execution in your environment.
- We wire identity integration so calling applications authenticate against your identity provider, not default accounts.
- We test decision calls against deployed DMN files, including invalid inputs, missing variables and expected error responses.
How we hand over
- You receive documentation of endpoints, request and response examples, and the deployment steps for new decision versions.
- We provide runbooks covering access reviews, decision deployment rollback and monitoring of the decision endpoints.
- We walk your engineers through the configuration so they can change decisions and access rules without us.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainers can cover Flowable version upgrades, security patching and regression testing when decision tables change.
- Ask for the support scope, response expectations and upgrade approach in writing before the engagement starts.
