website·Indexed 31 days ago
https://zigflow.devA declarative workflow orchestration layer for Temporal that allows users to define workflows using YAML or JSON.
Zigflow uses two separate channels for data movement. Confusing them is a common authoring error:
$output: Holds the result of the most recent task only. It is overwritten by every task and is the value the workflow returns. Use a task's output.as to shape this value.$context: Shared data that persists across tasks. Use a task's export.as to write to it and reference $context to read it later.Order of Operations per Task:
. in expressions).output.as is evaluated against the raw result and stored as $output.export.as is evaluated against the raw result and replaces $context.Key Rules:
export replaces $context entirely. To accumulate data, merge explicitly: export: { as: '${ $context + { key: . } }' }.export into $context.output.as on that task to shape the final return value.uuid, timestamp, timestamp_iso8601, and jq's now—must only be used inside a set task. This ensures they are evaluated within a Temporal side effect so the result survives replay. Using these functions in a call body, argument, or any other task position will be rejected during validation. Generate the value in a set task first, then reference it in later tasks.When authoring Zigflow workflows, the following constraints are mandatory:
document and do.do key must be an array of single-key maps: do: [ { stepName: { task } } ].${ ... }. Strings without this wrapper are treated as literals.{ minutes: 1, seconds: 30 }). ISO 8601 strings (like PT1M) are not supported.document.dsl and document.version must be semantic versions (e.g., 1.0.0).document.taskQueue and document.workflowType must be RFC 1123 DNS labels (letters, digits, and hyphens; must start/end with a letter or digit; no dots, underscores, or spaces).document object is closed; unknown fields are rejected.The workflow definition consists of top-level properties and a specific document metadata object.
Top-level Properties:
document (Required): Workflow metadata.do (Required): Array of single-key step maps.input (Optional): Input configuration and schema.output (Optional): Output configuration and shaping.schedule (Optional): Cron string or every duration. Requires document.metadata.scheduleWorkflowName if used.timeout (Deprecated): Use metadata.activityOptions instead.document Fields:
dsl (Required): Semantic version of the DSL (e.g., 1.0.0).taskQueue (Required): Temporal task queue name (RFC 1123 DNS label).workflowType (Required): Temporal workflow type name (RFC 1123 DNS label).version (Required): Workflow semantic version (e.g., 0.0.1).title (Optional): Human-readable title.summary (Optional): Markdown summary.tags (Optional): Key/value string map.metadata (Optional): Open object for additional config like activityOptions.Durations must be defined as an object with one or more plural integer keys. ISO 8601 strings (e.g., PT1M) and singular keys (e.g., minute) are not supported.
Supported Keys:
dayshoursminutessecondsmillisecondsActivity timeouts and retry policies are configured under metadata.activityOptions.
# Correct duration format
metadata:
activityOptions:
timeout: { minutes: 1, seconds: 30 }Zigflow provides six specific workflow-state variables available within ${ ... } expressions. Referencing any other variable will cause a compilation failure:
$context: Data exported by earlier tasks via the export property.$data: Internal workflow and execution state (metadata).$env: Environment variables. Only variables starting with the configured prefix (default ZIGGY_) are exposed, with the prefix stripped (e.g., ZIGGY_API_URL becomes $env.API_URL). The prefix is configurable via --env-prefix.$input: The original input provided by the caller (immutable).$output: The current output value.$propagated: Read-only values received via Temporal context propagation (from the zigflow.propagated header).document metadata and a do list of tasks. The document object must include dsl, taskQueue, workflowType, and version.document:
dsl: 1.0.0
taskQueue: zigflow
workflowType: hello-world
version: 0.0.1
title: Hello World
summary: Hello world with Zigflow
do:
- hello:
output:
as:
data: ${ . }
set:
message: Hello from ZiggyZigflow provides a read-only Model Context Protocol (MCP) server at https://mcp.zigflow.dev for AI assistants. Available tools include:
get_schema: Retrieves the JSON or YAML schema. Use def to get a specific definition (e.g., { "def": "taskList" }).list_examples: Lists bundled example workflows.get_example: Retrieves a specific example workflow by name.validate_workflow: Validates a YAML string and returns structured errors and warnings.call task with the value http. You must specify the method and the endpoint within the with block. The output format defaults to content but can be set to raw or response.do:
- getUser:
call: http
with:
method: get
endpoint: https://jsonplaceholder.typicode.com/users/3Zigflow supports exactly 11 task types. Each step in the do list must contain exactly one of these keys:
| Task Key | Purpose |
|---|---|
call | Invoke an activity, gRPC service, or HTTP endpoint. |
do | Run a nested sequence of sub-tasks. |
for | Iterate over a collection. |
fork | Run multiple branches concurrently. |
listen | Wait for and react to an event (e.g., signal). |
raise | Raise a workflow error. |
run | Run a script, shell command, container, or child workflow. |
set | Set data on the workflow state. |
switch | Branch based on data conditions. |
try | Run sub-tasks with a catch block. |
wait | Pause for a duration or until a timestamp. |
Common Task Properties:
Every task can optionally include: if (condition), input, output, export, then, and metadata. Note: There is no task-level timeout field.
A task's then property determines the next step in the workflow. Valid values include:
continue: The default behavior.exit: Exits the workflow.end: Ends the workflow.[taskName]: Jumps to another task in the same scope.Tokens such as goto, next, stop, fail, or return are invalid.