Overview

A workflow definition is a YAML file that models a business process as a state machine. Workflows define states, transitions between states, and can include parallel execution paths using forks and joins.

Note: The yWorkflow App uses a simplified definition format for demonstration purposes. For the full yWorkflow library definition language and capabilities, refer to the Workflow Definition section in "How it works".

Key Concepts

States

Nodes in the workflow representing stages of your business process. Each state can have transitions to other states.

Transitions

Actions that move the workflow from one state to another. Can be simple (direct state reference) or complex (with validation and inputs).

Forks

Split the workflow into multiple parallel branches that execute concurrently. All branches run simultaneously.

Joins

Merge parallel branches back together. Can wait for all branches (wait_all) or any branch (wait_any) to complete.

Owners

Users or roles that can trigger transitions from a specific state. Provides fine-grained access control.

Inputs

Data required to start a workflow or perform a transition. Can be required or optional, with type constraints.

State Types

Standard State

The most common state type. Has transitions to other states and can optionally have owners to restrict who can trigger transitions.

draft:
  transitions:
    submit: "approval_process"
    cancel: "cancelled"

Fork State

Splits the workflow into multiple parallel branches. Defined by a "fork" property with an array of state IDs.

approval_process:
  fork:
    - "manager_check"
    - "hr_check"

Join State

Merges parallel branches. Defined by a "join" property with the target state ID and a "mode" (wait_all or wait_any).

final_gate:
  mode: "wait_all"
  join: "approved"

Final State

A state with no transitions. When a workflow reaches a final state, it is marked as completed.

approved:
  type: "state"

Example: Leave Request Workflow

Here's a complete example workflow that demonstrates all the key concepts:

workflow:
  id: "leave-request"
  start: "draft"

  states:
    draft:
      transitions:
        submit: "approval_process"

    approval_process:
      fork:
        - "manager_check"
        - "hr_check"

    manager_check:
      owners: ["manager"]
      transitions:
        manager_deny: "draft"
        manager_approve: "final_gate"

    hr_check:
      owners: ["hr"]
      transitions:
        hr_deny: "draft"
        hr_approve: "final_gate"

    final_gate:
      mode: "wait_all"
      join: "approved"

    approved:
      type: "state"

Workflow Flow:

  1. Start in "draft" state
  2. Transition "submit" moves to "approval_process"
  3. Fork creates parallel branches: "manager_check" and "hr_check"
  4. Both branches must complete and reach "final_gate" (wait_all mode)
  5. Join to "approved" final state

Creating Workflow Definitions

1

Write Your Definition

Create a YAML file with your workflow definition. Save it locally (e.g., leave-request.yml).

2

Upload via API

Use the Definitions API to upload your workflow:

curl -X 'POST' \
  'https://app.yworkflow.com/api/definitions' \
  -H 'accept: */*' \
  -H 'X-API-KEY: wkf_123456789012' \
  -H 'Content-Type: application/yaml' \
  --data-binary @leave-request.yml
3

Versioning

If a definition with the same ID already exists, a new version is created automatically. The system maintains version history for each definition.

API Endpoints

GET /api/definitions

List all workflow definitions with pagination (cursor-based).

Parameters: cursor, limit (1-100, default: 20)

POST /api/definitions

Create a new workflow definition. If ID exists, creates a new version.

Body: YAML workflow definition

GET /api/definitions/{id}

Retrieve a specific workflow definition.

Accept: application/yaml or application/json

PUT /api/definitions/{id}

Create or update a workflow definition (upsert). Path ID takes precedence over body ID.

DELETE /api/definitions/{id}

Delete a workflow definition.

GET /api/definitions/{id}/versions

List version history for a workflow definition.