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".
Nodes in the workflow representing stages of your business process. Each state can have transitions to other states.
Actions that move the workflow from one state to another. Can be simple (direct state reference) or complex (with validation and inputs).
Split the workflow into multiple parallel branches that execute concurrently. All branches run simultaneously.
Merge parallel branches back together. Can wait for all branches (wait_all) or any branch (wait_any) to complete.
Users or roles that can trigger transitions from a specific state. Provides fine-grained access control.
Data required to start a workflow or perform a transition. Can be required or optional, with type constraints.
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"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"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"A state with no transitions. When a workflow reaches a final state, it is marked as completed.
approved:
type: "state"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:
Create a YAML file with your workflow definition. Save it locally (e.g., leave-request.yml).
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.ymlIf a definition with the same ID already exists, a new version is created automatically. The system maintains version history for each definition.
List all workflow definitions with pagination (cursor-based).
Parameters: cursor, limit (1-100, default: 20)
Create a new workflow definition. If ID exists, creates a new version.
Body: YAML workflow definition
Retrieve a specific workflow definition.
Accept: application/yaml or application/json
Create or update a workflow definition (upsert). Path ID takes precedence over body ID.
Delete a workflow definition.
List version history for a workflow definition.