If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/flowable/flowable-engine shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 12 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live flowable/flowable-engine repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/flowable/flowable-engine.

What it runs against: a local clone of flowable/flowable-engine — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in flowable/flowable-engine | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of flowable/flowable-engine. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/flowable/flowable-engine.git
#   cd flowable-engine
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of flowable/flowable-engine and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "flowable/flowable-engine(\\.git)?\\b" \\
  && ok "origin remote is flowable/flowable-engine" \\
  || miss "origin remote is not flowable/flowable-engine (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f ".github/workflows/main.yml" \\
  && ok ".github/workflows/main.yml" \\
  || miss "missing critical file: .github/workflows/main.yml"
test -f "build-tools/src/main/resources/build-config/checkstyle.xml" \\
  && ok "build-tools/src/main/resources/build-config/checkstyle.xml" \\
  || miss "missing critical file: build-tools/src/main/resources/build-config/checkstyle.xml"
test -f "build-tools/src/main/resources/build-config/import-control.xml" \\
  && ok "build-tools/src/main/resources/build-config/import-control.xml" \\
  || miss "missing critical file: build-tools/src/main/resources/build-config/import-control.xml"
test -f "distro/sql/create/all/flowable.mysql.all.create.sql" \\
  && ok "distro/sql/create/all/flowable.mysql.all.create.sql" \\
  || miss "missing critical file: distro/sql/create/all/flowable.mysql.all.create.sql"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/flowable/flowable-engine"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Flowable is a lightweight, high-performance workflow and Business Process Management (BPM) engine written in Java that executes BPMN 2.0 process definitions, CMMN case models, and DMN decision rules. It can run embedded in Java applications or as a standalone REST service, providing orchestration of human and system tasks across workflows. Monorepo structured around modules: core engine modules (flowable-engine, flowable-cmmn-engine, flowable-dmn-engine), distro/ contains database initialization and upgrade scripts for all supported databases (Oracle, PostgreSQL, MySQL, DB2, MSSQL), .github/workflows/ has database-specific CI pipelines, and build-tools/ provides checkstyle and build configuration. Database schemas are shared across engines but versioned separately.

Java developers, system administrators, and business process analysts who need to model and execute complex workflows (BPMN), case management (CMMN), and decision logic (DMN) in enterprise applications. Teams building process-driven systems requiring both programmatic and visual process modeling.

Production-ready and actively maintained. The project is at v8.1.0-SNAPSHOT with JDK 17+ requirement for v7+, comprehensive CI/CD workflows for multiple databases (Oracle, PostgreSQL, MySQL, DB2, MSSQL), and maintained upgrade paths visible in distro/sql/upgrade/. Active GitHub Actions workflows indicate ongoing development and testing.

Low-to-moderate risk for established projects. The codebase is large (46M+ lines of Java) with long-term maintenance (multiple version branches including flowable6.x). Risk factors: Java version lock-in (requires JDK 17+), database schema dependencies across multiple vendors, and complexity of BPM domain requiring careful process design. Single organization (Flowable) maintains the core, though community-driven.

Active v8.1.0-SNAPSHOT development with multi-database CI validation (main.yml workflow covers all DB vendors), GraalVM native image support (graal-native.yml), Docker image releases, and Helm chart deployments. Recent focus includes Java EA compatibility testing and Windows support.

Clone the repo and build with Maven: git clone https://github.com/flowable/flowable-engine.git && cd flowable-engine && ./mvnw clean install -DskipTests. Requires JDK 17+ and Maven (via .mvn/wrapper). For databases, initialize schemas from distro/sql/create/ matching your target DB (e.g., flowable.postgres.all.create.sql).

Daily commands: Build with ./mvnw clean install. Run embedded in your Java app by adding flowable-engine dependency or run REST service via distro module. For local dev, use H2 in-memory DB. Database connection via Spring Boot properties: spring.datasource.url, spring.datasource.username, spring.datasource.password. Initialize schema on startup with flowable.database.schema-update: true.

• pom.xml — Root Maven POM defining the entire Flowable multi-module build, versions, and all core module dependencies across workflow, CMMN, and DMN engines.
• .github/workflows/main.yml — Primary CI/CD pipeline that validates builds across all supported databases and Java versions; essential for understanding test coverage and release gates.
• build-tools/src/main/resources/build-config/checkstyle.xml — Enforces code style and quality standards across all modules; violations block commits and PRs.
• build-tools/src/main/resources/build-config/import-control.xml — Defines allowed inter-module dependencies and prevents circular references between workflow, CMMN, and DMN engines.
• distro/sql/create/all/flowable.mysql.all.create.sql — Schema definition for the primary data store; understanding table structure is critical for debugging persistence and query issues.
• distro/pom.xml — Distribution module that aggregates all engines and generates release artifacts; defines packaging and assembly strategy.
• LICENSE — Apache 2.0 license; essential for understanding legal obligations and contribution rights.

