Workflows

A workflow in ProvenanceOne is a directed acyclic graph (DAG) of steps that defines an automation. It specifies what triggers execution, what steps run in what order, and what happens when a step succeeds, fails, or requires human review. The workflow is the blueprint — it does not run by itself. Each time the trigger fires, ProvenanceOne creates a run: a live execution of the workflow against a specific input.

Workflows are not restricted to linear sequences. You can branch on logic conditions, run steps in parallel, embed approval gates, and compose agents, skills, and MCP server calls in any topology the DAG supports.

---

When to use workflows

Use a workflow any time you need to coordinate more than one automated step, or when you need to enforce ordering, approvals, or conditional logic around AI agent calls. Workflows are particularly valuable when:

• An AI agent needs to take consequential actions (deleting records, sending bulk messages) and you need a human-in-the-loop gate before those actions execute
• You are pulling data from one system, transforming it, and writing it to another on a schedule
• You need an auditable, versioned record of what ran, when, with what inputs, and what the agent decided

---

Key concepts

Workflow vs. run — the workflow is the definition (what to do); the run is the execution (what happened). A single workflow can have hundreds of runs. Each run records which workflow version was active when it started.

DAG — each workflow is a directed acyclic graph. Nodes are steps; edges define data flow and execution order. Cycles are not permitted — a step cannot depend on itself.

Version — every call to POST /workflows/{workflowId}/publish creates an immutable version (v1, v2, … v14, etc.). The draft workspace is separate from published versions. Runs always reference the version that was live when the run started.

Draft vs. deployed — the visual editor always operates on the draft. Publishing the draft produces a new immutable version without affecting runs in progress under the previous version.

Environment — workflows are deployed to production, staging, or development. Use separate environments to test changes before promoting to production.

---

How it works

Workflow lifecycle

A workflow moves through the following statuses:

• draft — being edited; not executable. The visual editor saves drafts automatically.
• deployed — a published version is active; the workflow can accept trigger events and start runs.
• paused — deployed but not accepting new trigger events. Runs in progress continue.
• failed — the platform detected a configuration or infrastructure error that prevents the workflow from operating. Inspect the workflow for misconfigured steps.
• approval — the workflow itself is pending an administrative approval before it can be deployed.

Publishing

Publish a draft by clicking Publish in the editor or calling POST /workflows/{workflowId}/publish. Each published version is immutable. The workflow version field increments by one. If you need to change the workflow, edit the draft and publish again.

Trigger types

A workflow has exactly one trigger, defined in the trigger step. The six trigger types are:

Trigger	How it fires
webhook	An HTTP POST to the workflow's unique inbound URL. The request body becomes the run's initial payload.
schedule	A cron expression or interval. ProvenanceOne fires the trigger at the defined time in the configured timezone.
manual	A user clicks Run in the UI or calls the runs API directly. Useful for testing and for workflows that should not fire automatically.
event	A named event on the ProvenanceOne event bus (e.g. approval.granted, run.failed). The event payload is passed to the workflow.
api	A call to POST /runs with the workflow ID. Similar to manual but designed for programmatic invocation from external systems.
queue	A message arrives on a configured queue integration. The message body becomes the run payload.

Step kinds

Each node in the DAG is a step with a kind. The ten step kinds are:

Kind	Purpose
trigger	The entry point of every workflow. Exactly one per workflow. Defines how the run starts and what initial data is available.
data	Reads from or writes to a datastore (database, object store, etc.). Use for structured data lookups or persistence.
skill	Calls a ProvenanceOne skill — a sandboxed serverless function with a defined input schema. Use for repeatable, testable data operations.
agent	Invokes an AI agent. The agent receives context from upstream steps and may call tools (skills, MCP servers). Agent steps are probabilistic; design surrounding steps accordingly.
mcp	Calls a specific tool on a registered MCP server, routed through the MCP Gateway proxy.
logic	A conditional branch or loop. Routes execution to different downstream steps based on field values or expressions.
approval	Pauses the run and sends a human-in-the-loop approval request. Execution resumes only when an assignee approves or rejects.
action	Calls an external service (e.g. create a CRM record, send an HTTP request). Distinct from skill in that actions are simpler, direct integrations without a sandbox.
notify	Sends a notification — email, Slack, or webhook — to one or more recipients.
storage	Reads from or writes to object storage (e.g. object storage). Use for files, large blobs, or structured exports.

