Workflow Management

Overview

• What you’ll learn: How to configure document workflows, build approval processes, understand workflow nodes and transitions, and automate business operations using iDempiere’s workflow engine.
• Prerequisites: Lessons 1-12 (Beginner level)
• Estimated reading time: 25 minutes

Introduction

Every time you click “Complete” on a Sales Order, “Prepare” on an Invoice, or “Process” on a Payment, you are triggering a workflow. iDempiere’s workflow engine orchestrates document processing, approval routing, and automated actions across the entire system. Understanding workflows is essential because they govern how documents move through their lifecycle and how business rules are enforced during state transitions.

This lesson covers the workflow engine from the ground up: the data model, workflow types, node configuration, approval chains, and hands-on creation of a custom approval workflow.

Workflow Architecture

The workflow engine is built on four core tables:

• AD_Workflow — The workflow definition (header). Defines the type, starting node, and overall configuration.
• AD_WF_Node — Individual steps within a workflow. Each node represents an action, decision, or subprocess.
• AD_WF_NodeNext — Transitions between nodes. Defines the sequence and conditions for moving from one node to the next.
• AD_WF_Responsible — Defines who is responsible for approving or acting on workflow nodes.

At runtime, two additional tables track execution:

• AD_WF_Process — A running instance of a workflow (one per document being processed).
• AD_WF_Activity — A running instance of a node within a process (the current step).

Workflow Types

iDempiere supports three workflow types, each serving a different purpose:

Document Process Workflow

This is the most common type. It defines the state machine for document processing — the sequence of steps a document goes through when you click Complete, Void, Close, or other DocAction buttons. Every document type (Order, Invoice, Payment, etc.) has a Document Process workflow assigned to its document type (C_DocType.AD_Workflow_ID).

The standard document processing flow looks like this:

Draft (DR) → In Progress (IP) → Completed (CO)
                                      ↓
                                 Closed (CL)

Completed (CO) → Reversed (RE)
Draft (DR) → Voided (VO)

Document Value Workflow

Triggered automatically when a document meets certain conditions, regardless of user action. These workflows fire on specific column value changes and are used for approval routing. For example: “When a Purchase Order total exceeds $10,000, route to the VP of Purchasing for approval.”

Document Value workflows are configured with:

• Table: Which table triggers the workflow (e.g., C_Order).
• Column: Which column change triggers it (e.g., DocStatus).
• Value: The specific value that triggers it (e.g., “CO” for Completed).

General Workflow (Manufacturing)

Used primarily in manufacturing for routing operations — defining the sequence of work center steps needed to produce a product. These workflows are beyond the scope of this general foundation lesson.

The Document Processing Workflow in Detail

Let us examine how a standard document processing workflow is structured. Open Workflow > Workflow and look at the “Process_Order” workflow as an example.

Workflow Header (AD_Workflow)

Name:           Process_Order
Workflow Type:  Document Process
Table:          C_Order
Start Node:     (DocAuto)
Duration:       0
Entity Type:    D (Dictionary - core)
Publish Status: Released

Key fields on the workflow header:

• Workflow Type: Determines behavior — Document Process, Document Value, or General.
• Table: The table this workflow operates on.
• Start Node: The first node executed when the workflow launches.
• Priority: When multiple workflows could apply, priority determines which runs first.
• Valid From / Valid To: Date-based activation for seasonal or temporary workflows.
• Publish Status: Must be “Released” for the workflow to be active.

Workflow Nodes (AD_WF_Node)

Each node represents a step in the workflow. A Document Process workflow typically has nodes for each document action:

Node: (DocPrepare)
  Action: Document Action
  Document Action: Prepare

Node: (DocComplete)
  Action: Document Action
  Document Action: Complete

Node: (DocVoid)
  Action: Document Action
  Document Action: Void

Node: (DocClose)
  Action: Document Action
  Document Action: Close

Node: (DocReverse)
  Action: Document Action
  Document Action: Reverse - Correct

Node action types include:

