Set Phase Transitions

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).

2. Permissions: Ensure your token has the necessary permissions.

3. Pipe ID: The ID of the pipe that owns the phase.

4. Phase IDs: The phase you are updating, and each phase it should connect to. A target must belong to the same pipe, must not be the draft phase, and must not be the phase itself.

Step 1: Find the phase IDs

1. Via Pipefy UI:
   1. Open the pipe settings for the phase.
   2. The URL includes the phase ID: https://app.pipefy.com/pipes/1234/settings/phases/123456.
   3. Phase ID = 123456 (the number after /phases/).
2. Via GraphQL Query
   1. Check on our Get resource IDs page.

Step 2: Replace the outgoing transitions

jumpTargetIds on updatePhase replaces the whole outgoing set. Omit the argument to leave the current transitions unchanged. Send an empty list to clear them.

next_phase_ids in the response lists only destinations with a higher index. A destination with a lower index is returned in previous_phase_ids. Together those two fields are the full outgoing set. Types::Phase does not expose a jumpTargetIds field.

mutation {
  updatePhase(input: {
    id: 123456,
    name: "Review",
    jumpTargetIds: [123457, 123458]
  }) {
    phase {
      id
      next_phase_ids
      previous_phase_ids
    }
  }
}

Arguments Breakdown

• id: the phase you are updating
• name: the phase name. updatePhase requires it even when you only change transitions
• jumpTargetIds: the phase IDs that replace every outgoing transition. [] clears them

Example Response

{
  "data": {
    "updatePhase": {
      "phase": {
        "id": "123456",
        "next_phase_ids": [123458],
        "previous_phase_ids": [123457]
      }
    }
  }
}

An id from another pipe, a draft phase, or the phase itself is rejected and the previous transitions stay in place:

{
  "data": {
    "updatePhase": null
  },
  "errors": [
    {
      "message": "Validation failed: Jump targets are not possible destinations: 999999",
      "extensions": {
        "code": "RECORD_INVALID"
      }
    }
  ]
}

Step 3: Create a phase without neighbor links

createPhase links the new phase to its neighbors by default. Pass connectNeighbors: false to skip that linking in both directions. Omit the argument, or send null, to keep today's behavior. The start form jump is not a neighbor transition: when this phase is the pipe's only phase, the start form still jumps to it.

mutation {
  createPhase(input: {
    pipe_id: "1234",
    name: "Review",
    connectNeighbors: false
  }) {
    phase {
      id
      next_phase_ids
      previous_phase_ids
    }
  }
}

Arguments Breakdown

• pipe_id: the pipe that will own the phase
• name: the phase name
• connectNeighbors: false creates the phase with no neighbor jumps. The start form still jumps to it when it is the pipe's only phase. The default is true

Example Response

{
  "data": {
    "createPhase": {
      "phase": {
        "id": "123459",
        "next_phase_ids": [],
        "previous_phase_ids": []
      }
    }
  }
}

Key Notes

• jumpTargetIds is a replacement, not an addition. Send every destination you want to keep.
• Unknown target ids are rejected. They are not dropped.
• Reordering phases is not part of updatePhase.