Create and run workflows

Admin

Workflows are admin-defined, deterministic step pipelines: a fixed sequence of steps that reads data, transforms it and stores results — for example “read the invoice mailbox → extract payment data → a human reviews → write a SEPA file”. They are managed in Administration under Workflows; the area is visible to administrators only. End users have no workflow interface.

Workflow or agent?

An agent works freely: it receives a task and decides on its own which tools to use in which order. A workflow is the opposite — a deterministic pipeline in which every step has a precisely defined input and output and the order is fixed. That makes runs repeatable, auditable and fully logged. The two combine: the step type agent.run tasks an existing agent as one node inside the pipeline. → Agent model

Creating a workflow — three ways

The editor offers three equivalent ways to the same definition; on the right, a read-only SVG pipeline view shows the flow, and the Validate button checks the definition at any time before running.

Way 1: Describe it to the assistant

Type the desired flow into the generator field in natural language (“Read unread mails from the invoice mailbox, extract the payment data and write a SEPA file”) — the assistant generates a draft as a step list. Follow-up prompts refine the existing definition (“insert a review step before the write”). If the assistant ever produces an invalid draft, it lands in the JSON tab together with a list of errors, where it can be corrected by hand.

Way 2: Build it in the step editor

Every step is a card with type and configuration; the order is changed via arrow buttons. In addition:

Inputs — named parameters of the workflow with type, required flag and optional default. They form the form shown on manual start and the expected JSON body of the webhook.
Error behaviour per step — fail (run fails, the default), continue (proceed with the next step) or fallbackStep (jump to a named step); plus optional retries (1–5 attempts with a delay).

Way 3: JSON tab for experts

The JSON tab shows the full definition as JSON and suits copying, templates and details the card editor does not cover. The same validation applies everywhere.

Data between steps

Steps pass data along via placeholders, which may appear in configuration fields:

{{inputs.videoUrl}} — accesses the workflow input videoUrl, e.g. as an argument of an mcp.tool step.
{{steps.extract.output}} — accesses the output of the step with id extract, e.g. as context in the prompt of a later llm.transform step.

Step reference

Type	Purpose
`llm.transform`	Transform text via LLM (polish, translate, extract)
`http.request`	Call a configured HTTP API tool
`file.write`	Write an artifact into the workflow artifact folder
`mail.fetch`	Read a configured mailbox deterministically
`mcp.tool`	Call a tool of a connected MCP server
`agent.run`	Task an existing agent
`review`	Pause the run for human review

`llm.transform`

Transforms input text via LLM — polish, translate or extract structured data (with outputSchema as a JSON schema for machine-readable results). Personal data is pseudonymised by default: the LLM sees placeholders, and the output is re-identified for the following steps. The bypassPii switch lifts that for the individual step and is recorded in the PII audit log. Configuration: prompt, optionally model and outputSchema. → PII shield

`http.request`

Calls an HTTP API tool created under Configured tools and inherits its complete security setup (base URL, authentication, allowed endpoints). Configuration: toolRef (the tool’s slug), method, args. Calls with write effect count as write steps (see dry run). → Set up an HTTP API tool

`file.write`

Writes an artifact — such as a generated XML or text file — into the workflow artifact folder (see Limits & operations); paths outside the artifact folder are rejected. Configuration: path (relative), content.

`mail.fetch`

Reads a mailbox created under Configured tools deterministically, with no LLM involved. Configuration: toolRef (the mailbox tool’s slug), optionally folder, senderFilter, subjectFilter, unreadOnly (default: on), maxItems, downloadAttachments (attachments land in the run’s subfolder of the artifact folder). The options markAsRead and archiveFolder prevent scheduled runs from processing the same mails twice. → Set up a mailbox tool

`mcp.tool`

Calls a tool of a connected MCP server with fixed arguments — e.g. fetching a YouTube transcript. Configuration: tool (tool name), args, plus the read-only call checkbox (intent: read): it declares the call as reading, so it executes for real during a dry run; without the checkbox the call counts as a write step. → Connect an MCP server

`agent.run`

Tasks an existing agent with a prompt and waits for its result. The agent works within its own tool allow-list and middleware (PII, dry run, timeout); its run is linked from the workflow timeline. Configuration: agentId, prompt, optionally timeoutSeconds and scopeOverride. → Create an agent and test it in a dry run

Override scope (scopeOverride): a JSON object whose fields replace the same fields of the agent’s source — all others stay as set on the agent page. Example: {"item": "{{steps.s1.output.file}}"} makes a working-folder or vault agent read exactly that one file; the folder stays the configured one. A single binding that yields an object works too. If the value is not an object, the step fails with the reason before the agent starts.
Feed folder sources, don’t poll them: a workflow run marks nothing as processed and moves no files; “Only new files” is off when the scope is overridden, unless the override sets onlyNew itself. Name the input explicitly through scopeOverride. → Chain agents
One run per step: even an agent with “One run per file” or “One run per mail” runs exactly once in a workflow.
Pass the result on: the step returns {agentRunId, status, summary, result}. result holds the agent’s JSON result (result schema on the agent page) — later steps bind single fields with {{steps.<id>.output.result.<field>}}. Without a result schema result is empty; use {{steps.<id>.output.summary}} instead. result is filled in a dry run as well.
Workflow from a description: the generator knows the existing agents and their result fields and builds such chains itself, e.g. “Read invoice X with the Invoices agent and write the amount into a file”.
Note: workflows are reserved for administrators. An overridden scope can point an agent at any vault folder, mailbox or (desktop) disk folder; vault permissions apply through the “Run-as user”. The working-folder source exists only in the desktop app.

`review`