---

Configuration options

Workflow fields

Field	Type	Required	Default	Description
name	string	Yes	—	Human-readable workflow name
description	string	No	—	Short description shown in the list view
status	enum	—	draft	draft | deployed | paused | failed | approval
trigger	enum	Yes	—	webhook | schedule | manual | event | api | queue
triggerDetail	object	Varies	—	Trigger-specific config (e.g. cron expression for schedule)
version	string	—	v1	Set by the platform on publish; increments with each publish
owner	string	Yes	—	User email of the workflow owner
tags	string[]	No	[]	Free-form tags for filtering
team	string	No	—	Team the workflow belongs to
environment	enum	Yes	—	production | staging | development

Contains flags

The workflow list shows four flags for each workflow, derived from its step composition: Agent, Mcp, Skill, Approval. These are computed; you cannot set them directly.

Metrics fields (read-only)

Field	Description
lastRun	Timestamp of the most recent run
lastRunStatus	Status of the most recent run
successRate	Percentage of runs that ended in succeeded over the last 30 days
runs7d	Number of runs in the last 7 days

---

Examples

Support escalation (agent + approval)

1. Trigger: webhook — receives a new support ticket
2. Agent step: classify ticket severity and draft a response
3. Logic step: if severity is high, route to approval; otherwise continue
4. Approval step: human reviews the agent's draft and approves or edits
5. Action step: post the approved response to the ticketing system

Scheduled data sync (schedule + skill)

1. Trigger: schedule — daily at 02:00 UTC
2. Skill step: extract records from the source database
3. Skill step: transform and validate the records
4. Data step: upsert into the destination datastore
5. Notify step: email summary to the data team

Event-driven enrichment (event + agent)

1. Trigger: event — run.completed from a sibling workflow
2. Data step: fetch the completed run's output payload
3. Agent step: enrich the data with external knowledge
4. Storage step: write the enriched result to object storage

---

Common mistakes

• Creating linear workflows when parallel branches would be faster. If two skills fetch independent data, connect them both to the same upstream step and they will execute concurrently.
• Skipping the approval step on high-risk agent actions. Agents are probabilistic — they can and do make mistakes. Insert approval steps before irreversible actions.
• Editing a deployed workflow and expecting changes to take effect immediately. Changes only take effect after you publish the draft as a new version.
• Using production for initial testing. Always validate in development or staging first.
• Leaving workflows in paused status indefinitely. A paused workflow will not process incoming trigger events. Queued triggers are not replayed when the workflow resumes.

---

Troubleshooting

Workflow stuck in approval status — a workflow-level approval is pending. Check the Approvals page and action it.

Trigger not firing on schedule — verify the cron expression and confirm the timezone setting. Confirm the workflow is in deployed status, not paused.

Webhook trigger not receiving events — the inbound webhook URL rotates on each publish. Update the URL in the external system after every publish.

Run starts but fails immediately on the trigger step — the trigger payload may not match the schema the first downstream step expects. Check the step's input mapping configuration.

---

Security and permissions

• editor and admin roles can create, edit, and publish workflows.
• viewer can view workflows and runs but cannot modify anything.
• Audit events workflow.edited, workflow.published, and workflow.draft_saved are emitted on each corresponding action.
• Workflows are scoped to a workspace. Members cannot see or trigger workflows in workspaces they are not members of.

---

Related pages

• Workflow Runs
• Agents
• Approvals
• Skills
• MCP Servers

---

FAQ