Skip to content
KolonyKolonyKolony Docs

Workflow configuration

A workflow configuration defines work steps (workbaskets / states), how items move between them (transitions), who sees what (views), and which form configurations may participate (integrations).

This guide walks the JSON part by part, then assembles a complete multi-route template. Validate and persist with the endpoints at the end.

Contract version covered here: 1.0.0.

Pair forms first: create a form configuration whose id you list under integrations.forms.allowedConfigurationIds (and reference in each view’s forms map). The completed example below uses the Field Snapshot template id 12c8aa13-88f6-40de-b7c0-4b1bef48bb51.

Mental model

Section titled “Mental model”
Concept Meaning for readers
Workbasket A state (work step) in the process
Transition Allowed move from one workbasket to another
View A queue / desk over one or more workbaskets, with form field visibility rules
$ refs Same translation pattern as forms — labels live under translations

Every structural id must be a UUID v4.

Part 1 — Document shell and controls

Section titled “Part 1 — Document shell and controls”
{
  "version": "1.0.0",
  "id": "f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d",
  "controls": {
    "enableLogging": true
  }
}
Property Purpose
version Schema version (1.0.0).
id UUID of this workflow configuration.
controls.enableLogging When true, enable audit logging for workflow activity (as supported by the deployment).

Part 2 — Translations

Section titled “Part 2 — Translations”

All labels for the workflow title, workbaskets, views, and transitions live here. Structure uses $ paths only.

{
  "translations": {
    "defaultLanguage": "en",
    "en": {
      "details": {
        "title": "Site Inspection Review",
        "description": "Multi-route review workflow for site inspection forms."
      },
      "workbaskets": {
        "wb_intake": { "label": "Intake" },
        "wb_triage": { "label": "Triage" },
        "wb_closed": { "label": "Closed" }
      },
      "views": {
        "v_operations": {
          "label": "Operations queue",
          "description": "Intake through early steps."
        }
      },
      "transitions": {
        "intake_to_triage": { "label": "Send to triage" }
      }
    }
  }
}

Keys under workbaskets / views / transitions are translation keys (e.g. wb_intake). They are not the UUID ids used in network and views arrays — those UUIDs are separate; $ paths bind display labels.

Part 3 — Network (workbaskets and transitions)

Section titled “Part 3 — Network (workbaskets and transitions)”

network is the process graph:

Property Purpose
entryWorkbasketId UUID of the starting workbasket (first state / work step).
workbaskets[] Each workbasket: id, $ label, order, optional terminal, and transitions[].
transitions[] From this workbasket: id, targetWorkbasketId, $ label.
terminal: true End state — typically empty transitions. 
{
  "network": {
    "entryWorkbasketId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "workbaskets": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "label": "$.workbaskets.wb_intake.label",
        "order": 1,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111101",
            "targetWorkbasketId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
            "label": "$.transitions.intake_to_triage"
          }
        ]
      },
      {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "label": "$.workbaskets.wb_triage.label",
        "order": 2,
        "transitions": []
      }
    ]
  }
}

Design transitions as the allowed actions operators can take from each step (including rejects and returns).

Part 4 — Views

Section titled “Part 4 — Views”

Views group workbaskets into queues and control how linked forms appear in list/detail for that view.

Property Purpose
id View UUID.
label / description $ translation paths.
workbasketIds Which workbaskets (states) this view covers.
permissionSlot Slot number used by the deployment’s permission model for this view.
forms Map keyed by form configuration UUID.
listFields Form field keys reserved for list presentation.
detailFields Field keys shown in detail, with optional overrides (editable, required, …).
metadata Per-view visibility/editability for form metadata facets (timestamp, tags, summary, location, …). 
{
  "id": "33333333-3333-4333-8333-333333333301",
  "label": "$.views.v_operations.label",
  "description": "$.views.v_operations.description",
  "workbasketIds": ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
  "permissionSlot": 1,
  "forms": {
    "12c8aa13-88f6-40de-b7c0-4b1bef48bb51": {
      "listFields": ["p1_k1", "p1_k2"],
      "detailFields": [
        { "fieldKey": "p1_k1", "overrides": { "editable": false } },
        { "fieldKey": "p2_k2", "overrides": { "editable": true } }
      ],
      "metadata": {
        "timestamp": { "visible": true, "editable": false },
        "tags": { "visible": true, "editable": true }
      }
    }
  }
}

Field keys (p1_k1, …) must match the form configuration’s field keys.

Part 5 — Integrations

Section titled “Part 5 — Integrations”
{
  "integrations": {
    "forms": {
      "allowedConfigurationIds": ["12c8aa13-88f6-40de-b7c0-4b1bef48bb51"]
    }
  }
}

Only form configuration ids listed here may be used with this workflow. Every key under each view’s forms map should also appear in this allowlist.

Completed example (template)

Section titled “Completed example (template)”

Multi-route Site Inspection Review: intake → triage → fast track / full review / reject → specialist → closed. Form id matches the Form configuration completed template. Replace UUIDs and adjust routes for your process.

