Workflows

Key Concepts

On Ergon, workflows let you define structured, multi-stage processes for your organization. Whether you are building a support ticket queue, a hiring pipeline, or an approval chain, the same building blocks apply.

Workflows

A workflow is an organization-scoped process definition. It acts as the container for everything else — phases, fields, routing, items, and field rules. Each workflow belongs to a single company, lives inside a folder (folders are first-class and used to organize and share workflows), and can be managed independently.

Phases

Phases are the ordered stages that items move through. Every workflow has at least one phase. Each phase can be configured with an optional timeout (to trigger automations when items stall), visibility settings that control which users can see items in that phase, and an allow_create_items flag that determines whether new items can be created directly into that phase.

Phase Routing

Routes are directed edges between phases. Each route defines a from_phase_id and a to_phase_id, restricting how items can move. Routing is strict: every move must follow an explicit route, and without a matching route the move is rejected. A route can also define a per-edge exit gate via required_field_ids — fields that must be filled before an item can leave along that edge — and items can be routed across workflows to a configured global target.

Fields

Fields add typed data collection to each phase. The platform supports a range of field types — from simple text and numbers to structured tables and cross-service record references. Visibility, required, and editability behavior is driven by field rules (managed separately per workflow), and fields also support cross-phase editability so you can control exactly when and by whom a field is filled in. See the Field Types section below for the full list.

Items

Items are the individual units of work that flow through a workflow. Each item has a title, a current phase, collected field values, and an optional assignment to a specific user. Items also support comments and file attachments to facilitate team collaboration.

Field Types

Every field on a phase has a type that determines how values are validated, stored, and presented. You can retrieve the full list programmatically via GET /api/v1/workflows/field-types, but the built-in types are:

Field Options

Some field types require an options object when creating the field. Here are the formats for each:

{
  "choices": ["Low", "Medium", "High", "Critical"]
}

Field Rules & Editability

Visibility and required behavior are driven by field rules — managed per workflow via /workflows/{workflow_id}/field-rules — so you can, for example, only show a “Rejection Reason” field when another field has a certain value. Fields themselves carry an editable_from_phase_ids array — the phases from which the field can be edited even after the item has moved past its original phase. This is useful for fields like priority or notes that should remain editable throughout the lifecycle.

Item Lifecycle

An item begins its life when it is created into a phase that has allow_create_items enabled. From there, it advances through the workflow by following the routes you have defined. At each phase, the relevant fields are presented for data collection. Items can be assigned or reassigned to users at any point, and collaborators can add comments and attachments along the way.

Below is a simple example: creating a workflow in a folder, adding phases and a route, enabling item creation on the entry phase, then creating an item and routing it forward.

# 1. Create a workflow inside a folder
curl -X POST https://platform.ergondata.ai/api/v1/workflows/companies/{company_id}/workflows \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bug tracker", "folder_id": "{folder_id}"}'

# 2. Add phases (use the workflow_id from step 1)
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/{workflow_id}/phases \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Open"}'

curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/{workflow_id}/phases \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "In Progress"}'

# 3. Allow new items to be created into the "Open" phase
curl -X PATCH https://platform.ergondata.ai/api/v1/workflows/phases/{open_phase_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"allow_create_items": true}'

# 4. Add a route from "Open" → "In Progress"
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/{workflow_id}/routes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"from_phase_id": "{open_phase_id}", "to_phase_id": "{in_progress_phase_id}"}'

# 5. Create an item in the "Open" phase
curl -X POST https://platform.ergondata.ai/api/v1/workflows/workflows/{workflow_id}/items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix login timeout", "phase_id": "{open_phase_id}"}'

# 6. Route the item to "In Progress" (must follow an explicit route)
curl -X POST https://platform.ergondata.ai/api/v1/workflows/items/{item_id}/route \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"to_phase_id": "{in_progress_phase_id}"}'

Groups

Assignment groups let you distribute workflow items among team members automatically. A group is a named collection of members attached to a workflow, with a configurable routing strategy that determines how items are assigned.

Routing Strategies

When a group is bound to a phase, that binding carries a strategy that decides which member receives the next item:

• round_robin — items are assigned to members in order, cycling through the list.
• least_loaded — items are assigned to the member with the fewest active items.
• manual — items are left unassigned for a member to claim.

Phase-Group Assignment

You can link a group to a specific phase so that items entering that phase are automatically assigned according to that phase's strategy. This is particularly useful for support queues, approval flows, or any process where work needs to be evenly distributed. The routing strategy lives on each phase-group binding, so the same group can use different strategies in different phases.

Automations

Automations let you react to events emitted by a workflow (item created, routed, field changed, timeout, comment added, …) and trigger actions in other parts of the platform — or in external systems. Authoring and execution live in the central Automations service; from a workflow you only need to grant the automation access to the workflow (or to its folder) and it can then list trigger events and invoke workflow actions like creating or routing items and sending notifications.

See the Automations service guide for the rule editor, condition language, and recursion safeguards (max_trigger_depth).