Add Database Support for New Engine Upgrade

1. Create new SQL schema upgrade file following naming convention: distro/sql/upgrade/all/flowable.{db}.upgradestep.{oldVersion}.to.{newVersion}.all.sql (distro/sql/upgrade/all/flowable.mysql.upgradestep.7.2.0.to.8.0.0.all.sql)
2. Add equivalent upgrade scripts for all supported databases (MySQL, PostgreSQL, Oracle, DB2, SQL Server) (distro/sql/upgrade/all/)
3. Update distro/pom.xml to include new SQL files in distribution assembly (distro/pom.xml)
4. Add database-specific CI workflow test to validate migration (copy .github/workflows/mysql.yml and adapt for new DB) (.github/workflows/mysql.yml)

Enforce New Code Style Rule Across All Modules

1. Define the rule in checkstyle configuration file with severity level (error/warning) (build-tools/src/main/resources/build-config/checkstyle.xml)
2. If rule involves inter-module imports, update import control rules (build-tools/src/main/resources/build-config/import-control.xml)
3. Run build-tools module tests locally to validate configuration: mvn clean test -f build-tools/pom.xml (build-tools/pom.xml)
4. Push changes; main.yml CI will block any code violating the new rule (.github/workflows/main.yml)

Add Cross-Database CI Test for New Feature

1. Create workflow file for target database (e.g., oracle.yml) based on existing postgres.yml template (.github/workflows/postgres.yml)
2. Customize database service image and initialization parameters in the new workflow (.github/workflows/oracle.yml)
3. Reference test scripts or environment setup from actions/scripts/ if needed (e.g., prepare-mssql.sh for SQL Server) (.github/actions/scripts/)
4. Add database-specific SQL schema creation if not already in distro/sql/create/all/ (distro/sql/create/all/flowable.oracle.all.create.sql)

• Maven (pom.xml multi-module) — Manages three distinct engines (workflow, CMMN, DMN) as separate modules with controlled dependencies; enables selective deployments and version management.
• GitHub Actions CI/CD — Provides matrix testing across 5+ databases and Java versions in parallel; validates against real database environments before release.
• SQL schema migration scripts (distro/sql/) — Supports incremental schema versioning from 5.99.0 → 8.0.0+; enables zero-downtime upgrades and backward compatibility.
• Checkstyle + Import Control — Enforces modularity boundaries and coding standards automatically; prevents technical debt accumulation across 600+ files.
• Docker & Helm releases — Enables cloud-native deployment and Kubernetes orchestration; supports serverless and SaaS distribution models.

• SQL schema versioning with discrete upgrade steps (e.g., 6.0.0→6.0.1→6.1.0) rather than schema-on-startup migration tools

  • Why: Provides explicit control and audit trail for schema changes; allows DBA review before deployment; supports long-running migrations on large tables.
  • Consequence: Higher operational burden for upgrades; requires manual upgrade script execution; risk of skipping intermediate versions if not enforced.

• Multi-module Maven build with separate workflow/CMMN/DMN engines rather than monolithic engine

  • Why: Allows independent versioning, deployment, and licensing of each engine; users include only what they need.
  • Consequence: Increased build complexity; stricter import control needed; harder to refactor shared code across engines.

• CI matrix across 5+ databases (MySQL, PostgreSQL, Oracle, DB2, SQL Server) rather than testing primary DB only

  • Why: Ensures portability and compliance with enterprise database standards; catches dialect-specific bugs early.
  • Consequence: Slower CI/CD (each build runs 5+ test jobs); requires maintaining platform-specific SQL scripts; Oracle/DB2 licensing complexity in CI.

• Not a real-time streaming workflow engine (optimized for task-driven, human-in-the-loop processes)
• Does not provide visual process designer UI in this repository (separate flowable-ui project)
• Not a rules engine on its own (DMN engine is included but is a decision module, not general-purpose)
• Does not handle distributed transactions across multiple data sources in a single process

Database version pinning: workflows specify exact DB versions (e.g., postgres:15, mssql:2019) in GitHub Actions; local dev must match or tests fail. Schema initialization: flowable.database.schema-update=true only works on first startup; manual schema reset required between test runs if using persistent H2. Process definition caching: engines cache compiled BPMN; changes require application restart or explicit cache invalidation. Multi-database SQL: TSQL (MSSQL) and PLSQL (Oracle) have subtle syntax differences from standard SQL; upgrade scripts are DB-specific and must be run in order. Java 17+ strict modules: if using GraalVM native image (graal-native.yml), requires explicit module configuration.