{
  "version": "1.0.0",
  "id": "f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d",
  "controls": {
    "enableLogging": true
  },
  "translations": {
    "defaultLanguage": "en",
    "en": {
      "details": {
        "title": "Site Inspection Review",
        "description": "Multi-route review workflow for site inspection forms."
      },
      "workbaskets": {
        "wb_intake": { "label": "Intake" },
        "wb_triage": { "label": "Triage" },
        "wb_fast_track": { "label": "Fast track" },
        "wb_full_review": { "label": "Full review" },
        "wb_specialist": { "label": "Specialist review" },
        "wb_closed": { "label": "Closed" },
        "wb_rejected": { "label": "Rejected" }
      },
      "views": {
        "v_operations": {
          "label": "Operations queue",
          "description": "Intake through fast-track steps."
        },
        "v_review": {
          "label": "Review desk",
          "description": "Full and specialist review steps."
        }
      },
      "transitions": {
        "intake_to_triage": { "label": "Send to triage" },
        "triage_fast": { "label": "Fast track" },
        "triage_full": { "label": "Full review" },
        "triage_reject": { "label": "Reject" },
        "fast_to_closed": { "label": "Close (fast track)" },
        "full_to_specialist": { "label": "Escalate to specialist" },
        "specialist_close": { "label": "Approve and close" },
        "specialist_return": { "label": "Return to triage" }
      }
    }
  },
  "network": {
    "entryWorkbasketId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "workbaskets": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "label": "$.workbaskets.wb_intake.label",
        "order": 1,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111101",
            "targetWorkbasketId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
            "label": "$.transitions.intake_to_triage"
          }
        ]
      },
      {
        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "label": "$.workbaskets.wb_triage.label",
        "order": 2,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111102",
            "targetWorkbasketId": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f",
            "label": "$.transitions.triage_fast"
          },
          {
            "id": "11111111-1111-4111-8111-111111111103",
            "targetWorkbasketId": "d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f8a",
            "label": "$.transitions.triage_full"
          },
          {
            "id": "11111111-1111-4111-8111-111111111104",
            "targetWorkbasketId": "a7b8c9d0-e1f2-4a3b-8c5d-6e7f8a9b0c1d",
            "label": "$.transitions.triage_reject"
          }
        ]
      },
      {
        "id": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f",
        "label": "$.workbaskets.wb_fast_track.label",
        "order": 3,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111105",
            "targetWorkbasketId": "f6a7b8c9-d0e1-4f2a-8b3c-5d6e7f8a9b0c",
            "label": "$.transitions.fast_to_closed"
          }
        ]
      },
      {
        "id": "d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f8a",
        "label": "$.workbaskets.wb_full_review.label",
        "order": 4,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111106",
            "targetWorkbasketId": "e5f6a7b8-c9d0-4e1f-8a2b-4c5d6e7f8a9b",
            "label": "$.transitions.full_to_specialist"
          }
        ]
      },
      {
        "id": "e5f6a7b8-c9d0-4e1f-8a2b-4c5d6e7f8a9b",
        "label": "$.workbaskets.wb_specialist.label",
        "order": 5,
        "transitions": [
          {
            "id": "11111111-1111-4111-8111-111111111107",
            "targetWorkbasketId": "f6a7b8c9-d0e1-4f2a-8b3c-5d6e7f8a9b0c",
            "label": "$.transitions.specialist_close"
          },
          {
            "id": "11111111-1111-4111-8111-111111111108",
            "targetWorkbasketId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
            "label": "$.transitions.specialist_return"
          }
        ]
      },
      {
        "id": "f6a7b8c9-d0e1-4f2a-8b3c-5d6e7f8a9b0c",
        "label": "$.workbaskets.wb_closed.label",
        "order": 6,
        "terminal": true,
        "transitions": []
      },
      {
        "id": "a7b8c9d0-e1f2-4a3b-8c5d-6e7f8a9b0c1d",
        "label": "$.workbaskets.wb_rejected.label",
        "order": 7,
        "terminal": true,
        "transitions": []
      }
    ]
  },
  "views": [
    {
      "id": "33333333-3333-4333-8333-333333333301",
      "label": "$.views.v_operations.label",
      "description": "$.views.v_operations.description",
      "workbasketIds": [
        "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
      ],
      "permissionSlot": 1,
      "forms": {
        "12c8aa13-88f6-40de-b7c0-4b1bef48bb51": {
          "listFields": ["p1_k1", "p1_k2", "p2_k1"],
          "detailFields": [
            { "fieldKey": "p1_k1", "overrides": { "editable": false } },
            { "fieldKey": "p2_k2", "overrides": { "editable": true } }
          ],
          "metadata": {
            "timestamp": { "visible": true, "editable": false },
            "tags": { "visible": true, "editable": true }
          }
        }
      }
    },
    {
      "id": "33333333-3333-4333-8333-333333333302",
      "label": "$.views.v_review.label",
      "description": "$.views.v_review.description",
      "workbasketIds": [
        "d4e5f6a7-b8c9-4d0e-8f2a-3b4c5d6e7f8a",
        "e5f6a7b8-c9d0-4e1f-8a2b-4c5d6e7f8a9b"
      ],
      "permissionSlot": 2,
      "forms": {
        "12c8aa13-88f6-40de-b7c0-4b1bef48bb51": {
          "listFields": ["p1_k1", "p2_k1", "p2_k2"],
          "detailFields": [
            { "fieldKey": "p2_k2", "overrides": { "editable": true, "required": true } }
          ],
          "metadata": {
            "summary": { "visible": true, "editable": true },
            "location": { "visible": true, "editable": false }
          }
        }
      }
    }
  ],
  "integrations": {
    "forms": {
      "allowedConfigurationIds": ["12c8aa13-88f6-40de-b7c0-4b1bef48bb51"]
    }
  }
}

Validate and create via the API

Section titled “Validate and create via the API”

Wrap the configuration under config:

{
  "id": "f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d",
  "config": { }
}
Method Path Purpose
POST /v0/workflows/configurations/validate Validate without persisting
POST /v0/workflows/configurations Create (persists; typically 201)
PUT /v0/workflows/configurations/{configurationId} Update
GET /v0/workflows/configurations/{configurationId} Fetch one
GET /v0/workflows/configurations List

Suggested order: authenticate → ensure the linked form configuration exists → POST .../validate → POST .../configurations → continue with Workflows (instances and transitions).

Exact schemas: API reference.