Warm-Flow Workflow Engine

Warm-Flow is a lightweight, domestic (Chinese) workflow engine designed for easy integration. Key features include:

• Simplicity: Uses only 7 database tables, making it easy to integrate and learn.
• Approval Capabilities: Supports pass, return, arbitrary jump, transfer, termination, sign-off (会签), ticket sign-off (票签), delegation, add/remove sign-off, mutual exclusion, and parallel gateways.
• Extensibility: Supports 5 types of listeners, custom condition expressions (including SpEL), and custom handler expressions (including SpEL).
• Database & ORM Support: Supports MySQL, Oracle, and PostgreSQL. Compatible with MyBatis, MyBatis-Plus, MyBatis-Flex, and JPA.
• Runtime Support: Compatible with Spring and Solon frameworks; supports Java 8, 17, and potentially 11.
• Core Features: Built-in multi-tenancy, soft deletes, and permission configurations for roles, departments, and users.

Warm-Flow is a lightweight, high-performance, and extensible workflow engine developed by the Dromara community. It is designed for rapid integration and is particularly suitable for small to medium-sized projects requiring flexible approval processes.

Key Features

• Lightweight: Uses only 7 database tables, minimizing maintenance overhead.
• Comprehensive Approval Operations: Supports pass, return, cancel, recall, arbitrary jump, terminate, transfer, sign, delegate, add/subtract sign, mutual exclusion, parallel, auto-approval, remote access, and script execution.
• Dual Designer Modes: Supports both 'Classic' and 'DingTalk-style' (仿钉钉) workflow designer modes via JAR package integration.
• Flexible Expressions: Built-in support for SpEL (Spring Expression Language) and custom condition/handler expressions.
• Extensible Listeners: Four types of listeners with support for dynamic permissions and parameter passing.
• Broad Compatibility:
  • Frameworks: Spring and Solon.
  • Runtimes: Java 8, Java 17, and Java 21.
  • ORM: MyBatis, MyBatis-Plus, JPA, Easy-Query, and BeetlSql.
  • Databases: MySQL, Oracle, PostgreSQL, and SQL Server.

If you are using a UI library not natively supported (like Arco or TDesign), you can implement the UiAdapter interface and register it via setUiAdapter(yourAdapter).

An adapter must provide:

1. Command Feedback: message, notify, alert, confirm, prompt, and loading.
2. Optional Directives: clickOutside and loadingDirective.
3. Component Mapping: A components object mapping semantic names (e.g., button, input) to your UI library's components.

Best Practices:

• Decoupled Context: Use your UI library's global/standalone APIs (e.g., Naive UI's createDiscreteApi) for message and notify so they work outside the component tree.
• Error Handling: For confirm, ensure you .catch() the rejection when a user cancels to avoid unhandled rejections.

import { setUiAdapter } from '@dromara/warm-flow-designer'
import type { UiAdapter } from '@dromara/warm-flow-designer'

const myAdapter: UiAdapter = {
  name: 'your-ui-lib',
  message: (type, content) => MyMessage[type](typeof content === 'string' ? content : content.message ?? ''),
  notify:  (type, content) => MyNotification[type](typeof content === 'string' ? { message: content } : content),
  alert:   (content, options) => MyModal.alert({ content, ...options }),
  confirm: (content, options) => MyModal.confirm({ content, ...options }),
  prompt:  (content, options) => MyModal.prompt({ content, ...options }).then((value) => ({ value })),
  loading: (options) => { const inst = MyLoading.open(options); return { close: () => inst.close() } },
  components: { button: MyButton, input: MyInput }
}
setUiAdapter(myAdapter)

Warm-Flow UI is transitioning to a dual-mode architecture that supports both a legacy SPA (Single Page Application) mode and a modern NPM Library mode. This allows developers to choose between embedding the designer via an iframe or integrating it directly into a Vue 3 application as a component.

1. SPA Mode (Legacy/Backward Compatible)

• Integration: Uses an <iframe> to embed the designer.
• Deployment: The Vue project is built into static files (dist/) and served via Spring Boot's ResourceHandler (typically mapped to /warm-flow-ui/**).
• Communication: Relies on URL parameters and postMessage for interaction.

2. NPM Library Mode (Modern/Recommended)

• Integration: Install via npm install @warm-flow/vue-designer and use as a standard Vue component.
• Deployment: Distributed as ES/UMD modules via NPM.
• Communication: Uses standard Vue props and events (e.g., @save, @close).

3. Core Architecture Layers

• Core Layer (src/core/): Handles configuration (singleton/injection), Axios instance factory, authentication (TokenProvider), and parameter retrieval from both URL and Props.
• Component Layer (views/ + components/): Contains the actual UI logic, decoupled from specific entry points.

/* SPA Integration Example */
<iframe :src="`${VUE_APP_FLOW_API}/warm-flow-ui/index.html?id=${insId}&type=FlowChart&Authorization=Bearer ${getToken()}`" />

/* NPM Integration Example (Vue 3) */
import { WarmFlowDesigner } from '@warm-flow/vue-designer';
<WarmFlowDesigner :id="defId" @save="onSave" />

The designer can be used as a Vue 3 component library, allowing you to decouple the data layer from your specific backend.

Important: The main entry point is UI-agnostic. You must call setUiAdapter(...) before rendering FlowDesigner to map neutral components (wf-*) to a specific UI library (Element Plus, Ant Design Vue, or Naive UI). Otherwise, the canvas will not render.

To build the library for local use:

yarn build:lib

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import { WarmFlowDesigner, setUiAdapter, setDataProvider, createMockProvider } from '@dromara/warm-flow-designer'
import { elementPlusAdapter } from '@dromara/warm-flow-designer/element-plus'
import '@dromara/warm-flow-designer/style'

const app = createApp(App)

// 1. Select UI Adapter (Must be called before rendering FlowDesigner)
setUiAdapter(elementPlusAdapter)

// 2. Register plugins
app.use(ElementPlus)
app.use(WarmFlowDesigner)
app.mount('#app')

// 3. Optional: Inject custom data provider or mock
setDataProvider(createMockProvider())

When using @dromara/warm-flow-designer as an NPM package (Library mode) rather than a standalone SPA, you should use the exported components and composables from the library entry point (src/index.js). This allows you to embed the designer or flow chart into your own Vue application without conflicting with your existing global configurations (like Pinia or Router).

// Import components from the library entry
import { WarmFlowDesigner, WarmFlowChart, WarmFormDesigner, WarmFormCreate } from '@dromara/warm-flow-designer';

// Import composables for advanced usage
import { useWarmFlowConfig } from '@dromara/warm-flow-designer/core/config';
import { useDark } from '@dromara/warm-flow-designer/composables/useDark';
import { useCache } from '@dromara/warm-flow-designer/plugins/cache';
import { useModal } from '@dromara/warm-flow-designer/plugins/modal';

// Import default configuration types
import { WarmFlowDefaultConfig } from '@dromara/warm-flow-designer/core/config';