Flowable Learning Project

A step-by-step learning project to understand the Flowable BPM engine by building a state machine incrementally using Spring Boot.

Tech Stack

• Java 21 (Amazon Corretto)
• Spring Boot 3.4.3
• Flowable 7.1.0 (Process Engine)
• PostgreSQL 17 (via Docker)
• Gradle 9.3.1

Prerequisites

• Java 21+
• Docker & Docker Compose
• Gradle (or use the included gradlew wrapper)

Getting Started

1. Start PostgreSQL

docker compose up -d

This starts a PostgreSQL 17 container with a named volume (flowable-pgdata) for data persistence.

2. Run the Application

./gradlew bootRun

The app starts on http://localhost:8080. Flowable auto-creates its schema tables on first run.

Learning Path

Step 1: Project Setup (done)

• Spring Boot + Flowable + PostgreSQL wiring
• Flowable auto-configures ProcessEngine, IdmEngine, EventRegistryEngine
• 45 tables created in PostgreSQL for process management

Step 2: Simple BPMN Process (done)

• Created a Leave Request process: Start → UserTask → End
• REST APIs to start a process, list tasks, and complete tasks
• Learned: BPMN XML, RuntimeService, TaskService, auto-deployment from resources/processes/

Step 3: Service Tasks (done)

• Added automatic Java logic via JavaDelegate implementations
• Flow: Start → ValidateRequest (auto) → ApproveTask (waits) → SendNotification (auto) → End
• Learned: JavaDelegate, DelegateExecution, process variables, flowable:class

Step 4: User Tasks (upcoming)

Step 5: Gateways (upcoming)

Step 6: Events & Timers (upcoming)

Step 7: Full State Machine (upcoming)

API Reference

Submit a Leave Request

POST /api/leave-request
Content-Type: application/json

{
  "employeeName": "John",
  "reason": "Vacation"
}

List Pending Tasks

GET /api/tasks?assignee=manager

Complete a Task

POST /api/tasks/{taskId}/complete

Get Process Variables

GET /api/process/{processInstanceId}/variables

Project Structure

src/main/
├── java/org/example/flowable/
│   ├── FlowableApplication.java          # Main class
│   ├── LeaveRequestController.java       # REST APIs
│   └── delegate/
│       ├── ValidateLeaveRequestDelegate.java  # Validates leave request
│       └── SendNotificationDelegate.java      # Simulates notification
└── resources/
    ├── application.yaml                  # DB & Flowable config
    └── processes/
        └── leave-request.bpmn20.xml      # BPMN process definition

Postman Collection

Import flowable-leave-request.postman_collection.json into Postman to test all APIs. Run requests 1-5 in order for the full flow.