Technical guide
Workflow Instance Architecture
Understanding request_data vs context in workflow instances
Workflow Instance Architecture
Understanding request_data vs context
★ Insight ─────────────────────────────────────
- Both are Mutable: Both request_data and context grow throughout the workflow execution
- Source Distinction: request_data = human input (forms), context = system output (APIs, calculations)
- Edit Sections Pattern: Approval steps can have edit_sections allowing approvers to add data to request_data ─────────────────────────────────────────────────
Corrected Understanding
request_data (Human Input Data)
Purpose: Accumulates all user-submitted form data throughout the workflow Mutability: ✅ Grows as users fill forms at different steps Source: Human input (requester + approvers)
context (System Generated Data)
Purpose: Accumulates all system-generated data throughout the workflow Mutability: ✅ Grows as API calls and calculations complete Source: System output (AI, APIs, computations)
Real Example: Multi-Stage Employee Onboarding
Step 1: HR submits initial form
{
"request_data": {
"employee_name": "John Doe",
"position": "Senior Engineer",
"start_date": "2025-03-01",
"department": "Engineering"
},
"context": {}
}Step 2: AI screening (automatic step)
{
"request_data": {
// ❌ No change - no human input yet
"employee_name": "John Doe",
"position": "Senior Engineer",
"start_date": "2025-03-01",
"department": "Engineering"
},
"context": {
// ✅ AI results added
"background_check": {
"status": "clear",
"verified": true,
"checked_at": "2025-01-29T10:00:00Z"
}
}
}Step 3: Manager approval WITH edit_sections
Manager's workflow step definition:
manager_review:
type: decision
assign_to: "@manager"
edit_sections:
- compensation_details # Manager can edit this section
on_approve:
continue_to: hr_finalizeManager fills in additional fields and approves:
{
"request_data": {
// ✅ Manager's input merged in
"employee_name": "John Doe",
"position": "Senior Engineer",
"start_date": "2025-03-01",
"department": "Engineering",
// ⭐ NEW: Manager added these fields
"approved_salary": 145000,
"bonus_eligible": true,
"manager_notes": "Excellent candidate, fast-track onboarding"
},
"context": {
"background_check": {...}
}
}Step 4: Salary calculation API (automatic)
{
"request_data": {
// ❌ No change - no human input
"employee_name": "John Doe",
"approved_salary": 145000
},
"context": {
"background_check": {...},
// ✅ Calculation results added
"compensation_package": {
"base_salary": 145000,
"benefits_value": 25000,
"total_package": 170000,
"calculated_at": "2025-01-29T10:05:00Z"
}
}
}Summary
| Field | Purpose | Source | Grows When | Variable Access | Nullable |
|---|---|---|---|---|---|
| request_data | All human form submissions | Users (requester + approvers) | Forms filled at any step | ${form.field} | ❌ Required |
| context | All system-generated data | APIs, AI, calculations | Automatic steps execute | ${variable.field} | ✅ Optional |
| metadata | Workflow configuration | System | At creation (rarely updated) | Not interpolated | ✅ Optional |