picked 0.0.102-next.1 → 0.0.102-next.2

package/docs/reference/dashboard/workflow-test-runs.md

@@ -6,8 +6,8 @@ layout: docs
 # Workflow test runs
 
 A test run runs the draft of a workflow one time, with the trigger input that you give.
-It shows what each node did. It saves nothing, so you can test a change before you
-publish it.
+It shows what each node did. By default it saves nothing, so you can test a change before
+you publish it.
 
 ## Where to start a test run
 
@@ -38,16 +38,39 @@ Each action field gets the input for its type:
 
 A required field must have a value before the test run starts.
 
+## Execute writes
+
+Set **Execute writes** to run the tools that write. This option is off by default.
+
+:::warning
+Writes are real. The test run creates and changes leads and labels, sends requests to
+external APIs and answers the action. You cannot undo these writes.
+:::
+
+When **Execute writes** is on:
+
+- Each tool that writes runs as it does in a run.
+- Each write records the workflow as the thing that made it.
+- An **Action response** node shows the payload of its answer in its output.
+- **Set run labels** and **Remove run labels** write the labels of the test run. Picked deletes
+  these labels when the test run ends.
+- A wait node does not wait.
+- The test run stops after 60 seconds. It shows `Failed` and the nodes that it ran before
+  it stopped. The API gives the failure code `test_run_timed_out`.
+- If a tool runs when the test run stops, that tool shows `Failed`. Its write can
+  continue after the stop.
+
+The scopes that you must have do not change.
+
 ## What runs
 
-| Node                                                                                         | In a test run                                                                                         |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| Tool that reads, such as **Search leads** or an **External API** `GET` or `HEAD`             | Runs.                                                                                                 |
-| Tool that writes, such as **Create lead**, **Set lead labels** or an **External API** `POST` | Does not run. The result shows the input that it would send.                                          |
-| **Set run labels** and **Remove run labels**                                                 | Do not run, because Picked does not keep a test run. The result shows the input that they would send. |
-| **Get run**                                                                                  | Runs, and gives the ID of the test run, which starts with `test_`, and no labels.                     |
-| Condition                                                                                    | Runs, and shows the branch that it took.                                                              |
-| Wait                                                                                         | Does not wait.                                                                                        |
+| Node                                                                                         | In a test run                                                                                               |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Tool that reads, such as **Search leads** or an **External API** `GET` or `HEAD`             | Runs.                                                                                                       |
+| Tool that writes, such as **Create lead**, **Set lead labels** or an **External API** `POST` | Runs only when **Execute writes** is on. If it does not run, the result shows the input that it would send. |
+| **Get run**                                                                                  | Runs, and gives the ID of the test run, which starts with `test_`, and the labels of the test run.          |
+| Condition                                                                                    | Runs, and shows the branch that it took.                                                                    |
+| Wait                                                                                         | Does not wait.                                                                                              |
 
 A later node that reads the output of a skipped node gets no value.
 
@@ -58,18 +81,18 @@ a later visit shows its number, such as `visit 2`. Refer to the
 
 ## Result
 