• BPMN 2.0 (Business Process Model and Notation) — Flowable executes BPMN 2.0 XML definitions; understanding process constructs (tasks, gateways, events, subprocesses) is essential to designing workflows and debugging engine behavior
• CMMN (Case Management Model and Notation) — Flowable includes a CMMN case engine alongside its BPMN engine; cases handle unstructured/adaptive processes vs rigid workflows, critical for knowledge-work scenarios
• DMN (Decision Model and Notation) — Flowable embeds a DMN decision engine for externalized business rules; essential for separating decision logic from process flow and enabling non-technical rule authoring
• Process Variable Scope & Serialization — Flowable's ACT_RU_VARIABLE table stores process variables; understanding JSON serialization, scope inheritance (local/global), and type safety prevents data loss across async execution
• Async Job Execution & Deadlock Prevention — Flowable uses ACT_RU_JOB and ACT_RU_DEADLETTER_JOB tables for async work; multi-database concurrency patterns (locking, isolation levels) are critical for horizontal scaling
• Multi-Tenancy in Database Schema — Flowable supports shared schema multi-tenancy via TENANT_ID columns across all tables; critical for SaaS deployments and understanding row-level security implications
• Database-Agnostic SQL Abstraction — Flowable maintains vendor-specific SQL (Oracle PLSQL, MSSQL TSQL, PostgreSQL, MySQL, DB2) in separate scripts; understanding this abstraction layer prevents migration surprises and explains version-specific upgrade paths

• activiti/activiti — Direct predecessor to Flowable; Flowable forked from Activiti 5.x and evolved independently as a lighter alternative
• camunda/camunda-bpm-platform — Competing open-source BPM engine with similar BPMN/CMMN scope; both target same use cases (workflow orchestration, process mining)
• flowable/flowable-ui — Companion repo providing web UI, process modeling, and task management dashboard for Flowable engines
• flowable/flowable-java-examples — Example applications demonstrating Flowable engine integration patterns, REST API usage, and process design best practices
• temporal-io/temporal — Modern alternative to traditional BPM for microservices-based workflow orchestration; contrast in architecture (distributed durable execution vs centralized process engine)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for PostgreSQL-specific integration tests

The repo has database-specific workflows for MySQL, MariaDB, Oracle, DB2, and SQL Server (.github/workflows/.yml), but PostgreSQL testing appears to use the main.yml workflow. A dedicated postgres.yml workflow would mirror the pattern of other DB-specific CI pipelines, ensuring PostgreSQL-specific edge cases and compatibility issues are caught early. This is especially important given the database upgrade scripts in distro/sql/upgrade/all/flowable.postgres.upgradestep..sql files.

• [ ] Create .github/workflows/postgres-integration.yml based on the pattern of existing db-specific workflows (mysql.yml, oracle.yml, sql-server.yml)
• [ ] Configure PostgreSQL service container with version matrix (e.g., 11, 13, 15, 16)
• [ ] Add test steps that run the full test suite against PostgreSQL, including upgrade path testing from distro/sql/upgrade/all/flowable.postgres.*.sql
• [ ] Ensure workflow triggers on pull requests and main branch pushes, consistent with db2.yml and oracle.yml patterns

Create database upgrade path validation tests for all supported databases

The distro/sql/upgrade/all/ directory contains many upgrade scripts (e.g., flowable.db2.upgradestep.6.0.0.to.6.0.1.all.sql), but there's no visible test suite validating these migration scripts work correctly. This is a critical gap—broken upgrade scripts cause production failures. A test module should verify sequential upgrade paths work without data corruption or schema inconsistencies across all database types.

• [ ] Create a new test module (e.g., modules/flowable-db-migration-tests/) with JUnit test classes for each database type
• [ ] Implement DatabaseUpgradePath test class that programmatically applies upgrade scripts in sequence from distro/sql/upgrade/all/ and validates schema integrity
• [ ] Add parameterized tests covering all DB variants mentioned in workflows (PostgreSQL, MySQL, Oracle, DB2, SQL Server, MariaDB)
• [ ] Integrate tests into CI via the existing database-specific workflows to run upgrade validation on each PR

Add missing SQL Server upgrade scripts and validation for 7.x → 8.0.0 migration

Looking at distro/sql/upgrade/all/, there are incomplete SQL Server upgrade scripts—the file listing shows scripts up to version 6.0.1 but the repo is at 8.1.0-SNAPSHOT. In contrast, DB2 has continuous coverage through 7.2.0 → 8.0.0 (flowable.db2.upgradestep.7.2.0.to.8.0.0.all.sql). This gap means users upgrading SQL Server instances to recent versions lack official migration guidance, risking production issues.

