Onboarding — Reference
The Onboarding surface is the first-login user experience plane. It owns the welcome flow, the role-aware path selection, per-step completion tracking, and the dismissal preferences that determine when (or whether) the flow appears again. Anything that drives a new operator from their first sign-in to their first productive session traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or wiring a new role path into the flow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Onboarding lives under the Onboarding module in SG-Admin. The module renders three primary views — the flow editor (per-step content and visibility rules), the path manager (role-to-flow mapping), and the completion report (per-user progress and drop-off points) — and exposes a small set of write operations for step add, step edit, step reorder, step archive, path edit, and per-user reset.
The module is paired by convention with the public-facing flow runner. SG-Admin owns the configuration; the flow runner consumes that configuration on first login and renders the welcome screens. Completion is tracked per-step, per-user, so resumed sessions pick up where the user left off.
A second surface — per-user dismissal preferences — sits adjacent to the main module and stores the user's choice to dismiss the flow entirely, dismiss a single path, or snooze the flow until a future date. Dismissal preferences are independent of completion — a user can dismiss an unfinished flow and the dismissal is honored.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Onboarding
- URL prefix:
/sg-admin/onboarding/ - View templates:
application/views/Admin/Onboarding/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Onboarding → Path: Administrator │├──────────────────────────────────────────────────────────────────────┤│ Step Title Type Required Completion ││ ──── ──────────────────────── ────────── ──────── ────────── ││ 1 Welcome to SGEN screen ✔ 98% ││ 2 Set your display name form ✔ 96% ││ 3 Invite your team form — 42% ││ 4 Connect your domain link-out — 31% ││ 5 Tour the dashboard screen — 58% ││ 6 Read the launch checklist link-out — 24% ← drop ││ ││ [+ Add step] [Reorder] [Preview path] │└──────────────────────────────────────────────────────────────────────┘Actions
The Onboarding surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
Read flow
Returns the configured paths, the steps within each path, and the visibility rules that determine which path a given user sees. The response shape is suitable for direct binding to the flow editor view.
Add a step
Creates a new step within a path. Required at minimum: title, type (screen, form, link-out), position. Optional: body, required flag, prerequisite step reference. On submit, the step is appended at the requested position; subsequent steps shift down.
Edit a step
Replaces the title, body, type, or visibility rule for a single step. The completion tracking continues against the same step identifier — edits do not reset completion.
Reorder steps
Replaces the stored ordering for a path's steps with a new sequence. Reorder is a single write of the full sequence — partial position swaps are not supported.
Archive a step
Removes a step from the active flow without deleting historical completion data. Archived steps remain in the data store for audit and re-activation; the flow runner skips them.
Set role-to-path mapping
Stores the mapping from operator role to onboarding path. The default mapping ships with one path per default role — Administrator path, Editor path, Viewer path. Custom roles can be mapped to any existing path or to a custom path created for that role.
Set visibility rule
Stores an optional condition that gates the flow for a given user. Conditions cover whether the user is the site's first-ever sign-in, whether the user was invited by another operator, whether the site has any published content yet, and similar context flags.
Mark a step complete (user-facing)
Records that a single user completed a single step. Called by the flow runner when the user submits the step's form or dismisses the step's screen. The action is idempotent — repeated calls return the existing record.
Reset per-user progress
Clears the completion record for a single user, returning their flow to "not started." Used during operator support — when a user requests a fresh walk-through of the welcome flow.
Dismiss the flow (user-facing)
Records the user's choice to dismiss the flow. Supports three modes — dismiss this path, dismiss all paths, snooze until a date. The flow runner reads this preference before rendering and skips when dismissed.
Read completion report
Returns per-step completion percentages across all users for a path, drop-off counts per step, and the median time-to-complete for the full path.
Data model
A flow record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
path_id | integer | Primary key for a path. |
path_slug | string | Identifier for matching to a role. |
name | string | Display label. |
visibility_rule | object | Optional condition for showing this path. |
created_at | timestamp | Set on create. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
step_id | integer | Primary key. |
path_id | integer | Foreign key into the path table. |
title | string | Visible header. |
body | string | Long-form text or markup. |
type | enum | One of screen, form, link-out. |
position | integer | Sort key. |
required | boolean | When true, the flow cannot be completed until this step is. |
prerequisite_step_id | integer | Optional. When set, this step is locked until the prerequisite is complete. |
archived | boolean | When true, the flow runner skips this step. |
| Field | Type | Notes |
|---|---|---|
user_id | integer | Foreign key. |
step_id | integer | Foreign key. |
completed_at | timestamp | Set on first complete. |
data | object | Optional. Form responses captured during the step. |
| Field | Type | Notes |
|---|---|---|
user_id | integer | Foreign key. |
dismissal_scope | enum | One of path, all. |
path_id | integer | Foreign key when scope is path. |
snooze_until | timestamp | Optional. When set, the flow resumes after this time. |
PATH RECORD├── path_id integer primary key├── path_slug string match key for roles├── name string├── visibility_rule object└── timestampsSTEP RECORD├── step_id integer primary key├── path_id (FK)├── title · body├── type screen | form | link-out├── position integer├── required boolean└── prerequisite_step_id integer (optional)PER-USER COMPLETION├── user_id · step_id (FK)├── completed_at└── data (form responses)PER-USER DISMISSAL├── user_id (FK)├── dismissal_scope path | all├── path_id (when scope=path)└── snooze_until optionalPermissions
Access to the Onboarding surface is gated at two layers.
Layer 1 — admin gate. Every administrative action under SG-Admin passes through the platform's standard admin access check at request entry. The user-facing actions (mark complete, dismiss the flow) pass through a separate authenticated-user gate.
Layer 2 — per-action capability. Within SG-Admin, each Onboarding admin action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| Read flow | ✔ | ✔ | ✔ |
| Add a step | ✔ | — | — |
| Edit a step | ✔ | — | — |
| Reorder steps | ✔ | — | — |
| Archive a step | ✔ | — | — |
| Set role-to-path mapping | ✔ | — | — |
| Set visibility rule | ✔ | — | — |
| Reset per-user progress | ✔ | ✔ | — |
| Read completion report | ✔ | ✔ | ✔ |
Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.
Self-protection rules. A user cannot reset another user's progress without the reset capability. A user cannot edit another user's dismissal preference at all — dismissal is strictly self-scoped.
Audit. Every administrative write — step add, edit, reorder, archive, role mapping, visibility rule, per-user reset — emits an Activity Log entry. Per-user completion writes are recorded in a separate completion stream rather than the Activity Log, to avoid flooding the log with per-step events.
USER FIRST LOGIN│▼┌───────────────────────────┐│ Read dismissal preference │ dismissed-all? skip│ │ snoozed? respect until└─────────────┬─────────────┘│ not dismissed▼┌───────────────────────────┐│ Resolve path from role │ role → path mapping└─────────────┬─────────────┘▼┌───────────────────────────┐│ Check visibility rule │ conditions met? continue└─────────────┬─────────────┘│ visible▼┌───────────────────────────┐│ Read completion progress │ first incomplete step└─────────────┬─────────────┘▼render next step│▼user completes OR dismisses│▼state persisted(resume on next login)Related references
- Users — Reference. Onboarding paths are mapped to user roles. Role assignments come from Users; the mapping is owned by this module.
- Settings — Reference. Hosts the role definitions and the global "show onboarding to new users" toggle. Changes there reshape the Onboarding visibility rules.
- Notifications — Reference. Some onboarding paths trigger a follow-up notification (welcome email, day-three check-in). Those messages are owned by Notifications; the trigger is wired here.
- Activity Log — Reference. Records administrative writes to Onboarding configuration.
- Custom Fields — Reference. Form-type steps can capture data into Custom Fields on the user record. The field bindings are configured here.
- Recently Viewed — Reference. Pairs with Onboarding for returning users — Recently Viewed surfaces last-visited content; Onboarding surfaces uncompleted steps.
/docs/onboarding.