Configure workflow stages

The IDDT workflow describes the path every plan takes from draft to registrar_confirmed. Workflows are tenant-scoped — each institution configures its own stages, escalation rules, and approval gates. This article covers the admin console for configuring those stages, the constraints the platform enforces on a configuration change, and how to roll out a workflow change without disrupting plans already mid-route.

Open the workflow configuration

Sign in with your administrator role and pick Workflow config from the admin rail. You will see the current configuration rendered as a directed graph:

• Each node is a stage.
• Each edge is a transition. Edges are labeled with the trigger (advisor_approves, committee_returns, etc.).
• A small badge next to each stage shows the count of plans currently resident in that stage.

The graph is the source of truth — every page in the rest of the platform reads from it. Changing the graph changes what advisors and students see in their workspaces.

Anatomy of a stage

Click any stage node to open its detail panel. Every stage has:

• A slug (machine name, never changes after creation).
• A display label shown to users.
• A role gate — who can move a plan into and out of the stage.
• An SLA (target time the plan should spend in the stage).
• An escalation path (who is notified when SLA is breached).

A stage with no inbound edges and no outbound edges is unreachable. The console warns you about unreachable stages and offers to remove them.

Add a new stage

Click Add stage in the action bar. The new-stage form asks for the slug, the display label, the role gate, and the SLA. Submit the form and the stage appears as a disconnected node in the graph.

Connect the new stage by clicking Add transition:

1. Pick the source stage.
2. Pick the target stage (the new one).
3. Name the trigger — keep names short and verb-led (advisor_assigns_committee rather than advisorAssignsCommitteeMember).
4. Pick the role gate for the transition. The transition gate must be a subset of the target stage's role gate; the console enforces this constraint and explains why it cannot be relaxed.

Save. The transition appears in the graph immediately.

Inbound vs outbound role gates

The platform distinguishes between who can move a plan into a stage (the inbound gate, owned by the transition) and who can act on a plan while it sits in the stage (the outbound gate, owned by the stage itself). Advisors can leave comments on a pending_advisor_review plan without being able to move it forward; the outbound gate is broader than the inbound gate by design.

Validate before you publish

A workflow change is not live until you click Publish. Before publish the console runs a validation pass:

• Every stage must be reachable from draft.
• Every terminal stage must be marked terminal (no orphan dead-ends).
• Every stage with plans currently resident must remain present in the graph.
• Every transition must have a role gate.

If any of these fail, the console blocks publish and shows the specific failures inline. Fix them and try publish again.

What "publish" actually changes

Publish does two things:

1. The new graph becomes the active one for new plan transitions.
2. A new revision is appended to the workflow's version history.

Plans that are already in flight keep their original graph until they transition. So a plan that was already in committee_review when you publish a new graph stays on the old graph for as long as it sits in committee_review; the next transition uses the new graph.

This dual-graph behavior is intentional. It lets you ship a workflow change without orphaning a plan that was already mid-route — the plan finishes on the graph it started on.

Roll out a change carefully

A workflow change that affects role gates is the most likely to cause confusion. Before publishing:

1. Announce the change in the tenant's support channel (email, Slack, or whichever mechanism your institution uses).
2. Hold the publish for at least one business day after the announcement so advisors and committee members can ask questions.
3. After publish, watch the Plans in flight counter on each stage for the next 48 hours. A spike in any stage usually means the transition gate is more restrictive than people expected.

If the change goes badly, click Revert to previous revision on the version history. Revert is non-destructive — plans that have already transitioned on the new graph stay on it.

What to do next

Once your workflow is stable, move on to Audit a plan's history — the audit view shows every transition with timestamps, role, and the acting user, which is the right surface for answering compliance questions about a specific plan.