Workflows

A Workflow is an executable block-graph that runs alongside Process Flows — a HITL gate, an approval routing, a multi-step automation. The Workflow Authoring SDK lets you ship workflows inside the same .scrydon-extension.tar.gz archive as your Process Flow, so a single upload installs the ontology, every workflow the flow needs, and the flow itself in one atomic transaction.

When to use this SDK

Use the Workflow Authoring SDK when:

• A Process Flow you ship has an action of actionType: "workflow" and you want the workflow to live in the same Extension (so re-importing the extension also refreshes the workflow).
• You're building a demo / starter Extension and don't want to require operators to wire up workflows by hand after install.
• You want extension-level idempotency — re-uploading the same .scrydon-extension.tar.gz updates the workflow rows in place.

If the workflow already exists in your tenant (system workflow or hand-authored), keep using actionType: "workflow" + workflowId on the action template — no Extension changes needed.

Install

bun add -d @scrydon/sdk-authoring zod

npm install --save-dev @scrydon/sdk-authoring zod

import {
  defineWorkflow,
  defineBlock,
  defineEdge,
} from '@scrydon/sdk-authoring/workflows'

Anatomy of a workflow

A complete example — HITL gate

This example mirrors the HITL gate that PR #1208 demos: a single human-in-the-loop block that gates the transition from Realize → Deploy. The Process Flow (next section) references it by slug.

import { defineWorkflow } from '@scrydon/sdk-authoring/workflows'

export const realizeGate = defineWorkflow({
  slug: 'hitl-realize-gate',
  name: 'HITL — Realize → Deploy Gate',
  description: 'Approval gate before transitioning from Realize to Deploy.',
  version: '1.0.0',
  definition: {
    blocks: {
      'block-start': {
        id: 'block-start',
        type: 'starter',
        name: 'Start',
        position: { x: 0, y: 0 },
        subBlocks: {},
        outputs: {},
        enabled: true,
      },
      'block-hitl': {
        id: 'block-hitl',
        type: 'human_in_the_loop',
        name: 'Realize → Deploy Gate',
        position: { x: 240, y: 0 },
        subBlocks: {
          reviewerRole: {
            id: 'reviewerRole',
            type: 'short-input',
            value: 'admin',
          },
          resolutionMode: {
            id: 'resolutionMode',
            type: 'dropdown',
            value: 'first_claim',
          },
        },
        outputs: {
          approved: 'boolean',
          notes: 'string',
        },
        enabled: true,
      },
    },
    edges: [
      { id: 'edge-start-hitl', source: 'block-start', target: 'block-hitl' },
    ],
    loops: {},
    parallels: {},
  },
})

defineWorkflow, defineBlock, and defineEdge are identity functions at runtime — they narrow types so your IDE catches a missing field or a typo before the build ever runs.

The slug-rebind contract

Inside an Extension, workflows and Process Flows are decoupled through an extension-local slug. The Process Flow references a workflow by workflowSlug; the extension importer materializes the workflow into the tenant, gets a real workflow id back, and rebinds the action template:

// In the Process Flow:
defineAction({
  name: 'Realize → Deploy gate',
  actionType: 'workflow',
  isRequired: true,
  workflowSlug: 'hitl-realize-gate',   // ← references the workflow by extension-local slug
})

The importer walks the manifest, looks up hitl-realize-gate in the resolved slug → id map produced by the workflow install phase, and mutates the action template in-place: workflowId is set to the materialized id and workflowSlug is cleared. From that point on the action behaves like any other workflow action.

A slug the Process Flow template declares inline in its own workflows[] list is not rebound: the action keeps its workflowSlug, and every run materializes its own copy of that workflow. An inline declaration takes precedence over a workflow-<slug>/ subdir with the same slug. Both upload paths (Settings → Extensions and POST /api/extensions/import) accept the same archives.

If the slug doesn't resolve (the template doesn't declare it inline, the extension didn't ship a workflow-<slug>/ subdir for it, or the manifest inside named something else), the install fails fast with UNKNOWN_WORKFLOW_SLUG. Likewise, two workflow subdirs claiming the same slug fail with DUPLICATE_WORKFLOW_SLUG.

Packaging into an Extension

An Extension may carry an ontology, one Process Flow, and zero or more workflows. Each workflow lives in its own workflow-<slug>/ subdir with a manifest.json produced from defineWorkflow. The top-level extension.json lists every workflow as a separate contents[] entry:

