The workflow file

A workflow is a JSON file at workflows/<id>.json. The id matches the file name without .json. You'll usually edit workflows through the visual Workflow Editor; this page documents the file it writes.

Minimal example

A fresh workflow from zeon new workflow my_workflow:

{
  "workflow_id": "my_workflow",
  "name": "my_workflow",
  "description": "",
  "version": "1.0.0",
  "author": "",
  "created_at": "2026-05-24T12:00:00.000Z",
  "updated_at": "2026-05-24T12:00:00.000Z",
  "simulation_validated": false,
  "objects": [],
  "inputs": [],
  "nodes": [
    { "node_id": "start", "type": "start", "label": "Start" },
    { "node_id": "end",   "type": "end",   "label": "End"   }
  ],
  "edges": [
    {
      "edge_id": "e0",
      "from_node": "start",
      "to_node": "end",
      "condition": { "type": "default" }
    }
  ]
}

The two timestamps are stamped by the CLI on your machine when the file is scaffolded, not by a server.

Top-level fields

inputs

Each input is a value supplied before the run starts. A single-input example, from a real workflow:

"inputs": [
  {
    "name": "reaction_plate",
    "type": "object",
    "is_array": false,
    "description": "PCR Wellplate"
  }
]

The five types appear in the editor's dropdown as String, Integer, Float, World Object, and Structured Data.

objects

A list of object declarations the workflow's nodes can reference by alias:

"objects": [
  {
    "alias": "reaction_plate",
    "mesh_type": "wellplate_pcr",
    "display_name": "PCR Wellplate"
  }
]

At execution time each alias is bound to a concrete object in the loaded world. This mechanism predates workflow inputs and is kept for compatibility. New workflows generally declare an object-typed input instead, and leave objects empty. Both work.

nodes

Five node types exist: start, end, skill, loop, and conditional. Every workflow has one start and at least one end.

In practice, most workflows use only start, end, and skill, a linear chain of skill nodes.

The file format and the executor use different names for the same edge conditions. The editor translates between them in both directions as it loads and saves: default becomes unconditional, loop_continue becomes loop_body, and loop_complete becomes loop_exit. (The gateway applies the same mapping one way, when importing older files.) You write the file-format names documented below; the translation is not something you manage.

A skill node:

{
  "node_id": "pick_pipette_1",
  "type": "skill",
  "label": "Pick Epipette",
  "skill_id": "epipette_grey_pick",
  "parameters": {}
}

edges

{
  "edge_id": "e0",
  "from_node": "start_0",
  "to_node": "pick_pipette_1",
  "condition": { "type": "default" }
}

Condition types:

The graph is structurally validated before it runs. A workflow with a node connected to no edges, an edge naming a node that doesn't exist, or a conditional node without exactly two outgoing edges is rejected.

Parameter references

A node's parameter can be:

• A literal: "volume": 5, "well": "A1". Arrays and nested objects are also fine.
• A workflow input reference: { "$input": "reaction_plate" }, resolved at run time to whatever was supplied for that input. For object-typed inputs it may also carry an offset: { "$input": "plate", "offset": { "xyz": [0, 0, 0.01], "wxyz": [1, 0, 0, 0] } }.
• An object reference: { "alias": "reaction_plate", "offset": { "xyz": [0, 0, 0.01], "wxyz": [1, 0, 0, 0] } }, naming an entry in the workflow's objects list.

In both reference forms the offset lets a skill target a pose relative to the object rather than its origin (10 mm above a plate, say). xyz is in metres; wxyz is a quaternion, scalar first.

canvas_ui

Present when a canvas is attached to the workflow:

"canvas_ui": {
  "kind": "react",
  "source_ref": "canvas/my_workflow_screen.tsx",
  "enabled": true,
  "version": 1,
  "updated_at": "2026-05-24T12:00:00.000Z"
}

See Creating a Canvas for how to add one.

See also