Workflow Orchestration & Durable Execution
Comparable to: Temporal, Airflow, Inngest
Key Concepts
Use the concepts below when they fit the task. Not every workflow needs every durability or tracking mechanism shown here.
- Each pipeline step is a registered function chained via named queues with config-driven retries
- Step progress is tracked in shared state and broadcast via streams
- A cron trigger handles scheduled maintenance (e.g. stale order cleanup)
- Queue behavior (retries, backoff, concurrency, FIFO) is defined per queue in
iii-config.yaml
Architecture
HTTP (create order)
→ Enqueue(order-validate) → validate
→ Enqueue(order-payment) → charge-payment
→ Enqueue(order-ship) → ship
→ publish(order.fulfilled)
Cron (hourly) → cleanup-stale
Queue configs (iii-config.yaml):
order-validate: max_retries: 2
order-payment: max_retries: 5, type: fifo, concurrency: 2
order-ship: max_retries: 3iii Primitives Used
| Primitive | Purpose |
|---|---|
registerWorker | Initialize the worker and connect to iii |
registerFunction | Define each pipeline step |
trigger({..., action: TriggerAction.Enqueue({queue})}) | Durable step chaining via named queues |
trigger({function_id: 'state::...', payload}) | Track step progress |
trigger({..., action: TriggerAction.Void()}) | Fire-and-forget stream events and publish |
registerTrigger({type: 'cron'}) | Scheduled maintenance |
registerTrigger({type: 'http'}) | Entry point |
Reference Implementation
See ../references/workflow-orchestration.js for the full working example — an order fulfillment pipeline with validate → charge → ship steps, retry configuration, stream-based progress tracking, and hourly stale-order cleanup.
Common Patterns
Code using this pattern commonly includes, when relevant:
registerWorker(url, {workerName})— worker initializationtrigger({function_id, payload, action: TriggerAction.Enqueue({queue})})— durable step chaining via named queuestrigger({function_id: 'state::update', payload: {scope, key, ops}})— step progress tracking- Named queues with a comment referencing
iii-config.yamlfor retry/concurrency settings const logger = new Logger()— structured logging per step- Each step as its own
registerFunctionwith a single responsibility trigger({function_id: 'publish', payload, action: TriggerAction.Void()})— completion broadcast
Adapting This Pattern
Use the adaptations below when they apply to the task.
- Each step should do one thing and enqueue the next function on success
- Define separate named queues in
iii-config.yamlwhen steps need different retry/concurrency settings - Capture enqueue receipts (
messageReceiptId) for observability and DLQ correlation when needed - The
trackStephelper pattern (state update + stream event) is reusable for any pipeline - Failed jobs exhaust retries and move to a DLQ — see the dead-letter-queues HOWTO
- DLQ support for named queues is provided by the Builtin and RabbitMQ adapters (Redis is pub/sub only)
- Cron expressions use 7-position numeric format:
0 0 * * * * *(every hour)
Engine Configuration
Named queues for pipeline steps are declared in iii-config.yaml under queue_configs with per-queue retry, concurrency, and FIFO settings. See ../references/iii-config.yaml for the full annotated config reference.
Pattern Boundaries
- If the task is "model HTTP endpoints as HTTP-invoked
registerFunctionfunctions" (including{path, id}arrays iterated into registration), preferiii-http-invoked-functions. - Stay with
iii-workflow-orchestrationwhen durable step sequencing, queue retries/backoff, and workflow progress tracking are the primary concerns.
When to Use
- Use this skill when the task is primarily about
iii-workflow-orchestrationin the iii engine. - Triggers when the request directly asks for this pattern or an equivalent implementation.
Boundaries
- Never use this skill as a generic fallback for unrelated tasks.
- You must not apply this skill when a more specific iii skill is a better fit.
- Always verify environment and safety constraints before applying examples from this skill.