284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
134 lines
6.1 KiB
Markdown
134 lines
6.1 KiB
Markdown
# PRD — Entra Settings Guided Flow Layout
|
|
|
|
- Slug: `entra-settings-guided-flow-layout`
|
|
- Date: `2026-02-20`
|
|
- Status: Draft
|
|
- Edition: Enterprise only (`NEXT_PUBLIC_EDITION=enterprise`)
|
|
|
|
## Summary
|
|
|
|
Restructure the Entra integration settings screen into two explicit modes:
|
|
|
|
1. Onboarding mode: guided, hard-gated sequence (Connect → Discover → Map → Initial Sync).
|
|
2. Maintenance mode: post-initial-sync operations view for recurring sync and health checks.
|
|
|
|
Keep existing Entra backend behavior, but improve UX clarity by exposing one current-step primary action at a time during onboarding and a stable operations surface afterward.
|
|
|
|
## Problem
|
|
|
|
The settings page currently presents `Run Discovery`, `Run Initial Sync`, and `Sync All Tenants Now` in the same visual tier. This implies equivalent usage order, but the real workflow is sequential: connect, discover, map, then sync.
|
|
|
|
Users can click actions out of sequence, leading to confusion about what should happen next and why certain actions appear disabled.
|
|
|
|
After initial setup, there is also no clear transition to an operational maintenance experience, so users still see setup-era controls without a maintenance-first framing.
|
|
|
|
## Goals
|
|
|
|
1. Present Entra onboarding as a clear, deterministic process.
|
|
2. Enforce hard-gated step progression in the UI.
|
|
3. Keep operational/manual sync actions available, but visually separate from onboarding.
|
|
4. Add an explicit maintenance mode after first initial sync run.
|
|
5. Reuse existing backend routes/actions and existing test coverage where possible.
|
|
|
|
## Non-goals
|
|
|
|
1. No Entra schema changes.
|
|
2. No Temporal workflow contract changes.
|
|
3. No new feature flags.
|
|
4. No redesign of mapping-table internals beyond placement/context.
|
|
|
|
## Users and Primary Flows
|
|
|
|
1. MSP admin connects Entra provider.
|
|
2. User runs discovery once connected.
|
|
3. User confirms tenant mappings.
|
|
4. User runs initial sync.
|
|
5. UI transitions to maintenance mode once initial sync exists.
|
|
6. User performs ongoing operations (`Sync All Tenants Now`, refresh discovery, review queue/history) from maintenance mode.
|
|
|
|
## UX / UI Notes
|
|
|
|
1. Add a step-progress header showing:
|
|
1. Connect
|
|
2. Discover
|
|
3. Map
|
|
4. Sync
|
|
2. Add a `Current Step` card with one primary CTA only (hard-gated).
|
|
3. Move `Sync All Tenants Now` to a separate `Ongoing Operations` section.
|
|
4. Keep mapping table visible and contextualize it as Step 3 (Map).
|
|
5. Keep status/connection diagnostics visible (including CIPP server/direct tenant details).
|
|
6. Add mode-level heading/treatment so users can distinguish Setup vs Ongoing Operations.
|
|
7. In maintenance mode, prioritize operational cards:
|
|
1. Health summary/status
|
|
2. Ongoing operations CTA group
|
|
3. Sync history / queue review
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
1. Derive guided step state from existing status signals (`status`, `lastDiscoveryAt`, `mappedTenantCount`) without new backend APIs.
|
|
2. Derive page mode (`onboarding` vs `maintenance`) from existing sync signals (existing sync history/run data), without schema changes.
|
|
3. Render only one onboarding primary action at a time:
|
|
1. Not connected: show connect options.
|
|
2. Connected without discovery: show `Run Discovery`.
|
|
3. Discovered without confirmed mappings: direct user to mapping confirmation.
|
|
4. Mapped tenants present: show `Run Initial Sync`.
|
|
4. Hard-gate future onboarding actions (no same-tier multi-action row).
|
|
5. Wire `Run Discovery` CTA to existing `discoverEntraManagedTenants` action.
|
|
6. Wire `Run Initial Sync` CTA to existing `startEntraSync({ scope: 'initial' })` path.
|
|
7. In maintenance mode, suppress onboarding-focused CTA emphasis and prioritize ongoing operations controls.
|
|
8. Keep `Sync All Tenants Now` behavior unchanged but place it in `Ongoing Operations`.
|
|
9. Preserve existing status panel fields and refresh/disconnect behaviors.
|
|
10. Preserve existing mapping table behaviors (`confirm`, `skip`, `import`, `remap`).
|
|
11. Preserve existing flag-gated visibility logic for optional advanced sections.
|
|
|
|
### Non-functional Requirements
|
|
|
|
1. No regression in existing Entra settings RBAC/flag checks.
|
|
2. UI state transitions should be deterministic from loaded status + mapping summary.
|
|
3. Keep implementation localized to Entra settings UI and its unit tests.
|
|
4. Mode switching must be predictable and not oscillate across refreshes for stable status data.
|
|
|
|
## Data / API / Integrations
|
|
|
|
1. Reuse existing server actions:
|
|
1. `discoverEntraManagedTenants`
|
|
2. `startEntraSync`
|
|
3. `getEntraIntegrationStatus`
|
|
4. `getEntraSyncRunHistory` (for maintenance-mode transition signal)
|
|
2. No new routes required.
|
|
3. No data model changes required.
|
|
|
|
## Security / Permissions
|
|
|
|
1. Continue to rely on existing route/action permission enforcement.
|
|
2. No client-portal access changes.
|
|
|
|
## Observability
|
|
|
|
1. No new observability scope.
|
|
2. Reuse existing sync feedback and sync history panel for run visibility.
|
|
3. Maintenance mode should surface last-run context from existing sync history data already available.
|
|
|
|
## Rollout / Migration
|
|
|
|
1. Ship behind existing Entra UI flag behavior.
|
|
2. No data migration required.
|
|
|
|
## Open Questions
|
|
|
|
1. Should Step 3 use a dedicated `Review Mappings` CTA (scroll/focus) or instruction-only guidance?
|
|
2. Should `Run Initial Sync` remain available both in guided Step 4 and mapping-confirm flow, or should one path become canonical?
|
|
3. Should maintenance mode expose `Run Discovery` as a secondary operation by default, or keep it behind an overflow/details affordance?
|
|
|
|
## Acceptance Criteria (Definition of Done)
|
|
|
|
1. The settings page no longer shows discovery/initial/all-tenants actions as same-tier onboarding controls.
|
|
2. Onboarding surface shows one current-step primary action based on progress state.
|
|
3. Discovery and initial-sync actions are clickable only when their prerequisites are met.
|
|
4. `Sync All Tenants Now` is visibly separated under operations/maintenance context.
|
|
5. Once initial sync has run, UI shifts to maintenance-mode emphasis and no longer presents setup CTAs as primary.
|
|
6. Existing status details, mapping flows, and advanced-flag panels continue to work.
|
|
7. Existing relevant tests continue to pass; only a small set of focused new UI tests is added.
|