-| Status      | Meaning                                          |
-| ----------- | ------------------------------------------------ |
-| `Succeeded` | The node did its work.                           |
-| `Skipped`   | The tool writes, so the test run did not run it. |
-| `Failed`    | The node failed, and shows the reason.           |
+| Status      | Meaning                                |
+| ----------- | -------------------------------------- |
+| `Succeeded` | The node did its work.                 |
+| `Skipped`   | The test run did not run the tool.     |
+| `Failed`    | The node failed, and shows the reason. |
 
 When a node fails, the test run stops at that node and shows `Failed`. If an edge leaves
 the error exit of the node, the test run continues on that edge as a run does, and can
 show `Completed`. Refer to the [workflow runs reference](/reference/dashboard/workflow-runs#run-status).
 
-Each node shows its input and its output. A test run does not show in **Runs**, and it
-does not create or change leads or labels.
+Each node shows its input and its output. A test run does not show in **Runs**. When
+**Execute writes** is off, it does not create or change leads or labels.
 
 ## Run variables
 

package/docs/reference/management-api/schema/action.md

@@ -6,13 +6,14 @@ generated: true
 
 # Action schema
 
-The operations and types that `action.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `action`
 
-Get an action by ID within a workspace.
+Reads an action.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 action(id: ID!, workspaceId: ID!): Action @auth
@@ -20,8 +21,9 @@ action(id: ID!, workspaceId: ID!): Action @auth
 
 ### `actions`
 
-List actions in a workspace. Filter by name with `search` (case-insensitive
-substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+Lists the actions in a workspace. `search` matches a case-insensitive substring of the name;
+`sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 actions(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: ActionSortKeys = NAME, reverse: Boolean = false): ActionConnection! @auth
@@ -31,7 +33,8 @@ actions(first: Int, after: String, last: Int, before: String, workspaceId: ID!,
 
 ### `actionCreate`
 
-Create a new action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates an action in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 actionCreate(input: ActionCreateInput!): ActionCreatePayload! @auth
@@ -39,7 +42,8 @@ actionCreate(input: ActionCreateInput!): ActionCreatePayload! @auth
 
 ### `actionUpdate`
 
-Update an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates an action.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 actionUpdate(input: ActionUpdateInput!): ActionUpdatePayload! @auth
@@ -47,7 +51,9 @@ actionUpdate(input: ActionUpdateInput!): ActionUpdatePayload! @auth
 
 ### `actionDelete`
 
-Delete an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes an action and the workflow it starts. An action that an experience references is not
+deleted, and comes back as an `IN_USE` user error.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 actionDelete(input: ActionDeleteInput!): ActionDeletePayload! @auth
@@ -59,37 +65,29 @@ actionDelete(input: ActionDeleteInput!): ActionDeletePayload! @auth
 
 ```graphql
 """
-A side effect triggered during experience flow execution. Workspace-
-scoped — actions are copied into a new workspace when the workspace is
-duplicated.
-
-Examples: API calls (`tracking/send-event`), analytics events
-(`segment/identify`), or SDK state updates (`features/toggle`). The
-shape of the side effect itself is encoded in the action's `key` and
-handled by the SDK plugin matching that key.
+A side effect that starts when a flow reaches it. Your application registers a handler for it by
+`key`.
 """
 type Action {
-  """Unique action identifier."""
+  """The ID of the action."""
   id: ID!
-  """Display name of the action."""
+  """The name of the action."""
   name: String!
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the action, unique within its workspace."""
   key: String!
-  """Optional description of what this action does."""
+  """A description of the action. Null when none is set."""
   description: String
-  """When this action was created."""
+  """When the action was created."""
   createdAt: DateTime!
-  """When this action was last updated."""
+  """When the action last changed."""
   updatedAt: DateTime!
-  """The workspace this action belongs to."""
+  """The workspace the action belongs to."""
   workspace: Workspace!
-  """
-  The workspace ID this action belongs to (denormalised for query convenience).
-  """
+  """The ID of the workspace the action belongs to."""
   workspaceId: ID
-  """Fields whose responses this action receives."""
+  """The fields whose answers the action receives."""
   fields(first: Int, after: String, last: Int, before: String): FieldConnection!
-  """The one workflow this action starts, or null when it starts none."""
+  """The workflow the action starts. Null when it starts none."""
   workflow: Workflow
 }
 ```
@@ -97,19 +95,15 @@ type Action {
 ### `ActionConnection`
 
 ```graphql
-"""
-Relay-style connection of actions, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of actions."""
 type ActionConnection {
-  """List of action edges."""
+  """The edges in this page."""
   edges: [ActionEdge!]!
-  """
-  Flat list of actions, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The actions in this page."""
   nodes: [Action!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of actions."""
+  """The number of actions across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -117,9 +111,9 @@ type ActionConnection {
 ### `ActionEdge`
 
 ```graphql
-"""Edge type for `ActionConnection`."""
+"""An action in a page of results."""
 type ActionEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The action."""
   node: Action!
@@ -129,17 +123,19 @@ type ActionEdge {
 ### `ActionCreateInput`
 
 ```graphql
-"""Input for `actionCreate`."""
+"""The input of `actionCreate`."""
 input ActionCreateInput {
-  """Workspace ID to create the action in."""
+  """The ID of the workspace to create the action in."""
   workspaceId: ID!
-  """Display name for the action."""
+  """The name of the action."""
   name: String!
-  """Unique key identifier for the action (stable across versions)."""
+  """
+  The stable identifier of the action, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Description of what this action does."""
+  """A description of the action."""
   description: String
-  """Ids of the fields whose responses this action receives."""
+  """The IDs of the fields whose answers the action receives."""
   fieldIds: [ID!]
 }
 ```
@@ -147,7 +143,7 @@ input ActionCreateInput {
 ### `ActionCreatePayload`
 
 ```graphql
-"""Payload returned by `actionCreate`."""
+"""The result of `actionCreate`."""
 type ActionCreatePayload {
   """The created action."""
   action: Action
@@ -157,19 +153,18 @@ type ActionCreatePayload {
 ### `ActionUpdateInput`
 
 ```graphql
-"""Input for `actionUpdate`. Omit a field to leave it unchanged."""
+"""The input of `actionUpdate`. Omit a field to keep its value."""
 input ActionUpdateInput {
-  """Action ID."""
+  """The ID of the action."""
   id: ID!
-  """Workspace ID the action belongs to."""
+  """The ID of the workspace the action belongs to."""
   workspaceId: ID!
-  """New display name."""
+  """The name of the action."""
   name: String
-  """New description."""
+  """A description of the action."""
   description: String
   """
-  Replacement set of field ids. Omit to leave the set unchanged; pass an empty
-  list to request nothing.
+  The IDs of the fields whose answers the action receives. Replaces the current set; an empty list clears it.
   """
   fieldIds: [ID!]
 }
@@ -178,7 +173,7 @@ input ActionUpdateInput {
 ### `ActionUpdatePayload`
 
 ```graphql
-"""Payload returned by `actionUpdate`."""
+"""The result of `actionUpdate`."""
 type ActionUpdatePayload {
   """The updated action."""
   action: Action
@@ -188,11 +183,11 @@ type ActionUpdatePayload {
 ### `ActionDeleteInput`
 
 ```graphql
-"""Input for `actionDelete`."""
+"""The input of `actionDelete`."""
 input ActionDeleteInput {
-  """Action ID."""
+  """The ID of the action."""
   id: ID!
-  """Workspace ID the action belongs to."""
+  """The ID of the workspace the action belongs to."""
   workspaceId: ID!
 }
 ```
@@ -200,13 +195,11 @@ input ActionDeleteInput {
 ### `ActionDeletePayload`
 
 ```graphql
-"""
-Payload returned by `actionDelete`. Returns `userErrors` when the action is in use.
-"""
+"""The result of `actionDelete`."""
 type ActionDeletePayload {
-  """ID of the deleted action (null when `userErrors` is non-empty)."""
+  """The ID of the deleted action. Null when `userErrors` is not empty."""
   deletedActionId: ID
-  """Validation errors. Empty array indicates success."""
+  """The reasons the action was not deleted. Empty on success."""
   userErrors: [ActionDeleteUserError!]!
 }
 ```
@@ -214,11 +207,9 @@ type ActionDeletePayload {
 ### `ActionDeleteUserErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `actionDelete`."""
+"""The reasons `actionDelete` refuses a delete."""
 enum ActionDeleteUserErrorCode {
-  """
-  The action is referenced by one or more experiences and cannot be deleted.
-  """
+  """An experience references the action."""
   IN_USE
 }
 ```
@@ -226,18 +217,18 @@ enum ActionDeleteUserErrorCode {
 ### `ActionDeleteUserError`
 
 ```graphql
-"""
-A user error from `actionDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
-"""
+"""A reason `actionDelete` did not delete an action."""
 type ActionDeleteUserError {
-  """Path to the input field that caused the error."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """A machine-readable code."""
   code: ActionDeleteUserErrorCode!
   """
-  Experiences that reference this action (present when `code` is `IN_USE`).
+  The experiences that reference the action. Null unless `code` is `IN_USE`.
   """
   referencingExperiences: [ReferencingExperience!]
 }
@@ -246,16 +237,13 @@ type ActionDeleteUserError {
 ### `ActionSortKeys`
 
 ```graphql
-"""
-Sort keys for `actions(...)`. Pair with `reverse: true` to flip the order
-(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `actions` can sort by. `reverse: true` flips each."""
 enum ActionSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```