• Document Action: Executes a document action (Prepare, Complete, Void, etc.).
• User Choice: Presents the user with approval options (Approve/Reject).
• Set Variable: Sets a column value on the document.
• User Window: Opens a window for user interaction.
• Process: Runs an AD_Process.
• Sub Workflow: Launches another workflow.
• Wait (Sleep): Pauses execution for a specified duration.
• EMail: Sends an email notification.

Node Transitions (AD_WF_NodeNext)

Transitions define how execution flows from one node to the next:

From: (DocPrepare) → To: (DocComplete)
  Sequence: 10
  Is Standard Transition: Yes

From: (DocComplete) → To: (DocClose)
  Sequence: 100

From: (DocComplete) → To: (DocReverse)
  Sequence: 110

Transition configuration:

• Sequence: When multiple transitions exist from the same node, sequence determines evaluation order.
• Transition Code: An optional SQL condition. If the condition evaluates to true, this transition is taken. If blank, the transition is unconditional.
• Is Standard Transition: Marks the “normal” path. Non-standard transitions represent exception paths (like approval rejection routing).

Approval Workflows

Approval workflows are one of the most practically useful features in iDempiere. They route documents to designated approvers based on rules you define.

AD_WF_Responsible (Workflow Responsible)

Defines who handles workflow activities:

• Human: A specific user must act.
• Organization: Any user in the specified organization can act.
• Role: Any user with the specified role can act.
• Invoker: The person who triggered the workflow is responsible (common for document processing).

Approval Hierarchy

iDempiere supports approval routing based on the organizational hierarchy. Each user can have a Supervisor defined (AD_User.Supervisor_ID). When a document requires approval:

1. The system checks the document amount against the user’s approval threshold.
2. If the amount exceeds the threshold, the document is routed to the user’s supervisor.
3. The supervisor’s threshold is checked. If still exceeded, it escalates further up the chain.
4. This continues until a user with sufficient authority approves or the top of the chain is reached.

Creating a Custom Approval Workflow: Step by Step

Let us build a Purchase Order approval workflow that requires manager approval for orders over $5,000.

Step 1: Create the Workflow Header

Navigate to Workflow > Workflow and create a new record:

Name:            PO Approval Over 5000
Workflow Type:   Document Value
Table:           C_Order
Document Value:  DocStatus = CO
Priority:        5
Publish Status:  Released
Duration:        1 (days)
Entity Type:     User Maintained

Step 2: Define the Workflow Responsible

Navigate to Workflow > Workflow Responsible and create:

Name:              PO Approval Manager
Responsible Type:  Human
User:              (Select the approving manager)

Step 3: Create Workflow Nodes

Switch to the Node tab and create three nodes:

Node 1: Check Amount
  Action:     User Choice
  Column:     GrandTotal
  Workflow Responsible: PO Approval Manager
  Duration:   1

Node 2: Approved
  Action:     Set Variable
  Column:     IsApproved
  Value:      Y

Node 3: Rejected
  Action:     Set Variable
  Column:     DocStatus
  Value:      DR

Step 4: Create Transitions

Switch to the Node Next (Transition) tab:

Transition 1:
  From: Check Amount → To: Approved
  Sequence: 10
  Description: Approved path

Transition 2:
  From: Check Amount → To: Rejected
  Sequence: 20
  Description: Rejected path

Step 5: Set the Start Node

Back on the workflow header, set Start Node to “Check Amount”.

Step 6: Configure the Trigger

On the workflow header, configure the Document Value trigger:

Column:  DocStatus
Value:   CO

This means the workflow fires when a Purchase Order’s DocStatus changes to “CO” (Completed) and the GrandTotal exceeds the user’s approval limit.

Priority and Escalation

Each workflow and each node can have a priority setting (0-9, where 0 is highest). Priority affects:

• Processing order: Higher-priority workflows are processed first by the workflow processor.
• User notification: High-priority activities appear prominently in the user’s workflow inbox.
• Escalation: You can configure a Duration and Duration Unit on each node. If the activity is not completed within the specified time, it escalates — either to the next user in the hierarchy or to a designated escalation user.

-- Node escalation configuration
Duration:       2
Duration Unit:  Day
-- If not acted upon in 2 days, escalate to supervisor

Email Notifications

iDempiere can send email notifications at various workflow stages:

