Workflows

Lifecycle (GraphQL)

All lifecycle operations go through POST /graphql. Only one version can be ACTIVE per workflow; activating a new version automatically deactivates the previous one.

Activate or deactivate a version

mutation ActivateWorkflowVersion($workflowVersionId: UUID!) {
  activateWorkflowVersion(workflowVersionId: $workflowVersionId)
}

mutation DeactivateWorkflowVersion($workflowVersionId: UUID!) {
  deactivateWorkflowVersion(workflowVersionId: $workflowVersionId)
}

Edit a published workflow (create a draft)

mutation CreateDraftFromWorkflowVersion($input: CreateDraftFromWorkflowVersionInput!) {
  createDraftFromWorkflowVersion(input: $input) {
    id name status trigger steps
  }
}

# input
{
  "workflowId": "workflow-uuid",
  "workflowVersionIdToCopy": "source-version-uuid"
}

Versions are immutable once activated. This mutation copies the trigger and steps into a new editable DRAFT.

Trigger a manual run

mutation RunWorkflowVersion($input: RunWorkflowVersionInput!) {
  runWorkflowVersion(input: $input) { workflowRunId }
}

# input
{
  "workflowVersionId": "version-uuid",
  "payload": { "customField": "value" },
  "objectNameSingular": "person",
  "recordId": "record-uuid"
}

Only ACTIVE versions can run. For MANUAL triggers, the payload becomes the {{trigger.*}} variable source for the run.

Apply a template

mutation CreateWorkflowFromTemplate($input: CreateWorkflowFromTemplateInput!) {
  createWorkflowFromTemplate(input: $input) {
    success workflowId workflowVersionId stepsCreated
  }
}

# templateType values:
#   DEAL_FROM_PERSON            create an opportunity from a person
#   DEAL_FROM_COMPANY           create an opportunity from a company
#   CUSTOMER_SUCCESS_HANDOFF    handoff on opportunity stage change
#   INBOUND_LEAD_TRIAGE         route and qualify inbound leads

Reading Run State

A run's state object contains the executed flow, per-step outputs, and any error:

{
  "flow": { "trigger": { }, "steps": [ ] },
  "stepInfos": {
    "step-uuid": { "status": "SUCCESS", "output": { } }
  },
  "workflowRunError": null,
  "triggerUserName": "Alice Smith"
}

# Quick status check with jq
curl -sG "https://app.usedalil.ai/rest/workflowRuns/run-uuid" \
  --data-urlencode "depth=1" \
  -H "Authorization: Bearer YOUR_API_KEY" | \
  jq '{ status: .data.workflowRun.status,
        error: .data.workflowRun.state.workflowRunError }'

Common Gotchas

• Workflow ≠ Version: POST /rest/workflows creates only the container; create a workflowVersion separately to have something to edit.
• You cannot PATCH trigger or steps via REST; step editing goes through GraphQL mutations.
• Running a DRAFT version returns an error; activate it first.
• Deleting a workflow permanently removes all versions and runs; there is no soft delete.
• Response wrappers follow the path segment: .data.workflow, .data.workflowVersions, .data.workflowRuns.