picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/workflow-run.md

@@ -0,0 +1,263 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Workflow run schema
+
+The operations and types that `workflow-run.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `workflowRun`
+
+Get a workflow run by ID. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+
+```graphql
+workflowRun(id: ID!): WorkflowRun @auth
+```
+
+## Types
+
+### `WorkflowRunStatus`
+
+```graphql
+"""Where a run is in its life."""
+enum WorkflowRunStatus {
+  """The run has started and not yet ended."""
+  RUNNING
+  """Every task the run reached succeeded."""
+  COMPLETED
+  """A task failed and the run stopped there."""
+  FAILED
+}
+```
+
+### `WorkflowTaskType`
+
+```graphql
+"""The kind of node a task ran."""
+enum WorkflowTaskType {
+  """The trigger node the run started from."""
+  ORIGIN
+  """A tool node."""
+  TOOL
+  """A condition node, which chose a branch."""
+  CONDITION
+  """A sleep node, which suspended the run."""
+  SLEEP
+}
+```
+
+### `WorkflowTaskStatus`
+
+```graphql
+"""Where a task is in its life."""
+enum WorkflowTaskStatus {
+  """The task has started and not yet ended."""
+  RUNNING
+  """The task did its work."""
+  SUCCEEDED
+  """The task failed, and the run with it."""
+  FAILED
+}
+```
+
+### `WorkflowRunSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `Workflow.runs(...)`. Pair with `reverse: true` to flip
+the order. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+"""
+enum WorkflowRunSortKeys {
+  """Sort by `startedAt`."""
+  STARTED_AT
+}
+```
+
+### `WorkflowTaskSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `WorkflowRun.tasks(...)`. Pair with `reverse: true` to
+flip the order. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+"""
+enum WorkflowTaskSortKeys {
+  """
+  Sort by `startedAt`: the order the run executed its tasks in, one at a time.
+  """
+  STARTED_AT
+}
+```
+
+### `WorkflowRun`
+
+```graphql
+"""
+One execution of a workflow: its published version, or its draft for a run
+started on the preview surface.
+
+A run is started by an event and walks the workflow's graph in order; `tasks`
+lists every node it reached. `failureReason` is set only when `status` is
+`FAILED` and names a node, a tool or an argument, never anything a tool read.
+"""
+type WorkflowRun {
+  """Unique run identifier."""
+  id: ID!
+  """
+  ID of the workflow the run executed. Present after the workflow is deleted,
+  which is what a link to the run is built from.
+  """
+  workflowId: ID!
+  """
+  ID of the workspace the workflow belongs to. A workflow ID is unique only within its workspace.
+  """
+  workspaceId: ID!
+  """
+  The workflow the run executed, or null once it is deleted. Requires scope:
+  `ORGANIZATION_WORKSPACE_READ`.
+  """
+  workflow: Workflow
+  """Where the run is in its life."""
+  status: WorkflowRunStatus!
+  """When the run started."""
+  startedAt: DateTime!
+  """When the run ended, or null while it is running."""
+  finishedAt: DateTime
+  """Why the run failed, or null unless it did."""
+  failureReason: String
+  """
+  True when a visitor on the preview surface started the run. A preview run
+  executes the workspace's draft workflow as it stood when the run started, and
+  its writes are real.
+  """
+  preview: Boolean!
+  """
+  The tasks the run performed, one per visit of a node, in the order it reached them;
+  pass `reverse: true` for the latest first. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  """
+  tasks(first: Int, after: String, sortKey: WorkflowTaskSortKeys = STARTED_AT, reverse: Boolean = false): WorkflowTaskConnection! @auth
+  """
+  The run's labels, ordered by namespace then key: state the run keeps about
+  itself, such as its outcome, or a person's notes on it. An expired label is
+  not listed. Run labels outlive every lead.
+  Write them with `labelsSet`, `ownerType: WORKFLOW_RUN` and the run's id.
+  Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  """
+  labels: [Label!]! @auth
+}
+```
+
+### `WorkflowTask`
+
+```graphql
+"""
+One task of a workflow run: one visit of a node the run reached, and what came of it.
+
+A tool task's `operations` are the creates, updates and deletes it made to
+leads and labels. Other kinds perform none.
+"""
+type WorkflowTask {
+  """Unique task identifier. The same across every attempt of one visit."""
+  id: ID!
+  """
+  The ID of the graph node the task ran, as the workflow's `nodes` name it.
+  """
+  stepId: ID!
+  """
+  Which visit of its node the task is, from 1. A run that re-enters a node records each visit as a task of its own.
+  """
+  visit: Int!
+  """The kind of node the task ran."""
+  type: WorkflowTaskType!
+  """The tool a tool task ran, or null for another kind."""
+  tool: String
+  """Where the task is in its life."""
+  status: WorkflowTaskStatus!
+  """When the task started."""
+  startedAt: DateTime!
+  """When the task ended, or null while it is running."""
+  finishedAt: DateTime
+  """Why the task failed, or null unless it did."""
+  failureReason: String
+  """The run this task belongs to."""
+  run: WorkflowRun!
+  """
+  What the task did to leads and labels, latest first; pass `reverse: false`
+  for the order performed. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  """
+  operations(first: Int, after: String, sortKey: OperationSortKeys = OCCURRED_AT, reverse: Boolean = true): OperationConnection! @auth
+}
+```
+
+### `WorkflowRunConnection`
+
+```graphql
+"""Relay-style connection of workflow runs."""
+type WorkflowRunConnection {
+  """List of run edges."""
+  edges: [WorkflowRunEdge!]!
+  """Flat list of runs, equivalent to `edges[].node`. Convenience accessor."""
+  nodes: [WorkflowRun!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of runs in the list."""
+  totalCount: Int!
+}
+```
+
+### `WorkflowRunEdge`
+
+```graphql
+"""Edge type for `WorkflowRunConnection`."""
+type WorkflowRunEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The run."""
+  node: WorkflowRun!
+}
+```
+
+### `WorkflowTaskConnection`
+
+```graphql
+"""Relay-style connection of workflow run tasks."""
+type WorkflowTaskConnection {
+  """List of task edges."""
+  edges: [WorkflowTaskEdge!]!
+  """
+  Flat list of tasks, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [WorkflowTask!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of tasks the run performed."""
+  totalCount: Int!
+}
+```
+
+### `WorkflowTaskEdge`
+
+```graphql
+"""Edge type for `WorkflowTaskConnection`."""
+type WorkflowTaskEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The task."""
+  node: WorkflowTask!
+}
+```
+
+### `Workflow` (extension)
+
+```graphql
+extend type Workflow {
+  """
+  This workflow's runs in its workspace, oldest first; pass `reverse: true`
+  for the latest first. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  """
+  runs(first: Int, after: String, last: Int, before: String, sortKey: WorkflowRunSortKeys = STARTED_AT, reverse: Boolean = false): WorkflowRunConnection! @auth
+}
+```