Action Types

An Action Template is the thing a Task asks someone (or the system) to do. A Task can carry one or many actions; they render side-by-side in the task detail panel and complete independently. Picking the right actionType is the most consequential authoring decision in a Process Template — it determines what the assignee sees, what data the platform records, and which downstream gates and integrations fire. When a Task carries exactly one action, the kanban board shows that action's type chip (icon + color) directly on the task card — single-action tasks read as "the task is the action" at a glance.

This page expands on the summary table on the Process Flows overview — one section per type, with a copy-pasteable example pulled from a real pack in the SDK examples, and a one-line note on what the assignee actually sees in agentic.

Anatomy of an action

Every action shares the same envelope, regardless of type:

import { defineAction } from '@scrydon/sdk-authoring/process-templates'

defineAction({
  name: 'Approve rollout plan',                  // required, 1–200 chars
  description: 'Sign off on the customer rollout schedule.',
  actionType: 'approval',                        // required, see below
  isRequired: true,                              // required — drives gate completion
  executionMode: 'manual',                       // optional — see below
  dueOffsetDays: 5,                              // optional — relative due date
  metadata: { persona: 'champion' },             // optional — per-type config bag
  // workflowId / workflowSlug only used by actionType: 'workflow' — mutually exclusive
})

The fields that vary per type all live on metadata. Each section below calls out the metadata keys that the runtime reads for that specific type.

executionMode

A single optional field controls when an action runs:

Pick manual whenever a human is the principal. Pick automatic when the platform should drive the step the moment it can. Pick on_entry only when the step must run before the stage is interactable.

checklist

The lightest-weight action. The assignee sees a single button labeled "Mark complete" and clicks it when done. No artifact, no metadata captured beyond the completion event itself.

Use for: confirmations, attestations, "I did X" acknowledgements where the audit trail just needs the actor and the timestamp.

Schema fields used: name, description, isRequired, executionMode, metadata.persona.

Example (from the NATO multi-source detection pack — an operator confirms a sensor flag):

defineAction({
  name: 'Confirm UAV detection',
  description: 'Sensor operator confirms UAV radar reading and flags the track for fusion.',
  actionType: 'checklist',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'operator' },
})

What the assignee sees: a card titled "Confirm UAV detection" with a single primary button. Completion writes an action_completed activity-log entry tagged with the actor's id.

document

A long-form text artifact the assignee must produce. The platform opens a markdown editor inside the task; the resulting page is stored in the instance's workspace knowledgebase and indexed for retrieval by downstream AI steps.

Use for: plans, summaries, write-ups, meeting agendas, minutes — anything where the content is the deliverable, not a file.

Schema fields used: name, description, isRequired, executionMode, metadata.persona, metadata.promoteToCorpus (optional — one of summary / minutes / decisions / action-items; when the stage completes, the document is additionally published to the instance KB's instances/<instance>/canonical/ folder under that slug, where downstream KB-promotion steps look for it).

Example (from the AI Boardroom template — the secretary drafts the agenda):

defineAction({
  name: 'Create meeting agenda',
  actionType: 'document',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'secretary' },
})

What the assignee sees: a card titled "Create meeting agenda" with an "Open editor" button. Completion is implicit — the action is considered done once the page is saved with non-empty content.

Where the document lands: while being edited, the content lives on the action itself. When the action is marked completed, the platform converts it to Markdown and writes it as a real page in the process flow's instance knowledge base, under instances/<instance>/documents/<stage>/ with the action's name as the page title. Completing the action again after edits updates the same page in place. From there it is queryable via the instance's KB and can ground later actionType: "workflow" steps via metadata.retrieval. Process flows created before instance knowledge bases existed get one provisioned automatically the first time a document, transcript, or canonical page is written.

approval

A sign-off gate. The assigned persona sees an Approve / Reject pair of buttons. Approving marks the action complete and unblocks downstream tasks; rejecting flags the task and surfaces a reason field.

Use for: stage-gate sign-offs, go/no-go decisions, governance reviews where someone with named authority must vouch for the result.

Schema fields used: name, description, isRequired, executionMode, metadata.persona, metadata.promoteToOrgKb (boolean — completes the workspace-KB → org-KB learnings condense; only valid on approval).

Example (from the AI Boardroom template — executive sign-off on the AI-drafted summary):

defineAction({
  name: 'Approve meeting summary',
  actionType: 'approval',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'executive' },
})

