> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Setup

> Create and configure workflows for your domain in OpenIndex.

Workflows control the lifecycle of work items in a domain. A workflow defines the valid statuses a work item can move through, the stages that group those statuses, the stage gates that enforce requirements at transitions, and the custom fields that capture structured data during execution.

<CardGroup cols={2}>
  <Card title="Statuses" icon="circle-dot">
    Named states a work item can be in, such as `backlog`, `in_progress`, or `completed`.
  </Card>

  <Card title="Stages" icon="layers">
    Groups of statuses that represent a phase of work. Stage gates enforce entry requirements.
  </Card>

  <Card title="Stage gates" icon="lock">
    Checkpoints between stages that require acknowledgement, checklist completion, or custom-field values before progressing.
  </Card>

  <Card title="Custom fields" icon="sliders">
    Structured data fields attached to a workflow, optionally required at specific transitions.
  </Card>
</CardGroup>

***

## Creating a workflow

Use the API to create a workflow in your domain:

```bash theme={null}
POST /workflows
```

```json theme={null}
{
  "name": "Triage",
  "description": "Default triage workflow for incoming requests",
  "domain": "<domain-id>"
}
```

Workflows can be personal-domain or domain-scoped. Once a work item references a `workflowId`, that value is immutable.

***

## Managing workflow statuses and stages

After creating a workflow, update its statuses and stages:

```bash theme={null}
PATCH /workflows/:id
```

Status transitions, stage membership, and stage gate configurations are all managed through this endpoint.

<Note>
  All status transitions and stage gate requirements are validated server-side. A work item cannot bypass a gate through the API or CLI.
</Note>

***

## Adding custom fields

Custom fields let you capture structured data on work items that use a workflow. Add a field with:

```bash theme={null}
POST /workflows/:id/fields
```

You can also update or delete fields:

```bash theme={null}
PATCH /workflows/:id/fields/:fieldId
DELETE /workflows/:id/fields/:fieldId
```

**Field types** available on work items include text, number, select, and date values. Fields can be marked as required at specific stage transitions — the server enforces these requirements when an agent or user attempts to progress the work item.

***

## Attaching a workflow to a domain

Once a workflow is configured, attach it to a domain so it becomes available when creating work items in that domain:

```bash theme={null}
POST /domains/:id/workflows
```

To see all workflows available in a domain:

```bash theme={null}
GET /domains/:id/workflows
```

***

## Viewing workflows via CLI

```bash theme={null}
# List all workflows in a domain
oi settings domain workflows list --domain OPS

# Get a specific workflow
oi settings domain workflows get TRIAGE --domain OPS

# List custom fields on a workflow
oi settings domain workflows fields list TRIAGE --domain OPS
```

***

## Assigning a workflow to a work item

Pass `--workflow-id` when creating or updating a work item:

```bash theme={null}
oi work-item create --kind task --title "Review request" --domain-id <id> --workflow-id <workflow-id>

oi work-item update ABC-123 --workflow-id <workflow-id>
```

***

## Viewing available transitions

Before claiming or progressing a work item, check which status transitions and stage gates are currently available:

```bash theme={null}
oi work-item transitions ABC-123
```

The output includes:

* `availableTransitions`: statuses reachable from the current state
* `availableStageGates`: gates that can be progressed right now
* `terminalStatuses`: statuses that mark the work item as resolved

***

## Progressing through a stage gate

When a workflow stage has a gate, you must satisfy its requirements before moving to the next stage.

<Steps>
  <Step title="Check available gates">
    ```bash theme={null}
    oi work-item transitions ABC-123
    ```

    The response shows available stage gates and their keys.
  </Step>

  <Step title="Progress through a text-acknowledgement gate">
    ```bash theme={null}
    oi work-item progress ABC-123 --to-stage waiting_for_input --accept-requirements-text
    ```
  </Step>

  <Step title="Progress through a checklist gate">
    ```bash theme={null}
    oi work-item progress ABC-123 --stage-gate-key <gate-key> \
      --checked-requirement-item "First requirement" \
      --checked-requirement-item "Second requirement"
    ```

    Pass every required checklist item. The server rejects the request if any required item is missing.
  </Step>
</Steps>

<Tip>
  Use `--to-stage` to resolve the gate from the current `availableStageGates` automatically. Use `--stage-gate-key` when you want to target a specific gate explicitly.
</Tip>

***

## Completing work

Once a work item has progressed through its workflow, claim it, complete it, or use the one-shot `done` shortcut:

```bash theme={null}
# Claim the item (mark as in-progress)
oi work-item claim ABC-123 --to-status in_progress

# Complete the item (resolve and clear agent fields)
oi work-item complete ABC-123 --to-status completed

# One-shot: auto-progress through all valid stage gates to completion
oi work-item done ABC-123
```

`complete` requires a terminal status from the workflow's `terminalStatuses` list. It clears active agent fields and marks the work item as resolved.