import { defineExtension } from '@scrydon/sdk-authoring/extensions'

export default defineExtension({
  manifestVersion: 1,
  package: {
    id: 'sap-activate-brabant',
    name: 'SAP Activate (Brabant)',
    version: '1.0.0',
  },
  contents: [
    { kind: 'ontology',     path: 'ontology',             version: '1.0.0', required: true },
    { kind: 'workflow',     path: 'workflow-hitl-gate',   version: '1.0.0', required: true },
    { kind: 'process-flow', path: 'process-flow',         version: '1.0.0', required: true },
  ],
  installOrder: ['ontology', 'workflow', 'process-flow'],
  metadata: { isSystemExtension: false, isDemoExtension: true, tags: ['sap-activate'] },
})

A few rules the bundler enforces:

• ontology and process-flow are singletons — each may appear at most once. workflow may repeat.
• contents[].path must be unique across all entries.
• installOrder is a permutation of the distinct kinds in contents[] — a single "workflow" entry covers every workflow subdir; they all run in the workflow phase, before process-flow so the slug map is populated when the process-flow rebind runs.

Extension layout

<extension>.scrydon-extension.tar.gz
├── extension.json                          # ExtensionArchiveManifestSchema (lists every subdir)
├── ontology/
│   └── manifest.json                  # OntologyManifestSchema — may be empty
├── workflow-hitl-gate/
│   └── manifest.json                  # WorkflowManifestSchema (one per workflow)
├── workflow-cutover-gate/
│   └── manifest.json                  # (optional — extensions may ship many workflows)
└── process-flow/
    ├── manifest.json                  # ProcessFlowManifestSchema
    └── assets/                        # optional — JSON / image assets

The extension inspector validates each subdir's manifest against its own Zod schema. Workflow manifests round-trip as standalone JSON — you can validate one in isolation with bunx @scrydon/sdk-authoring extension validate against a workflow manifest.json.

Block validation rules

WorkflowDefinitionSchema enforces two structural invariants beyond the per-field types:

Block type is intentionally an open string — the runtime block catalog (starter, human_in_the_loop, every extension block, …) evolves independently of the SDK and the schema doesn't lock to a snapshot. Same for sub-block type: the value is preserved verbatim and surfaced to the editor.

Block references are checked too

Those two rules cover the edge graph — how control flows. The other half is the <blockName.field> references inside sub-block values — and inside a loop's forEachItems, whileCondition and doWhileCondition — which is how data flows. They are checked in every workflow your extension ships: the workflows of a workflow manifest and the inline template.workflows of a process flow. Every command that produces a shippable extension resolves every one of them: extension validate, extension build, build-dist and build-source. Errors fail the command and are reported all at once, so a workflow with several bad references takes one run to fix, not one run each. Warnings print to stderr and never change the exit code.

A reference names a block by its name, lowercased with spaces removed — never by its id:

defineBlock({ id: 'block-intake-webhook', name: 'Report', /* … */ })
// reads as <report.body.subject>   ✅  the name, normalized
// NOT      <block-intake-webhook.body.subject>   ❌  the id never resolves

Names are not limited to ASCII: a block named Résumé is read as <résumé.content> and is checked like any other. A field segment may contain a hyphen — <api.headers.content-type> reads the content-type key. An array element is read by its position, written either [0] or .0: <api.data.users[0].name> and <api.data.users.0.name> are the same reference, and both are checked. Only a number goes in the brackets — <api.data[key]> is not a reference.

The three runtime roots are scoped, not blanket-accepted

start, loop and variable name no block, so they are resolved against what the runtime actually provides rather than against blocks:

Two shapes are deliberately not checked, because both are ordinary authored text that the runtime also leaves alone: a reference with no .field segment (<announcement> — indistinguishable from the HTML tag <div>), and anything that starts with a space, is a number, or contains an operator, @, : or / (a < b && c > d, <0.5>, <someone@example.com>). A name may start with digits as long as a letter follows them directly: a block named 2FA check, read as <2facheck.result>, is checked like any other, while <0.5> and <1.2.3> stay text.

Migration note — new build errors