What the assignee sees: a card with Approve and Reject buttons. Approval writes an approval_granted activity entry; rejection writes approval_rejected with an optional reason and leaves the task open.

workflow

Executes a Scrydon workflow — either an agentic AI agent, an integration block sequence, or a human-in-the-loop gate. The workflow runs in the platform's workflow engine; the action completes when the workflow returns.

Use for: AI agent steps, automated integrations, HITL gates that need richer than a yes/no — anything where executable logic must run as part of the flow.

Schema fields used: name, description, isRequired, executionMode (often automatic), workflowId or workflowSlug (mutually exclusive), metadata.aiAgent, metadata.retrieval, metadata.outputSurface.

There are two ways to reference the workflow, and choosing between them is the key authoring decision for this type:

By workflowId — refer to an existing workflow

Use this when the workflow already exists in the tenant. Two common cases: a @system/* agent shipped by the platform, or a workflow the workspace built independently.

Example (from the NATO sense stage — calling the system-provided multi-source detector):

defineAction({
  name: 'Run UAV radar detection',
  actionType: 'workflow',
  isRequired: true,
  executionMode: 'automatic',
  workflowId: '@system/agent-multi-source-detector',
  metadata: { persona: 'ai-platform', aiAgent: 'multi-source-detector' },
})

The runtime treats @system/* ids specially — they always resolve, regardless of which workspace the instance runs in.

By workflowSlug — ship the workflow inside the same pack

Use this when the workflow is bespoke to the process and you want them to ship as one atomic unit. Author the workflow alongside the process template in the same .scrydon-pack.tar.gz; the importer materializes the workflow first, then rebinds every workflowSlug to the materialized id before the process template lands.

Example (from the SAP Activate Brabant pack — a HITL gate shipped with the template):

defineAction({
  name: 'Realize → Deploy Gate (HITL)',
  actionType: 'workflow',
  isRequired: true,
  executionMode: 'manual',
  workflowSlug: 'hitl-realize-gate',  // resolved at install time
})

workflowId and workflowSlug are mutually exclusive — the Zod refinement rejects an action that sets both. See Workflows for the slug-rebind contract.

What the assignee sees: if executionMode is automatic or on_entry, usually nothing — the step runs in the background and shows its result inline once it lands. If manual, a "Run" button appears; clicking it starts the workflow and streams progress into the card.

Where AI output lands

When a workflow action runs a @system/ agent and declares an outputSurface, its result is saved in three places:

1. The action itself — structured verdict (verdict, confidence, rationale, cited learning titles) plus a rendered Markdown copy.
2. The instance knowledge base — a page under instances/<instance>/assessments/<stage>/, written automatically on completion. This page is the source of truth: the View output button on the action opens it inline. The page's clearance level is capped at the high-water-mark of the sources that informed it, so readers below that clearance see a denial instead of the content.
3. A sibling approval action (only when the flow declares the approval output surface) — an advisory banner on the human decision gate.

Re-running the action updates the same page in place. The Run Details panel on the action shows the execution envelope (workflow id, execution id, status, timestamps) and the raw stored payloads for debugging.

entity_link

The intent is to attach a task to a typed Object instance from the ontology — so the action becomes "fill in this Object" rather than "produce a free-form artifact." The Object Type would be declared via task.ontologyContract.writes (or the action's ontologyContract), and the runtime would scaffold an editor for that type's properties.

Schema fields used: name, description, isRequired, executionMode, ontologyContract (declared at the action or task level).

file_upload

The assignee uploads one or more files. Bytes flow into the instance's workspace knowledgebase, get hashed and stored via @scrydon/storage, and are immediately indexed — making them available to downstream actionType: "workflow" steps via metadata.retrieval.inputs[].fromTask.

Use for: importing source documents (RFPs, contracts, board packs, audit evidence) that downstream AI steps need to reason over.

Schema fields used: name, description, isRequired, executionMode, metadata.persona, and the optional drop-zone constraints metadata.acceptedExtensions, metadata.acceptedMimeTypes, metadata.maxSizeMb.

Constraining what can be uploaded. A file_upload step always accepts multiple files; you cannot turn multiplicity off. What you can declare is which files and how large:

All three are optional. Declare none and the step falls back to the platform defaults: extensions .pdf .docx .xlsx .csv .pptx .txt .md, max size 50 MB. Declaring acceptedExtensions or acceptedMimeTypes replaces the default extension set, so you can gate purely by MIME if you prefer.

These limits are enforced both in the picker (the drop-zone's accept filter and size check) and server-side at upload — a request that bypasses the UI is still rejected with a 400. Existing in-flight instances keep the defaults; the constraints take effect for flows instantiated after the template declares them.

Example (from the AI Boardroom template — secretary uploads the board pack):

defineAction({
  name: 'Upload board documents',
  actionType: 'file_upload',
  isRequired: true,
  executionMode: 'manual',
  metadata: {
    persona: 'secretary',
    // Optional — omit for the platform defaults (.pdf/.docx/.xlsx/.csv/.pptx/.txt/.md, 50 MB).
    acceptedExtensions: ['.pdf', '.docx', '.pptx'],
    acceptedMimeTypes: ['application/pdf'],
    maxSizeMb: 25,
  },
})

What the assignee sees: a drop-zone card that accepts multiple files — select several at once or keep adding files over time (each upload appends to the step's attachment list; existing files are never replaced). The picker only offers the accepted types and rejects files over the size cap. Completion is explicit: once at least one file is attached, the assignee marks the step complete (the Mark step complete button on the card, or the action's checkbox in the task checklist). Each file becomes a KB page that downstream tasks can reference by this task's slug.

distribution

Sends a message to the holders of one or more personas and tracks acknowledgment. Used to broadcast a result, request acknowledgment before a tabletop, or close a loop with stakeholders who aren't actively running the flow.

Delivery today runs over email through the platform mailer — no integration setup is required. channel: "slack" and channel: "teams" are accepted in the manifest as declared intent, but delivery for those channels will be enabled in a future release; until then the panel shows the declared channel and disables sending for non-email channels.

Use for: notifications, briefings, summaries pushed to external channels.

Schema fields used: name, description, isRequired, executionMode, plus a richer metadata block:

Example (from the ISO Quarterly Review pack — distributing the audit-ready summary on Slack with a recipient list):

defineAction({
  name: 'Distribute report summary',
  actionType: 'distribution',
  isRequired: true,
  metadata: {
    persona: 'compliance-lead',
    channel: 'slack', // Declared intent — Slack delivery not yet active; email delivers today.
    recipientPersonas: ['compliance-lead', 'ciso', 'dpo', 'eng-owner'],
    completion: 'all-acknowledged',
  },
})

What the assignee sees: a focused panel showing the declared channel, the completion mode, and the resolved recipient list (each recipient persona's assigned users by name). For email, a compose form (subject prefilled from the action name, editable message) sends each recipient a personal tracked link; once sent, the panel shows per-recipient acknowledgment status and an "N of M acknowledged" progress line for all-acknowledged / quorum modes. Recipients acknowledge by opening the tracked link, which also redirects them to the linked artifact.

voice_trigger

Captures audio against a path defined on the template. The recording is automatically transcribed (STT runs through the STT capability). When the action completes, the transcript is written as a page in the process flow's instance KB under instances/<instance>/transcripts/<stage>/, and the raw audio is queued for ingestion under instances/<instance>/audio/<stage>/ — both ready to ground downstream steps.

Use for: meeting recordings, dictation, voice-driven enrichment of a flow that's mostly silent the rest of the time.

Schema fields used: name, description, isRequired, executionMode, metadata.persona, metadata.triggerPath (matches a path on a top-level template.voiceTriggers[] entry).

Example (from the AI Boardroom template — recording the meeting itself, paired with a top-level voice-trigger that wires up STT and downstream enrichment):

// On the task action:
defineAction({
  name: 'Record meeting',
  actionType: 'voice_trigger',
  isRequired: true,
  executionMode: 'manual',
  metadata: { persona: 'secretary', triggerPath: 'board-meeting' },
})

// On the top-level template:
defineVoiceTrigger({
  path: 'board-meeting',
  sttProvider: 'openai',
  language: 'en',
  enrichments: [
    { workflowId: '@system/agent-meeting-summarizer' },
  ],
})

What the assignee sees: a card with a record button. Recording in the browser; on stop, the audio uploads and the STT result streams in. Enrichment workflows on the voice-trigger fire automatically once the transcript lands.

Choosing the right type

A short decision flow for when authors are unsure:

If the step is "fill in a typed Object," there isn't a first-class action type yet — model it as a workflow action that calls an agent or integration block to create the instance via the ontology API.

Common validation pitfalls

The pack validate command runs the Zod schema and rejects manifests that violate these rules. The ones that bite most often:

Where to next