Pauses the run and presents it to an administrator for review — see Resolving review steps. Useful immediately before write steps when an LLM extracted or generated something beforehand.

Safety markers in the editor

The editor marks risky constellations directly on the step cards:

Yellow frame/chip — the step bypasses the PII shield (bypassPii). Personal data leaves the system unpseudonymised; every such call is audited.
Blue chip — write step: the step changes something outside the workflow (a file, an HTTP write call, a writing MCP tool).
Red warning — PII bypass combined with a non-EU provider: personal data would go to a provider outside the EU unpseudonymised. Response: remove the bypass, assign the step a model from an EU provider — or accept the constellation deliberately and documented. → Data sovereignty

Running and monitoring

Manual start: the start button opens a form generated from the defined inputs (required fields, defaults).
Dry run: the recommended first test of every workflow. Read steps run for real; write steps are not executed but only logged as a DryRunSuppressed event — including what would have been written. Review steps are skipped (their review payload lands in the log).
Run list: every run appears with a status badge — Running, Waiting for review, Succeeded, Failed, Cancelled — along with trigger mode and duration.
Timeline: a run’s detail view shows start, end, attempts and an output excerpt per step as a sequence of events with colour dots. For agent.run steps the agent run is linked directly.
Cancel: a running or waiting run can be cancelled at any time.

Resolving review steps (human-in-the-loop)

When a run reaches a review step, it pauses with status Waiting for review. Administrators see a badge on the Workflows tile in Administration and a banner in the Workflows area; in addition an email notification goes out to the administrators (via the configured SMTP connection). A paused run survives an app or server restart — it waits until someone decides.

The review panel presents the data under review as a form (for structured results), a JSON view or a preview. Actions:

Approve — the run continues; optionally correct individual values first (the corrections overwrite the reviewed step’s result).
Re-run with a note — repeats the reviewed step with the note as an additional instruction, at most 3 times per review; only available for generative, repeatable step types (the current version has no such type yet — the action appears with future generative steps, e.g. image generation).
Cancel — the run ends with status Cancelled.

Triggers: schedule and webhook

The trigger tab only appears for saved workflows. Regardless of the trigger: per workflow, at most one run executes at a time.

Schedule (cron)

A cron expression in UTC (e.g. 0 6 * * 1-5 = weekdays 06:00 UTC) starts the workflow automatically; the tab shows the next run, and an active toggle pauses the schedule without deleting it. Cron syntax matches agent triggers. → Set up a cron trigger

Webhook

External systems (e.g. your own n8n, a Git server, a form backend) start the workflow via HTTP:

Generate a token on the trigger tab. It is shown exactly once — copy it to a password manager immediately; only a hash is stored.

Set up the call: POST /api/workflows/{id}/trigger with the token in the X-Workflow-Token header and the workflow inputs as the JSON body:

curl -X POST https://cw.example.com/api/workflows/<workflow-id>/trigger \
  -H "X-Workflow-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "videoUrl": "https://www.youtube.com/watch?v=…" }'

Responses: a wrong or missing token yields 401; if a run of the workflow is already executing, the call is rejected with 409 and logged on the running run.

Rotate token generates a new token (again visible only once) and invalidates the old one immediately — all callers must be updated.

Limits & operations

One run per workflow: further triggers — manual, schedule or webhook alike — are rejected and logged on the running run.
Schedules require server mode (licence). On the desktop, schedules only run while the app is open — use web/server mode for continuous operation (as with agents). → Web vs. desktop
Artifact storage: file.write and mail attachments land in the folder from the Workflows:ArtifactRoot configuration; the default is Evanto/CompanyWizard/workflow-artifacts inside the local app data directory (macOS: ~/Library/Application Support/…, Windows: %LOCALAPPDATA%\…, Linux: ~/.local/share/…). Attachments are stored per run in a run-<id> subfolder.
Setting up the building blocks — HTTP API tools, mailboxes, MCP servers, agents, SMTP — is not part of the workflow editor; see the linked articles.

Example 1: invoice mailbox → review → SEPA file

Goal: fetch new invoices from a mailbox on weekday mornings, extract payment data, have a human review it and store a SEPA file.

Inputs: none — all parameters are fixed in the configuration.
Step mail.fetch: toolRef pointing to the invoice mailbox tool, subjectFilter: "Invoice", unreadOnly on, downloadAttachments on, markAsRead on (prevents double processing in scheduled operation).
Step llm.transform: prompt “Extract recipient, IBAN, amount and payment reference from these invoices: {{steps.mails.output}}” with an outputSchema for a list of payment items. The PII shield stays on — the pseudonymisation is resolved automatically for the next step.
Step review: the run pauses; an admin reviews the extracted payment data in the form, corrects amounts if needed and approves.
Step file.write: writes the SEPA file (pain.001 XML) from {{steps.extract.output}} into the artifact folder.
Trigger: schedule 0 6 * * 1-5 (weekdays 06:00 UTC); activate after a successful dry run.

Example 2: YouTube import via webhook

Goal: an external system reports a video URL; CompanyWizard fetches the transcript and prepares it editorially.

Input: videoUrl (text, required).
Step mcp.tool: calls the transcript tool of the connected YouTube MCP server with args: { "url": "{{inputs.videoUrl}}" } — tick read-only call.
Step llm.transform: prompt “Polish this transcript into a well-readable article: {{steps.transcript.output}}”.
Step llm.transform: translates the polished text (“Translate to German: {{steps.polish.output}}”).
Trigger: generate a webhook token and set up the caller with the curl pattern above — body: { "videoUrl": "…" }.
Test: first a dry run with a sample URL, then the first real webhook call.