Workflows

name: Handle Request
description: Takes a request and answers it.
graph:
  nodes:
    - id: start
      type: trigger_manual
      position: { x: 0, y: 0 }
      data:
        description: An operator starts this workflow from the web app.
    - id: respond
      type: ai_agent
      position: { x: 280, y: 0 }
      data:
        mode: existing
        agent: agents.responder
        agentName: Responder
        inputMappings: []
  edges:
    - id: start-to-respond
      source: start
      target: respond

A Workflow is a graph: nodes (each with an id, a type, a canvas position and type-specific data) and edges connecting them (source → target). It's the same graph the Workflow canvas in Studio edits.

References inside nodes

Wherever Studio stores the id of an Agent, Team, Tool, Knowledge Base or model, the portable form uses a manifest-local reference or a Slot:

Node types

A Workflow can carry all 27 node types of the Studio canvas. Each type below links to its page under Workflows, which describes the panel in Studio, and to its section of Workflow nodes, which lists every field of its data, what travels and what validate and build refuse, with a working example. npx @elizon/cli example workflow --node <type> prints that example inside a complete project.

A Code node's source travels as written and is scanned by validate and build (CODE_NODE_STATIC_SCAN_FLAGGED is a warning; the installing Organization re-scans). A node type that can't be packaged, such as a retired type surviving in an old saved version, is refused (PORTABLE_UNSUPPORTED_NODE_TYPE) with a hint to replace it in Studio. Edges between nodes, and the named handles of if_else, classify and loop, are described under Edges and handles.

Reading another node's output

A node reads an earlier node's output as {{ upstream.<id>.output.<path> }}, where <id> is that node's id in the graph. These rules cover every node type:

• Every reference goes through .output. {{ upstream.<id>.text }} does not exist; {{ upstream.<id>.output.text }} does.
• A path is dots only. A list entry is its index as a segment: output.files.0, never output.files[0].
• A reference to a field the output does not have fails the node that reads it, with a message naming the path. It never resolves to an empty value.
• Except in the nested-Loop case at the end of this item, validate (and so build) checks only code, ai_agent, human_review and data_table nodes: it refuses a reference whose first segment after output is not one of the node's fields below (WORKFLOW_UNKNOWN_OUTPUT_FIELD). The usual case is a Code node's key read without result: {{ upstream.<id>.output.rows }} instead of {{ upstream.<id>.output.result.rows }}. Read after the Loop (outside its body), a Loop-body node's output is only iterations and loopNodeId, and validate checks that too. A node inside a nested Loop's body, read from the enclosing Loop's body (outside its own), has no output yet: validate refuses every {{ upstream.<id>.output… }} reference to it there, for any node type and for the bare {{ upstream.<id>.output }} too.

The fields each node type outputs, as the run records them:

A Note node never runs, so it has no output to read.

Values the installer supplies

Two values are never carried, and are collected at install:

• the approvers of a human-review step (emails),
• the username of a password-protected form trigger (never the password).

The wizard asks for them, and the CLI takes them as --approver.<node-id>=… and --form-user.<node-id>=…. Carried text (notes, prompts, messages) must not name people either: an email address in carried text, such as a sticky note's ask jane@acme.com, fails validate and build with PORTABLE_PERSONAL_DATA_LEAK at the field's path (workflows.<name>.graph.nodes[<i>].data.text). A Code node's source (data.code on a code node) is the one exception: an address-shaped match there, such as x@self.weights or logo@2x.png, is a PORTABLE_MACHINE_CONTENT_EMAIL warning at workflows.<name>.graph.nodes[<i>].data.code and the Package still builds; a person's address in the source must still go. The node's inputExpression is refused as usual. A {{secret.…}} reference anywhere in the file, the source included, fails with PORTABLE_ORG_IDENTIFIER_LEAK. Only the people fields below, and a human-review fallbackAssignedTo (always stripped), are stripped instead. See Carried text.

People fields

A few node fields name who an email goes to: a human-review step's assignedTo, and a Send Email step's to, cc and bcc. One rule covers all of them, and build, validate and install apply the same check:

• A field made only of {{ }} expressions travels as written: it names nobody until a run resolves it. For example {{ loop.item.Contact email }}. Separate several with commas or semicolons; a run splits the resolved value on those, so expressions separated only by spaces resolve to one invalid address.
• Anything else — a literal address, an expression next to a literal, an address inside the braces, a {{secret.…}} reference, or stray text — is stripped by build, which reports a warning naming the node and the field (HUMAN_REVIEW_APPROVER_STRIPPED, SEND_EMAIL_RECIPIENT_STRIPPED). Empty fields are dropped silently.
• An artifact that carries a non-expression people field is refused at install with PORTABLE_PERSONAL_DATA_LEAK (PORTABLE_ORG_IDENTIFIER_LEAK for a secret reference).

A stripped approver is collected at install (above). A stripped Send Email recipient is set on the canvas after install. A Send Email node's SMTP server, login and sender never travel, even when they are expressions.

Workflows and triggers

When a Workflow is the Package's entry point, the manifest's triggers start it. schedule, webhook, email, app and knowledge-document triggers require a Workflow entry point. See Triggers.

A Workflow's graph can also hold several trigger nodes, as it can in Studio: any mix of types, and any number of Manual triggers. A run starts only from the trigger that fired. It can hold at most one Webhook, Form, Email, App and Recurrence trigger node each; validate and build refuse a second one with PORTABLE_DEFINITION_INVALID at that node, the same refusal an install gives. See Several triggers on one workflow.