iii-workflow-orchestration

name	iii-workflow-orchestration
description	Orchestrates durable multi-step workflow pipelines on the iii engine. Use when building order fulfillment, data pipelines, task orchestration, or any sequential process requiring retries, backoff, step tracking, scheduled cleanup, or dead letter queue (DLQ) handling.

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: 3

iii 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 initialization
• trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) }) — durable step chaining via named queues
• trigger({ function_id: 'state::update', payload: { scope, key, ops } }) — step progress tracking
• Named queues with a comment referencing iii-config.yaml for retry/concurrency settings
• const logger = new Logger() — structured logging per step
• Each step as its own registerFunction with 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.yaml when steps need different retry/concurrency settings
• Capture enqueue receipts (messageReceiptId) for observability and DLQ correlation when needed
• The trackStep helper 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-field 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 registerFunction functions" (including { path, id } arrays iterated into registration), prefer iii-http-invoked-functions.
• Stay with iii-workflow-orchestration when 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-orchestration in 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.