Tours — Reference
The Tours surface is the guided-walkthrough plane for SGEN. It owns the catalog of product tours configured on a site, the per-tour ordered step sequence, the anchor selectors that pin each step to an on-page element, the trigger rules that decide when a tour first fires for a visitor, the completion-tracking layer that records progress, and the dismissal-preference layer that respects a visitor's "don't show me this again" signal. Anything that asks "introduce a capability with a sequence of in-page callouts" traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, extending the step model, or scoping an onboarding program. Customer-facing how-tos for authoring tours live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Tours live under the Tours module in SG-Admin. The module renders four primary views — the tour list (every configured tour with state and trigger summary), the tour editor (the ordered step sequence with per-step anchor, copy, and navigation controls), the trigger-rules editor (the conditions that decide when a tour fires), and the completion-stats view (per-tour start, advance, complete, and dismiss counts).
The module is paired by convention with the Pages, Users, and Activity Log surfaces. Anchor selectors reference DOM elements rendered by page records; trigger rules can reference user records by role; completion records reference user records by id; every tour state transition writes an Activity Log entry. The Tours module owns the tour and the step sequence; the consuming surfaces own the records the trigger rules and the anchors point at.
A second surface — the runtime tour engine — is the read-side contract surfaced to the public frontend. When a page loads, the engine asks the Tours surface "is any tour pending for this visitor on this page" and receives either a tour definition (ordered steps, anchors, copy, completion-state) or nothing. The engine renders the first un-completed step, listens for advance / dismiss interactions, persists progress to the completion-tracking layer after each interaction, and stops when the sequence is exhausted or the visitor dismisses.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Tours
- URL prefix:
/sg-admin/tours/ - View templates:
application/views/Admin/Tours/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Tours [+ New tour] │├──────────────────────────────────────────────────────────────────────┤│ Tour Steps Trigger Completion ││ ───────────────────────── ───── ──────────────── ──────────────││ first-time-builder 7 First admin login 68% complete ││ pricing-page-walkthrough 4 URL match /pricing 42% complete ││ new-dashboard-callouts 5 Role: editor — ││ trial-day-3-followup 3 Trial day == 3 12% complete ││ ││ [⋯ Edit] [⋯ Trigger rules] [⋯ Stats] [⋯ Pause] [⋯ Archive] │└──────────────────────────────────────────────────────────────────────┘Actions
The Tours surface exposes the following operations. Each is described by what it does to the data and to the runtime contract, not by its internal method name.
List and search
Returns the tour records visible to the current operator, paginated, with name, step count, trigger summary, current completion rate, and lifecycle state columns. Supports column sort, free-text filter on tour name and trigger rule, and per-page count. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.
Create tour
Opens an empty tour form. Required fields at minimum: tour name, ordered step sequence (each step carries an anchor selector, a title, body copy, and navigation controls), and at least one trigger rule. Optional fields cover a max-runtime cutoff, a per-visitor frequency cap (default: show once per visitor per tour), and a dismissal-respect window (how long to honor a dismissal before considering the tour eligible again). On submit, the surface validates that the step sequence is non-empty, that anchor selectors are syntactically valid, and that trigger rules are well-formed, persists the record, and returns the new identifier.
Edit tour
Loads an existing tour into the same form shape used for create, pre-populated. Submit replaces the stored configuration. Edits to the step sequence on a live tour do not retroactively reset captured completion progress — visitors mid-tour continue from their last completed step, even if the upstream steps have been rewritten. The surface surfaces a soft warning on this case.
Configure trigger rules
Trigger rules are an ordered list of conditions. Each rule pairs a match condition with an outcome (fire the tour, do not fire). Conditions cover: URL match on the current page, user role, user trial-day number, custom user attribute (set elsewhere in SG-Admin), and a date / time window. The runtime engine walks rules in order — the first matching rule decides whether the tour fires; if no rule matches, the tour does not fire.
Configure step anchors
Each step carries an anchor selector that pins the callout to an on-page element. The selector syntax supports CSS-like selectors plus a small named-anchor catalog for known SGEN UI regions (@sg-admin-sidebar, @page-builder-canvas, etc.). When the anchor cannot be resolved on the current page, the runtime engine surfaces the step in a default centered-modal position and records an anchor-miss event on the completion-tracking layer.
Start tour
Transitions the tour from draft to live. The runtime engine begins evaluating trigger rules for new visitor loads. Visitors who have not yet completed or dismissed the tour become eligible.
Pause tour
Suspends the runtime engine for this tour. New visitors do not see the tour during the pause; visitors mid-tour are paused at their current step and resume at the same step when the tour resumes.
Resume tour
Reverses a pause.
Conclude tour
Transitions the tour from live to done. The runtime engine stops surfacing the tour for new visitors. Completion progress is frozen. The tour can be re-opened from done to live via an explicit transition, which resets the per-visitor frequency cap.
Record completion event
The write-side contract the runtime engine calls. Inputs: tour id, visitor id, step index, event type (start, advance, complete, dismiss, anchor-miss). Output: the next eligible step (or null when the sequence is exhausted). The contract is append-only — events cannot be edited or deleted.
View completion stats
Returns per-step start, advance, complete, dismiss, and anchor-miss counts for a single tour. Used by operators to identify which step is causing drop-off and to refine copy or anchors accordingly.
Reset visitor progress
A targeted write path that clears completion progress for a single visitor on a single tour. Used when an operator needs to re-show a tour to a specific visitor (typically for testing or for a support-driven re-onboarding). The surface validates that the calling operator has explicit consent to act on the visitor's behalf.
Archive tour
Marks the record inactive without removing it from the database. Archived tours disappear from the default list view but remain queryable via the archive filter. Captured completion data is retained.
Permanent delete
Hard-removes the record. Available only after an archive. Captured completion data is removed with the record. This path is irreversible.
Data model
A tour 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 |
|---|---|---|
id | integer | Primary key. Stable across edits. |
slug | string | Unique. Used in the completion-tracking key. |
name | string | Display name. Not unique. |
steps | ordered list | Each step: { anchor, title, body, advance_label, dismiss_label }. Order preserved. |
trigger_rules | ordered list | Each rule: { condition, fire_or_skip }. Order preserved. |
frequency_cap | enum | once_per_visitor (default), once_per_session, every_load. |
dismissal_respect_days | integer | How long to honor a dismissal. |
max_runtime_days | integer | Optional. Auto-concludes past the cutoff. |
lifecycle_state | enum | draft, live, paused, done, archived. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
Completion-record shape: completion progress is stored on a separate completion record keyed by tour id and visitor id. Each record carries the highest step index reached, a per-event log (start, advance, complete, dismiss, anchor-miss timestamps), and the dismissal-respect deadline if dismissed.
TOUR RECORD├── id integer primary key├── slug string unique completion-key prefix├── name string display├── steps ordered [{anchor, title, body, advance, dismiss}]├── trigger_rules ordered [{condition, fire_or_skip}]├── frequency_cap enum once_per_visitor (default) | per_session | every_load├── dismissal_respect_days integer honor-dismissal window├── max_runtime_days integer optional auto-conclude├── lifecycle_state enum draft | live | paused | done | archived└── timestamps created_at, updated_at↓ per visitor per interactionCOMPLETION RECORDper (tour_id, visitor_id): max_step_index, event log, dismissed_until(append-only event log; max-step + dismissed_until mutable)↓ aggregateCOMPLETION STATSper-step: start_count, advance_count, complete_count,dismiss_count, anchor_miss_countPermissions
Access to the Tours surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Tours surface.
Layer 2 — per-action capability. Within SG-Admin, each Tours 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 |
|---|---|---|---|
| List tours | ✔ | ✔ | ✔ |
| Create tour | ✔ | ✔ | — |
| Edit tour | ✔ | ✔ | — |
| Configure trigger rules | ✔ | ✔ | — |
| Start / pause / resume | ✔ | ✔ | — |
| Conclude tour | ✔ | ✔ | — |
| View completion stats | ✔ | ✔ | ✔ |
| Reset visitor progress | ✔ | — | — |
| Archive | ✔ | — | — |
| Restore archived | ✔ | — | — |
| Permanent delete | ✔ | — | — |
Self-protection rules. A tour cannot reference its own slug in a trigger rule (no recursive triggering). A tour with a frequency cap of every_load cannot be combined with a once_per_visitor dismissal-respect window — the configuration is self-contradictory. The surface returns a structured rejection in each case.
Audit. Every write — create, edit, start, pause, resume, conclude, reset, archive, restore, delete — emits an Activity Log entry. Visitor-progress resets carry the target visitor identifier on the audit entry, since this action affects an external party.
PAGE LOAD│ inputs: visitor_id, current_url, role, attributes▼┌───────────────────────────┐│ Find candidate tours │ active + matching trigger-rule top-to-bottom└─────────────┬─────────────┘│ candidates found▼┌───────────────────────────┐│ Resolve completion state │ skip if completed; skip if within dismissal window└─────────────┬─────────────┘│ eligible tour selected▼┌───────────────────────────┐│ Render step N │ N = max_step_index + 1 (or 0 first time)│ resolve anchor │ anchor-miss → centered fallback + log event└─────────────┬─────────────┘│ visitor interaction▼record event (advance | dismiss | complete)│▼update completion record│▼return next step (or null when sequence exhausted)Related references
- Pages — Reference. Anchor selectors resolve against the DOM rendered by page records. Page deletion mid-tour surfaces anchor-miss events on the completion-tracking layer.
- Users — Reference. Trigger rules can reference user records by role and by custom attribute. Soft-deleted users do not receive new tour starts; existing in-progress completion records are preserved.
- Activity Log — Reference. Every tour lifecycle transition emits a one-line entry. Visitor-progress resets carry the target visitor on the audit entry.
- Settings — Reference. Owns the role definitions referenced by the capability map and the Activity Log retention policy that governs audit-entry lifetime.
- A/B Testing — Reference. Tour variants (testing two versions of the same onboarding sequence) are authored through the Experiments module pointing at two distinct tour records — the Tours surface itself does not carry variant semantics.
/docs/tours.