• When an activity is assigned: The responsible user receives an email that a document needs their attention.
• When an activity is escalated: The escalation target is notified.
• When a workflow completes: The originator can be notified of the outcome.

Email templates are configured on the workflow node. The system uses the Mail Template (R_MailText) associated with the node. Template variables give you access to document fields:

Subject: Purchase Order @DocumentNo@ requires your approval
Body: A purchase order for @GrandTotal@ from @C_BPartner_ID@
      requires your approval. Please review in your workflow inbox.

Workflow History and Logs

Every workflow execution is fully auditable:

• AD_WF_Process: Records the overall workflow execution — when it started, current state, which document.
• AD_WF_Activity: Records each step — which node was executed, who acted, when, and the result (Approved/Rejected/Completed).
• AD_WF_EventAudit: Detailed event log with timestamps for fine-grained auditing.

To review workflow history, navigate to Workflow > Workflow Activities for pending items, or Workflow > Workflow Process for completed workflows. You can also access workflow history directly from a document using the toolbar’s workflow status icon.

Testing Workflows

Follow this process to test a new workflow:

1. Set Publish Status to “Test” initially. This allows you to iterate without affecting production.
2. Create a test document that meets your trigger conditions.
3. Process the document and observe whether the workflow fires.
4. Check Workflow Process to see the execution state, which node is active, and any errors.
5. Act on pending activities from the Workflow Activities window.
6. Review logs for any issues. Common problems include:
   • Missing Workflow Responsible assignment.
   • Incorrect transition conditions.
   • Start Node not set.
   • Publish Status not set to “Released” (for production).
7. Set Publish Status to “Released” when testing is complete.

Common Workflow Patterns

Sequential Approval

Document flows through a chain of approvers in order: Department Manager, then Finance Director, then CFO. Each approver’s node transitions to the next only on approval.

Parallel Approval

Multiple approvers must all approve. Create separate approval nodes that all transition from the same predecessor, then converge on a “join” node that requires all incoming activities to complete.

Conditional Routing

Use transition conditions to route documents differently based on amount, type, or other criteria:

-- Transition condition: orders over 10000 go to VP
GrandTotal > 10000

-- Transition condition: orders under 10000 auto-approve
GrandTotal <= 10000

Auto-Approval with Threshold

Skip the approval step entirely for small amounts. The first node checks the amount and transitions directly to “Approved” if below threshold, or to the approval node if above.

Key Takeaways

• iDempiere’s workflow engine powers document processing, approval routing, and automated actions.
• Three workflow types exist: Document Process (state machine), Document Value (triggered by data changes), and General (manufacturing).
• Workflow Nodes define individual steps; NodeNext transitions define the flow between steps with optional conditions.
• Approval workflows route documents through a hierarchy based on user authority and document amount.
• Priority and Duration settings enable escalation when activities are not acted upon promptly.
• All workflow execution is fully logged and auditable via AD_WF_Process and AD_WF_Activity.
• Always test workflows with Publish Status “Test” before releasing to production.

What’s Next

In Lesson 16, you will set up your iDempiere development environment using Eclipse IDE. This marks your transition from configuration-based customization to code-based development — opening up the full power of iDempiere’s extensible architecture.

草稿 (DR) → 處理中 (IP) → 已完成 (CO)
                                ↓
                           已關閉 (CL)

已完成 (CO) → 已沖銷 (RE)
草稿 (DR) → 已作廢 (VO)

名稱：          Process_Order
工作流程類型：  Document Process
資料表：        C_Order
起始節點：      (DocAuto)
持續時間：      0
Entity Type：   D（Dictionary - 核心）
發佈狀態：      Released

節點：(DocPrepare)  動作：Document Action  文件動作：Prepare
節點：(DocComplete) 動作：Document Action  文件動作：Complete
節點：(DocVoid)     動作：Document Action  文件動作：Void
節點：(DocClose)    動作：Document Action  文件動作：Close
節點：(DocReverse)  動作：Document Action  文件動作：Reverse - Correct

下書き (DR) → 処理中 (IP) → 完了 (CO)
                                  ↓
                             クローズ (CL)

完了 (CO) → 取消 (RE)
下書き (DR) → 無効 (VO)