Skip to content
KolonyKolonyKolony Docs

Workflows

Goal

Section titled “Goal”

Run a process from a validated workflow configuration: create an instance linked to an item (typically a form), inspect view queues, and transition items between states (work steps).

Prerequisites

Section titled “Prerequisites”
  1. Authenticate — Authentication
  2. Form configuration + form instance — Form configuration, Forms (optional files: Form with file)
  3. Workflow configuration — Workflow configuration (POST /v0/workflows/configurations/validate, then create)

Ensure the form configuration id is listed under the workflow’s integrations.forms.allowedConfigurationIds (the Site Inspection Review template allowlists 12c8aa13-88f6-40de-b7c0-4b1bef48bb51).

Configuration vs instance

Section titled “Configuration vs instance”
Workflow configuration Workflow instance
Purpose Declares workbaskets (states / work steps), transitions, views, form allowlist A running process for one item (e.g. a form)
Identity Configuration UUID Created via POST /v0/workflows/instances; item stays addressable as itemId
Entry network.entryWorkbasketId New instances start in that entry workbasket
Forms integrations.forms + per-view forms maps itemType + itemId point at an existing form instance
Progress Transition definitions on workbaskets POST .../transitions with a transitionId from available transitions

You can also pass integrations.workflowConfigurationId when creating a form if the form configuration allows workflow starts — POST /v0/workflows/instances is the explicit start path shown here.

Steps

Section titled “Steps”
  1. Note workflowConfigurationId and a viewId from the configuration
  2. POST /v0/workflows/instances — start a workflow for an item (see example below)
  3. GET /v0/workflows/views/{viewId}/items?workflowConfigurationId=... — list items in that view’s workbaskets
  4. GET /v0/workflows/items/{itemId}?workflowConfigurationId=...&viewId=... — fetch fields, payload, and available transitions
  5. Optional: PATCH /v0/workflows/items/{itemId} — update item fields when the view allows it
  6. POST /v0/workflows/items/{itemId}/transitions — move to the next state (work step) using a transitionId from the available transitions

Repeat fetch → transition as the process advances until a terminal workbasket (e.g. Closed / Rejected).

Example: create instance

Section titled “Example: create instance”

Aligned to the completed Workflow configuration template. Replace itemId with the form instance id returned from Forms create (POST /v0/forms).

{
  "workflowConfigurationId": "f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d",
  "itemType": "FORM",
  "itemId": "<form-instance-id>",
  "confirmSwitch": false
}
Property Purpose
workflowConfigurationId The Site Inspection Review configuration id
itemType Defaults to FORM if omitted
itemId Form instance id to attach to this process
confirmSwitch Optional; set when the API requires confirming a switch onto this workflow

The instance enters the configuration’s entry workbasket (a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d — Intake in the template).

Example: list and fetch (template views)

Section titled “Example: list and fetch (template views)”

Operations queue (Intake / Triage / Fast track) — view id 33333333-3333-4333-8333-333333333301:

GET /v0/workflows/views/33333333-3333-4333-8333-333333333301/items?workflowConfigurationId=f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d

Fetch item (include the view you are working in):

GET /v0/workflows/items/<form-instance-id>?workflowConfigurationId=f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d&viewId=33333333-3333-4333-8333-333333333301&itemType=FORM&language=en

Use available transitions from that response — do not invent transition ids. For reference, Intake → Triage in the template is:

Transition id Meaning
11111111-1111-4111-8111-111111111101 Send to triage ($.transitions.intake_to_triage)

Example: transition

Section titled “Example: transition”
POST /v0/workflows/items/<form-instance-id>/transitions?workflowConfigurationId=f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d&viewId=33333333-3333-4333-8333-333333333301&itemType=FORM&language=en
{
  "transitionId": "11111111-1111-4111-8111-111111111101"
}

Afterward, fetch again for the next available transitions (e.g. Fast track / Full review / Reject from Triage). Review desk view id in the template: 33333333-3333-4333-8333-333333333302.

Section titled “Related”

Exact payloads: API reference. Quotas: Errors & limits.