Move through phases

Phase moves change the phase field on the onboarding and write a PhaseTransition entry to the audit log. Every move runs the same pipeline: validate, write the transition, fire notifications, fire webhooks. There’s no “soft” move that skips any of it.

Who can move an onboarding

The CSM is whoever holds the csm field on the onboarding. A member counts as “assigned” if they own any open task in the current phase.

Advance one phase

1. Open the onboarding from the Workbench or Customers > [name] > Onboardings.
2. Click Advance phase in the header. The next phase in the workspace sequence appears in the confirmation dialog.
3. Add an optional note. The note lands on the PhaseTransition entry, not on the task list.
4. Confirm. The onboarding moves, the previous phase locks for editing on customer-facing views, and the new phase opens.

If the previous phase has open tasks, you see a prompt: leave them as carryover (they stay open, attributed to the prior phase) or mark them complete on the spot. Pi treats carryover tasks as overdue once you advance.

Send back to a previous phase

Click the phase pill in the header and pick an earlier phase. You’ll be required to enter a reason. The reason is non-optional because the field surfaces in the customer’s portal under “what happened” and in the audit log.

Common reasons:

• Scope changed: customer expanded the integration mid-UAT.
• Failed UAT: a test case didn’t pass, work resumes in Integration.
• Blocked on customer: Pause the onboarding instead; see onboarding states.

Skip a phase

Admins only. Use Phase > Jump to… and pick any later phase. Tasks in the skipped phase stay open and Pi flags them as orphaned. Skipping is the right move when a phase doesn’t apply (e.g. a free trial with no Integration work), and the wrong move when work in that phase is incomplete.

What fires on every move

• A PhaseTransition record with from_phase, to_phase, actor, reason, timestamp.
• An email to the customer’s primary contact if the new phase is customer-facing.
• A Slack notification in the customer’s channel if Slack is connected.
• An onboarding.phase_changed webhook with the full transition payload.

Gotchas

• Email notifications respect the customer’s portal settings. If the customer has muted phase updates, no email goes out, and the audit log records notification_skipped: muted.
• A move with zero open tasks in the new phase looks empty on the kanban. Apply a phase template at move time to populate it.
• You can’t undo a move. To reverse one, send back with a reason.

Related

• The phase model
• Audit log
• Onboarding states