IchWillHeim/workflow_engine_execution.md

Workflow Engine -- Execution Model (Explanation)

Purpose

This document explains how the workflow engine operates at runtime: - how steps are executed - how data flows between steps - how decisions determine the next step

---

High-Level Flow

1. User triggers a workflow (e.g., button)
2. Engine loads the workflow and its start step
3. Engine creates an empty context object
4. Steps are executed sequentially
5. Each step may branch to another step based on its result
6. Execution ends when no next step is defined

---

Core Components

1. Workflow

Defines: - name - start step

2. Step

Defines: - function to execute - input mapping - parameters - output key

3. Function

Implements the actual logic: - UI interaction (dialog, selection) - system action (call, camera, scan) - computation

4. Transition

Maps a result to the next step.

5. Context

Shared data store during execution.

---

Context Model

The context is a key-value store:

{
  "SelectedContact": "Peter",
  "Answer": "YES"
}

Rules: - Steps write results using output_key - Later steps read values via input_mapping

---

Step Execution Lifecycle

For each step:

1. Resolve input values from context
2. Merge with static parameters
3. Call function
4. Receive result:
   • value
   • result_code
5. Store result in context
6. Determine next step via transitions

---

Result Handling

A function returns:

{
  "value": "...",
  "result_code": "YES"
}

The result_code is used for branching.

Examples: - YES / NO - OK / CANCEL - PETER / NOT_PETER - ERROR

---

Transition Resolution

Order: 1. Find transition with matching result_code 2. If none → use is_default 3. If none → end workflow

---

Example Walkthrough

Scenario: Call Workflow

Step 1 -- Select Contact

Result:

{
  "value": "Peter",
  "result_code": "PETER"
}

→ Next step: Ask confirmation

---

Step 2 -- Ask Confirmation

User selects YES

{
  "value": true,
  "result_code": "YES"
}

→ Next step: Call

---

Step 3 -- Call Contact

Uses:

SelectedContact = "Peter"

→ Executes call → End

---

Error Handling

If a function fails: - return result_code = ERROR - transition can handle it - or workflow stops

Optional: - retry step - fallback step - log error

---

Persistence (Optional)

During execution: - store workflow_runs - store workflow_run_steps

Benefits: - debugging - history - resume execution

---

Design Principles

• Data-driven (no hardcoded flows)
• Extensible (new functions)
• Reusable (functions used in multiple workflows)
• UI-independent (engine separated from UI)

---

Summary

Execution is a loop:

Step → Function → Result → Transition → Next Step

Data flows via:

Context (key-value store)

Control flow is defined by:

Transitions (result_code → next step)