WEB-ADMIN: Guided Setup Wizard

[roywanyaga]

Objective

Provide a multi-step wizard that guides administrators through initial system setup, creating locations, organizations, care teams, users, and assignments in one cohesive flow.

User Story

As an administrator setting up a new deployment,
I want to follow a guided wizard to create my org structure and users,
So that I can get the system ready for use without navigating multiple screens.

Key Deliverables

• 5-step wizard: Locations → Organizations → CareTeams → Users → Assignments + Review
• Reuse of entity forms in wizard mode (emit Bundle entries instead of POSTing)
• Progress indicator and navigation
• Draft state persistence in sessionStorage
• Two-phase commit: Bundle transaction for non-user resources, then per-user creation
• Review step showing complete resource graph
• Partial failure recovery for user creation

Acceptance Criteria

• Wizard guides through all 5 steps in order
• Entity forms work in both standalone and wizard modes
• Draft state persists within browser session
• Review step shows all resources to be created
• Submit creates non-user resources in atomic Bundle transaction
• Users created via custom endpoint with CareTeam and PractitionerRole assignments
• Partial user creation failure shows which succeeded/failed
• Failed users can be retried individually

Cross-Repository Tasks

Web Portal (ohs-player-reference-web-portal)

• Wizard route and step framework
• Progress indicator component
• Refactor forms to support mode: 'wizard' | 'standalone'
• Step 1: Locations (with hierarchy)
• Step 2: Organizations
• Step 3: CareTeams
• Step 4: Users
• Step 5: Assignments and review
• Two-phase commit logic
• Partial failure recovery UI

Dependencies

Depends on: Epic 3, 4, 5, 6, 7 (all entity forms must exist in standalone mode first)

References

• Bundle Transaction semantics