193 lines
3.8 KiB
Markdown
193 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
``` json
|
|
{
|
|
"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:
|
|
|
|
``` json
|
|
{
|
|
"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:
|
|
|
|
``` json
|
|
{
|
|
"value": "Peter",
|
|
"result_code": "PETER"
|
|
}
|
|
```
|
|
|
|
→ Next step: Ask confirmation
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
#### Step 2 -- Ask Confirmation
|
|
|
|
User selects YES
|
|
|
|
``` json
|
|
{
|
|
"value": true,
|
|
"result_code": "YES"
|
|
}
|
|
```
|
|
|
|
→ Next step: Call
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
#### Step 3 -- Call Contact
|
|
|
|
Uses:
|
|
|
|
``` json
|
|
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:
|
|
|
|
``` text
|
|
Step → Function → Result → Transition → Next Step
|
|
```
|
|
|
|
Data flows via:
|
|
|
|
``` text
|
|
Context (key-value store)
|
|
```
|
|
|
|
Control flow is defined by:
|
|
|
|
``` text
|
|
Transitions (result_code → next step)
|
|
```
|