Define a workflow in JSON

Use this when you want a new workflow on the server. A workflow is plain JSON: a list of steps (nodes) and a list of arrows between them (edges), stored inside a session. Prerequisites: a running server. If it uses API keys, add -H "X-API-Key: $YUKTA_API_KEY" to every curl.

Steps

Pick a trigger

A trigger starts the run. API_TRIGGER emits the payload of the start request, SCHEDULE_TRIGGER ticks on a timer (Schedule a workflow) and CONSTANT_SOURCE emits fixed values.

Add processors

Chain the plugins that fetch, transform, route or decide. The type string is used exactly as listed in the plugin reference. To see the options, ports and defaults of one plugin, ask the server:

curl -s localhost:9858/api/plugins/MAPPER

End every path with a terminal

Every path must reach a terminal, such as CONSOLE_TERMINAL. A workflow with no terminal is refused.

Write it down

Save this as session.json. It builds a greeting from the start payload:

session.json

{
  "sessionId": "demo",
  "name": "Demo",
  "description": "Greet a user",
  "initiator": "docs",
  "projectPath": "/tmp",
  "workflows": {
    "greet": {
      "workflowId": "greet",
      "description": "Build a greeting",
      "nodes": [
        { "nodeId": "trigger", "type": "API_TRIGGER", "config": {} },
        { "nodeId": "map", "type": "MAPPER",
          "config": { "mode": "PROJECTION", "mapping": { "greeting": "'Hello, ' + payload.name" } } },
        { "nodeId": "end", "type": "CONSOLE_TERMINAL", "config": {} }
      ],
      "edges": [
        { "source": "trigger", "target": "map" },
        { "source": "map", "target": "end" }
      ]
    }
  }
}

The fields are in the Workflow JSON reference. Only the node’s engine object is read by the server (retries, error routing, time limits: Node options); everything else in config belongs to the plugin.

Check it, then apply it

The check takes one workflow (the object under workflows) and stores nothing; see Validate and roll back. Applying runs the same checks, so an invalid definition is never stored.

curl -X POST localhost:9858/api/sessions -H 'Content-Type: application/json' -d @session.json

Applying replaces the whole session with the same sessionId: workflows you leave out are removed. To edit, read it with GET /api/sessions/demo/config, change it and send it back.

Start a run

curl -s -X POST localhost:9858/api/workflow/start -H 'Content-Type: application/json' \
  -d '{"sessionId":"demo","workflowId":"greet","payload":{"name":"Ada"}}'

The answer is 202 with the new executionId.

Verify it worked

curl -s -H 'Accept: application/json' localhost:9858/api/sessions/demo/executions/$EXEC/results

$EXEC is the executionId from the start call. The answer has "status": "SUCCESS" and a RESULT event from node end whose payload is {"greeting": "Hello, Ada"}. If the apply call answers 400, its message names the node and the option at fault.

Variations

No input needed. Start from CONSTANT_SOURCE instead of API_TRIGGER.
Group nodes in the UI. Give nodes a group, or share an id prefix before the first dot (lint, lint.fail); display only.
Use the CLI or the web UI. yukta-cli session apply session.json (CLI reference); the web UI renders a form from each plugin’s options and previews the graph.
Limits. 500 nodes and 2000 edges per workflow; names and ids up to 256 characters. The newest 20 versions of a workflow are kept.

Route and branch to send messages down different paths.
Use variables and expressions to read message data and secrets in config.
Sessions and workflows for how the pieces relate.

Build workflows

Work with AI

Supervise runs

Run and operate

Extend

Define a workflow in JSON

Steps

Verify it worked

Variations

Steps

Verify it worked

Variations

Related