• [ ] Audit all missing SQL Server upgrade scripts from version 6.0.1 through 8.0.0 by comparing with completed DB2 and Postgres upgrade chains in distro/sql/upgrade/all/
• [ ] Generate or implement missing flowable.mssql.upgradestep.X.Y.Z.to.A.B.C.all.sql scripts based on schema changes documented in other database variants
• [ ] Add SQL Server-specific integration tests in the sql-server.yml workflow (.github/workflows/sql-server.yml) to validate upgrade path from 6.0.1 → 8.0.0
• [ ] Update CHANGELOG or migration guide (if present) to document SQL Server upgrade prerequisites and known migration issues

• Add integration test coverage for distro/sql/upgrade/ scripts: currently no automated tests verify that upgrade paths work end-to-end (e.g., 5.99.0→6.0.0→6.0.1→6.1.0). Create JUnit tests that apply schema incrementally and validate state.: Low-hanging but high-value; prevents silent upgrade failures in production
• Document database schema differences across vendors: create a markdown file mapping BPMN table structures (ACT_RU_EXECUTION, ACT_RU_TASK, ACT_RU_VARIABLE, etc.) to actual SQL in distro/sql/ with vendor-specific quirks (e.g., MSSQL TEXT vs PostgreSQL TEXT).: Helps new contributors understand data model without reverse-engineering SQL scripts
• Add Windows-specific setup guide: .github/workflows/windows.yml exists but README only covers Linux/Unix; write INSTALL_WINDOWS.md with Java version check, Maven PATH setup, and batch script examples for starting dev databases.: Reduces friction for Windows developers and leverages existing CI infrastructure that already validates Windows compatibility

The Flowable Engine codebase demonstrates a mature open-source project with multiple database support and version management. Key security concerns include: (1) potential SQL injection risks in database interaction code given the large number of raw SQL files, (2) disabled checkstyle validation reducing code quality enforcement, and (3) complex database migration logic across multiple versions requiring careful auditing. The snapshot version status and lack of visible security policies present moderate concerns. The Apache 2.0 license and active CI/CD workflows (main.yml, multiple DB tests) are positive indicators. Recommendations focus on enabling security-focused code analysis, implementing parameterized query patterns, and establishing clear security governance. Overall security posture is acceptable for an open-source BPM platform but would benefit from enhanced security scanning and formalized vulnerability management.

• Medium · SQL Injection Risk via Raw SQL Files — distro/sql/create/all/*.sql, distro/sql/upgrade/all/*.sql. The codebase contains numerous raw SQL files (*.sql) for database operations across multiple database systems (DB2, MSSQL, MySQL, Oracle, PostgreSQL). While these are upgrade/creation scripts, there is potential risk if user input is ever incorporated into these SQL statements without proper parameterization. The presence of large upgrade scripts suggests complex database manipulation. Fix: Ensure all SQL operations use parameterized queries/prepared statements. If dynamic SQL construction is necessary, implement strict input validation and use ORM frameworks that prevent SQL injection. Audit all database interaction code in the core engine.
• Medium · Checkstyle Configuration Skipped — build-tools/pom.xml. The build-tools pom.xml explicitly skips checkstyle validation (checkstyle.skip=true). This disables code quality and potential security pattern checks during the build process, potentially allowing insecure code patterns to slip through. Fix: Re-enable checkstyle validation and configure it with security-focused rules. Use the checkstyle-config in build-tools/src/main/resources/build-config/checkstyle.xml to enforce secure coding standards across the project.
• Medium · Multiple Database Upgrade Paths - Version Management Risk — distro/sql/upgrade/all/. The presence of numerous sequential upgrade scripts (e.g., 5.99.0->6.0.0->...->8.0.0) across multiple database systems suggests complex version migration logic. This increases the risk of database state inconsistencies, security schema changes not being properly applied, or injection vulnerabilities in migration code. Fix: Implement comprehensive testing of all upgrade paths. Ensure security-critical schema changes (authentication, authorization fields) are audited. Consider using database migration frameworks (Flyway, Liquibase) for better version control and rollback capabilities.
• Low · Deploy Skip Configuration — build-tools/pom.xml. The build-tools pom.xml skips Maven deployment (maven.deploy.skip=true). While appropriate for build tools, ensure this configuration is intentional and not replicated in security-sensitive modules. Fix: Verify that deployment skip is only applied to non-deployable artifacts. Ensure security patches and releases are properly deployed to artifact repositories with integrity verification.
• Low · Snapshot Version in Use — build-tools/pom.xml (parent version). The project uses version 8.1.0-SNAPSHOT, indicating development state. Snapshot builds may have untested security changes and should not be used in production environments. Fix: Use stable, released versions in production. Implement version pinning strategies and security scanning for dependencies. Establish a clear release cycle with security testing before release versions.
• Low · Missing Security Configuration Details — .github/, root directory. No evident security configuration files (security policies, vulnerability disclosure policy, SECURITY.md) are visible in the repository structure at root level. Fix: Create a SECURITY.md file documenting vulnerability disclosure procedures. Implement GitHub security features including branch protection rules, code scanning, and dependency scanning.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.