PSA/ee/docs/plans/2026-01-07-dashboard-onboarding-checklist-substeps/PRD.md

# PRD — Dashboard Onboarding Checklist: Sub-steps + Updated Portal/Email Items

- Slug: `2026-01-07-dashboard-onboarding-checklist-substeps`
- Date: `2026-01-07`
- Status: Draft

## Summary

Update the MSP dashboard onboarding checklist to support sub-steps within a step card. Two existing steps will be re-framed (Customer Portal setup and Email configuration) to show multiple sub-items that must all be completed before the parent step is considered complete. Also fix the Secure Identity & SSO “Connect SSO” link.

## Problem

Today, each onboarding step is treated as a single boolean-ish completion state. Some setup areas require multiple distinct actions (e.g., portal domain + portal branding + inviting a portal user). Without sub-steps, the checklist can report “complete” too early or lacks guidance for what’s still missing, reducing its usefulness.

## Goals

- Support rendering and tracking sub-steps inside a checklist step card.
- Consider a step complete **only when all of its sub-steps are complete**.
- Update checklist content:
  - Replace “Client Portal Domain” with a broader “Set Up Customer Portal” step that includes:
    - Portal custom domain
    - Portal color and logo customizations
    - Invite your first contact to the portal
  - Replace “Managed Email Domain” with “Configure Email” that includes:
    - Configure inbound email
    - Configure outbound custom email domain
- Fix the Secure Identity & SSO “Connect SSO” link to `/msp/profile?tab=Single+Sign-On`.

## Non-goals

- Adding new backend configuration workflows beyond surfacing existing state.
- Changing the overall number of top-level onboarding panels (keep the existing set of top-level steps stable unless required for UX).
- Adding new analytics/metrics beyond what already exists for step completion and CTA clicks (unless requested).

## Users and Primary Flows

- **MSP admin** opens the dashboard and sees onboarding cards and/or the onboarding drawer.
- Admin clicks CTAs to complete setup tasks.
- Progress updates automatically as configuration is completed, with sub-step checkmarks reflecting what’s done and what remains.

## UX / UI Notes

- Sub-steps should be displayed within the relevant onboarding step card as a short list with completion checkmarks.
- Parent step status rules:
  - **complete**: all sub-steps complete
  - **blocked**: any sub-step blocked (surface the most relevant blocker message)
  - **in_progress**: at least one sub-step started/complete but not all complete
  - **not_started**: all sub-steps not started
- If a step has no sub-steps, behavior remains unchanged.
- Parent “progressValue” may be derived from sub-steps (e.g., 1/3, 2/3 → 33%, 67%) to keep existing progress visuals meaningful.

## Requirements

### Functional Requirements

1. The onboarding progress payload supports an optional list of sub-steps per step.
2. The dashboard checklist UI renders sub-steps with a checked/unchecked affordance.
3. The parent step status is derived from its sub-steps (or legacy single-step status when no sub-steps exist).
4. “Set Up Customer Portal” sub-steps resolve from existing system signals:
   - Portal custom domain: reuse current portal domain status signal.
   - Portal color/logo customization: infer from tenant branding settings.
   - Invite first contact: infer from portal invitation / client portal user existence.
5. “Configure Email” sub-steps resolve from existing system signals:
   - Inbound email: infer from inbound email provider configuration.
   - Outbound custom email domain: reuse managed email domain verification status.
6. The Secure Identity & SSO card CTA route is corrected to `/msp/profile?tab=Single+Sign-On`.

### Non-functional Requirements

- Keep the implementation lightweight and consistent with the existing `getOnboardingProgressAction` aggregation pattern.
- Ensure the UI gracefully handles missing `substeps` (backward-compatible rendering).

## Data / API / Integrations

- Extend `OnboardingStepServerState` to include `substeps?: OnboardingSubstepServerState[]`.
- Add/extend a small helper to derive parent step status + progress from sub-steps.
- Reuse existing actions/services where possible:
  - Portal domain: `getPortalDomainStatusAction`
  - Tenant branding: `tenant_settings.settings.branding` (via an existing action or direct query)
  - Portal invite/user: query `portal_invitations` and/or `users` (`user_type = 'client'`)
  - Inbound email: query `email_providers` (and/or vendor configs as needed)
  - Outbound domain: `@ee/lib/actions/email-actions/managedDomainActions.ts`

## Security / Permissions

- No new permissions surfaces; onboarding progress continues to require an authenticated MSP session.
- Data derived should not leak sensitive secret material; only counts/statuses and non-sensitive metadata are included.

## Observability

- Keep existing `onboarding_step_completed` event semantics (fires when the parent step transitions to `complete`).
- (Optional) Decide whether to add sub-step completion events later; not required for this scope.

## Rollout / Migration

- No data migrations expected.
- Roll out as a UI + server aggregation update; ensure older clients tolerate missing `substeps` and newer clients tolerate empty lists.

## Open Questions

Resolved (2026-01-07):

1. “Portal color and logo customizations” is complete when **any** customer portal configuration exists (any configuration at all).
2. “Invite your first contact to the portal” is complete when **a portal invite exists**.
3. “Configure inbound email” is complete when **any provider row exists**.

## Acceptance Criteria (Definition of Done)

- The onboarding checklist shows sub-steps for the Customer Portal and Email cards.
- Each sub-step has an accurate checked/unchecked state based on system signals.
- Parent card only shows “Complete” when all of its sub-steps are complete.
- The Secure Identity & SSO CTA navigates to `/msp/profile?tab=Single+Sign-On`.
- Existing steps without sub-steps behave exactly as they do today.