Extensions that built cleanly before this check can now fail extension build / extension validate with workflow_reference_unresolvable. Each of these already produced a wrong value at runtime — the literal reference text — so the build is reporting an existing defect, not introducing one. For the same reason the check ships in a minor release of @scrydon/sdk-authoring, not a major one; pin the previous version if a build has to stay green while you fix the references it reports.

The same checks now cover a loop's forEachItems / conditions and a process flow's inline template.workflows, so an extension whose workflow subdirs were already clean can still find new errors there.

Already-published extensions keep installing. Importing an archive (the upload preview under Settings → Platform → Extensions → Sources → Upload an extension, the /api/extensions/import API, and extension inspect) runs the same checks but reports every finding as a warning — an unresolvable root keeps the workflow_reference_unresolvable code, advisory findings use workflow_reference_advisory — and never blocks the install. Rebuild the extension to see them as errors and fix them.

Human-in-the-Loop gates

Every human_in_the_loop block is inspected when the extension is built, when it is imported, and when the workflow is deployed — from the canvas, Monitor, an automation, a promotion, or POST /api/v1/workflows/{id}/deploy. Three findings block, three advise. Every blocking finding blocks at build, at import and at deploy alike: an extension built before these checks existed is refused until its gate is fixed and the extension is rebuilt. Each warning is returned as hitlWarnings at deploy and shown next to the success message. A rollback to an earlier version reports its findings as warnings instead of refusing, because that version already ran.

The reserved names are approved, decision, reason, verdict, responses, aggregate, submission, response, url and option. You do not need a field for the decision itself — approving or rejecting is the decision, and it is readable downstream as <gate.verdict> (and <gate.approved>). The form is for what the envelope does not already carry.

Decision options

A gate that needs more than approve / reject declares its ballot in the decisionOptions sub-block. Each option maps to an outcome class — approve counts toward the required approvals, reject is a refusal, other is neither — and there are no weights. Either the editor's table rows or plain objects are accepted:

decisionOptions: {
  id: 'decisionOptions',
  type: 'table',
  value: [
    { value: 'go', label: 'Go', outcome: 'approve' },
    { value: 'no_go', label: 'No go', outcome: 'reject' },
    { value: 'defer', label: 'Defer', outcome: 'other' },
  ],
},

Downstream blocks read <gate.verdict> (approve · reject · undecided), <gate.aggregate.byOption.go> (a count per option, 0 included) and — on a single sign-off gate — <gate.option>. The resume API and A2A accept only a declared value, submitted as option; anything else is refused with HTTP 400 and not recorded. See Human in the Loop → Decision options for how each rule releases.

AI blocks and the model field

Core AI blocks (agent, router, evaluator, translate) have a required model field, but extension-authored workflows should leave it empty. Hardcoding a model would tie your extension to a vendor the installing organization may not have enabled. When the model sub-block is empty at execution time, the platform resolves the organization's default LLM extension (the one configured under Settings → Agentic → Default LLM Extension) and uses its model. If the organization has no default LLM configured, the run fails with <block name> is missing required fields: Model — configuring a default LLM extension resolves it.

Manifest version

Workflow manifests carry manifestVersion: 1. The build-time extractor injects this so authors don't have to.

The schema rejects:

Build, inspect, upload

bunx @scrydon/sdk-authoring extension build src/extension.ts --outDir dist
# → dist/<package.id>-<package.version>.scrydon-extension.tar.gz

bunx @scrydon/sdk-authoring extension inspect dist/sap-activate-brabant-1.0.0.scrydon-extension.tar.gz

curl -X POST "$AGENTIC_URL/api/extensions/import?organizationId=$ORG_ID&workspaceEnvironmentId=$ENV_ID" \
  -H "Cookie: $SESSION_COOKIE" \
  -F "file=@dist/sap-activate-brabant-1.0.0.scrydon-extension.tar.gz"

Idempotency

The materialized workflow row id is derived as extension:<packageId>:<slug>:<workspaceEnvironmentId>. Re-uploading the same Extension to the same workspace environment finds the existing row and (when replacePublished: true is passed) deletes + re-inserts it — workflow_blocks, workflow_edges, and workflow_subflows cascade. Different environment ids produce different rows, so the same extension can be installed side-by-side across dev / staging / prod environments.

workflow.variables is stored as Record<string, Variable> keyed by variable id. The materializer attaches the resolved workflowId to each variable on insert; authored entries omit it.

Where to next