Workflow Approvals

Overview#

Artifi uses a two-layer approval system to route write operations to the right people at the right level of scrutiny. This combination gives you powerful, fine-grained control over who approves what -- without building complex custom logic.

Why two layers? Lanes answer "does this need CFO approval?" while step conditions answer "which of our 10 regional managers should approve this specific vendor?"

---

Layer 1: Lane-Based Risk Assessment#

Lanes determine the risk level of a workflow submission and control which steps execute.

Payload → Lane Rules → Green | Yellow | Red → Step Execution Matrix

• Green lane: Low risk — skip most approval steps, auto-complete. Ideal for simple creates and trusted users.
• Yellow lane: Medium risk — single approval required. Used for updates to critical records and moderate amounts.
• Red lane: High risk — multi-level approval chain. Triggered by deletions, large transactions, or high-value changes.

Lane rules are configured in the Admin Dashboard under Workflows > Definitions > Steps > Lane Routing.

---

Layer 2: Step Conditions (Dynamic Approval Routing)#

Step conditions evaluate per step against the workflow payload to decide:

1. Should this step run or be skipped?
2. Who should approve this step?

Available Actions#

Condition Operators#

Field Paths#

Conditions reference fields in the workflow payload using dot notation for nested values:

• vendor_id — top-level field
• total_amount — numeric field for threshold comparisons
• dimensions.department — nested dimension value
• lines.0.account_number — array element access

Condition Groups#

Conditions can be grouped with logical operators. Within a group, you control whether all conditions must match (AND) or any condition must match (OR). Groups are evaluated in order, and the first matching group determines the action.

Evaluation Priority#

When creating workflow steps:

1. Lane-based skip (skip_if_lane) — skips the step entirely based on lane
2. Step condition evaluation — skip, include, assign, or auto-complete
3. Default (no conditions) — include the step with the default assignee

When assigning an approver to a task:

1. Condition override (from step conditions)
2. Submitter (if assignment strategy is "submitter")
3. Approver rules (from step definition)
4. Assigned user (specific user on step)
5. Assigned role (role-based fallback)

---

Approver Rules#

Each workflow step can define static approver rules as the default assignee. Step conditions can override these dynamically.

Dimension-Based Routing#

The dimension approver type looks up the approver from the dimension value metadata. When a transaction comes in with dimensions.department = "ENGINEERING", the engine:

1. Looks up the dimension value for "ENGINEERING"
2. Reads the approver_employee_id from its metadata
3. Finds the user linked to that employee
4. Assigns the task to that user

This is configured in the Admin Dashboard under Workflows > Definitions > Steps > Edit Step > Approver Rules.

---

Practical Examples#

Example 1: 300 Vendors, 10 Approvers#

Problem: 300 vendors, each group of 30 needs a different approver.

Solution: One approval step with 10 assign_to conditions, each using the in operator to match a range of vendor IDs to a specific approver.

Result: When an AP invoice for vendor #35 is submitted, the step automatically routes to the correct approver.

Example 2: Department + Amount Threshold#

Problem: Department heads approve all expenses. CFO only approves expenses of $50,000 or more.

Solution: Two approval steps:

• Step 1 — Department Head Approval: Uses assign_to conditions to route by department (Engineering, Marketing, Sales each go to their department head).
• Step 2 — CFO Approval: Uses a skip_step condition when total_amount < 50000.

Result:

• A $5k Engineering expense goes to the department head only.
• A $75k Marketing expense goes to the Marketing director, then to the CFO.

Example 3: Country-Based Compliance#

Problem: International vendors require a compliance review step; domestic vendors do not.

Solution: Add a skip_step condition on the "Compliance Review" step when country = "US". All non-US vendors automatically trigger the compliance review.

Example 4: Auto-Approve Small Recurring Items#

Problem: Small purchases from known recurring vendors should not require manual approval.

Solution: An AND condition group requiring both total_amount < 100 and vendor_id in [known vendor list] to trigger auto_approve. Both conditions must match for auto-approval.

---

How Lanes and Step Conditions Work Together#

Workflow Submitted
  │
  ├── 1. LANE EVALUATION (risk level)
  │     payload → lane rules → Green | Yellow | Red
  │
  ├── 2. STEP CREATION (per step)
  │     For each step in the workflow definition:
  │       a. Lane skip? → SKIP if current lane is excluded
  │       b. Step conditions? → skip / include / assign / auto-complete
  │       c. No conditions? → INCLUDE with default assignee
  │
  ├── 3. TASK ASSIGNMENT
  │     Assignee = override > submitter > approver rules > role
  │
  └── 4. STEP ADVANCEMENT
        Step completed → next pending step → assign task
        All steps completed → execute workflow

---

Notifications#

Auto-Completed vs Human-Approved#

When a workflow completes, the notification email clearly distinguishes how it was processed:

Auto-completed notifications include the payload details so the user can see exactly what was created (e.g., expense report title, amount, employee) without implying a human reviewed it.

Notification Template Types#

---

Fallback Behavior#

---

Configuration Options#

Admin Dashboard (Available Now)#

• Lane rules (green/yellow/red conditions)
• Step creation, ordering, and deletion
• Step lane skip configuration
• Approver rules (role, employee, dimension, submitter)
• Escalation settings

Step Conditions#

Step conditions are currently configured through the API. An Admin UI for step condition management is planned for a future release.

---

Troubleshooting#

Step condition not matching#

• Verify the field_path matches the actual payload key (case-sensitive)
• Check that string values are properly formatted
• Verify the operator is correct (eq not ==, gte not >=)
• For AND groups, all conditions must match

Approver not assigned#

• Check if the approver override is populated on the step
• Verify the employee-to-user link exists for employee-based assignment
• Verify a user with the required role exists in the organization