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