marwan/HH
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
HH/docs/ONBOARDING_COMPLETE.md
Marwan Alwali cfe83f50e0 add-acknowledgments
2026-01-06 13:36:43 +03:00

11 KiB
Raw Permalink Blame History

PX360 User Onboarding System - Complete Implementation

Overview

A comprehensive user onboarding system that ensures all new users receive proper training on the PX360 system before gaining full access. Users must complete a guided wizard, review content, and acknowledge checklist items before activating their accounts.

Key Features

1. Provisional User Management

  • Provisional Users: Users created without passwords who must complete onboarding
  • Invitation System: Email invitations with secure tokens
  • Token Validation: Time-limited tokens (default 7 days)
  • Audit Trail: Complete logging of all provisional user events

2. Onboarding Wizard

  • Multi-step Process: Guided wizard with clear progression
  • Content Presentation: HTML-rich content in English and Arabic
  • Progress Tracking: Real-time progress percentage
  • Resume Capability: Users can pause and resume later

3. Acknowledgement Checklist

  • Required Items: Must be acknowledged before account activation
  • Digital Signature: Users sign to confirm understanding
  • Audit Trail: All acknowledgements logged with timestamps
  • Role-Specific: Different checklists for different roles

4. Account Activation

  • Username/Password Creation: After completing onboarding
  • Final Signature: Legal signature on completed onboarding
  • Admin Notification: Email notification to PX Admins
  • Automatic Activation: Immediate access upon completion

Database Models

User Model Extensions

- is_provisional: Boolean (new users)
- invitation_token: UUID (secure token)
- invitation_expires_at: DateTime
- acknowledgement_completed: Boolean
- acknowledgement_completed_at: DateTime
- current_wizard_step: Integer
- wizard_completed_steps: JSONField

Acknowledgement Content

- code: Unique identifier
- title_en/title_ar: Bilingual titles
- content_en/content_ar: HTML content
- role: Optional role filter
- order: Display order
- is_active: Boolean

Acknowledgement Checklist Item

- code: Unique identifier
- content: FK to AcknowledgementContent
- text_en/text_ar: Checklist item text
- description_en/description_ar: Additional context
- is_required: Must acknowledge to proceed
- order: Display order

User Acknowledgement

- user: FK to User
- checklist_item: FK to ChecklistItem
- is_acknowledged: Boolean
- acknowledged_at: DateTime
- signature: Digital signature

User Provisional Log

- user: FK to User
- event_type: String (created, invited, reminder, completed, expired)
- metadata: JSONField (additional details)
- created_at: DateTime

API Endpoints

User Onboarding Actions

POST   /api/auth/onboarding/create-provisional    Create provisional user (Admin)
POST   /api/auth/users/{id}/onboarding/resend-invitation  Resend invitation (Admin)
GET    /api/auth/onboarding/progress               Get onboarding progress
GET    /api/auth/onboarding/content                Get wizard content
GET    /api/auth/onboarding/checklist              Get checklist items
POST   /api/auth/onboarding/acknowledge            Acknowledge checklist item
POST   /api/auth/onboarding/complete               Complete wizard and activate account
GET    /api/auth/users/{id}/onboarding/status      Get user onboarding status (Admin)

Content Management

GET    /api/auth/acknowledgement-content/          List content (Admin)
POST   /api/auth/acknowledgement-content/          Create content (Admin)
GET    /api/auth/acknowledgement-checklist-items/  List checklist items (Admin)
POST   /api/auth/acknowledgement-checklist-items/  Create checklist item (Admin)
GET    /api/auth/user-acknowledgements/             List acknowledgements

UI Pages

Wizard Pages

  1. Welcome Page (/onboarding/welcome)

    • Introduction to onboarding process
    • Overview of what to expect

  2. Content Step (/onboarding/content/{step})

    • Display content for current step
    • Navigation controls (Next/Previous)
    • Progress indicator

  3. Checklist Step (/onboarding/checklist)

    • List of items to acknowledge
    • Required vs optional items
    • Acknowledge each item with signature

  4. Activation Step (/onboarding/activate)

    • Create username and password
    • Final signature
    • Complete onboarding

  5. Complete Page (/onboarding/complete)

    • Success message
    • Redirect to dashboard

Management Pages

  1. Provisional Users List (/accounts/onboarding)

    • List all provisional users
    • Filter by status, role, hospital
    • Action buttons (resend, view progress, etc.)

  2. Create Provisional User (/accounts/onboarding/create)

    • Form to create new provisional user
    • Select roles and assign to hospital/department

  3. User Progress (/accounts/onboarding/{id}/progress)

    • Detailed progress view
    • Acknowledgement status
    • Timeline of events

Email Templates

Invitation Email

  • Subject: "Welcome to PX360 - Complete Your Onboarding"
  • Content: Welcome message + secure link to onboarding wizard
  • Arabic version available

Reminder Email

  • Subject: "Reminder: Complete Your PX360 Onboarding"
  • Content: Reminder to complete onboarding before expiration
  • Sent at 50% and 80% of token lifetime

Completion Notification

  • Sent to PX Admins
  • Contains user details and completion time
  • Includes link to user profile

Security Features

  1. Secure Tokens: UUID-based invitation tokens
  2. Token Expiration: 7-day validity period
  3. Password Validation: Django's built-in password validators
  4. Audit Logging: All actions logged for compliance
  5. Permission Checks: Role-based access control
  6. Digital Signatures: Cryptographic signature verification

Middleware

OnboardingMiddleware

  • Automatically redirects provisional users to onboarding wizard
  • Prevents access to other parts of the system
  • Allows access to onboarding pages and API endpoints

Services

OnboardingService

- create_provisional_user(user_data)
- validate_invitation_token(token)
- get_user_progress(user)
- get_user_progress_percentage(user)
- get_wizard_content(user)
- get_checklist_items(user)
- acknowledge_item(user, item, signature, request)
- complete_wizard(user, username, password, signature, request)

EmailService

- send_invitation_email(user, request)
- send_reminder_email(user, request)
- send_completion_notification(user, admin_users, request)

Default Content

The system comes with pre-configured acknowledgement content:

Generic Content (All Users)

  1. Welcome to PX360: System overview and key features
  2. Data Privacy & Security: Data protection policies and user responsibilities
  3. System Usage Guidelines: Best practices and support information

Role-Specific Content

  • PX Admin: Admin responsibilities and oversight
  • Hospital Admin: Hospital-level management scope
  • Department Manager: Department operations oversight
  • Physician: Physician role in patient experience
  • Staff: Staff responsibilities and service standards

User Flow

New User Onboarding

  1. Admin creates provisional user via management interface
  2. System sends invitation email with secure link
  3. User clicks link to start onboarding wizard
  4. User reviews content for each step
  5. User acknowledges checklist items (required items must be acknowledged)
  6. User creates username and password
  7. User signs final acknowledgement
  8. Account activated and user redirected to dashboard
  9. PX Admins receive notification email

Resume Onboarding

  • Users can pause and resume at any time
  • Progress is saved automatically
  • Must complete before invitation token expires
  • Can request new invitation if token expires

Admin Workflow

Create New User

  1. Navigate to /accounts/onboarding
  2. Click "Create Provisional User"
  3. Fill in user details (name, email, roles, hospital, department)
  4. System creates provisional user and sends invitation
  5. Track user progress from the list view

Monitor Progress

  1. View all provisional users on list page
  2. Click on user to see detailed progress
  3. View acknowledgement status
  4. Resend invitation if needed

Configuration

Settings

# Invitation token validity (in days)
INVITATION_TOKEN_VALIDITY_DAYS = 7

# Reminder schedule (percentage of token lifetime)
INVITATION_REMINDER_SCHEDULE = [50, 80]

# Onboarding wizard URL
ONBOARDING_WIZARD_URL = '/onboarding'

Permissions

CanManageOnboarding

  • PX Admins only
  • Can create provisional users
  • Can resend invitations
  • Can view all onboarding status

IsProvisionalUser

  • Users with is_provisional=True
  • Can access onboarding wizard
  • Cannot access other parts of system

CanViewOnboarding

  • PX Admins
  • Can view any user's onboarding status

CanManageAcknowledgementContent

  • PX Admins only
  • Can create/edit acknowledgement content
  • Can create/edit checklist items

Audit Trail

All provisional user events are logged:

  • User created
  • Invitation sent
  • Reminder sent
  • Item acknowledged
  • Wizard completed
  • Token expired
  • Account activated

Testing

Manual Testing Checklist

  • Create provisional user as PX Admin
  • Verify invitation email received
  • Click invitation link and verify wizard loads
  • Navigate through all wizard steps
  • Acknowledge required checklist items
  • Try to skip required items (should fail)
  • Create username and password
  • Sign final acknowledgement
  • Verify account activated
  • Verify admin notification received
  • Test resume functionality (pause and return)
  • Test expired token scenario
  • Verify provisional users cannot access other pages
  • Test role-specific content visibility

Management Commands

Initialize Onboarding Data

python manage.py init_onboarding_data

Populates the database with default acknowledgement content and checklist items.

Future Enhancements

Potential improvements for future versions:

  1. Video Tutorials: Embedded video content for visual learners
  2. Quiz Assessments: Knowledge check before allowing progress
  3. Gamification: Badges and achievements for completing onboarding
  4. Bulk Onboarding: Import multiple users from CSV
  5. Custom Content Per Hospital: Hospital-specific onboarding content
  6. Analytics Dashboard: Onboarding completion rates and insights
  7. Mobile-Optimized: Better mobile experience for onboarding wizard

Support

For issues or questions:

  1. Check the implementation guide: docs/ONBOARDING_IMPLEMENTATION_GUIDE.md
  2. Review the quick start guide: docs/ONBOARDING_QUICK_START.md
  3. Contact the PX360 support team

Conclusion

The PX360 User Onboarding System ensures that all new users receive comprehensive training and acknowledge their understanding of the system before gaining access. This promotes:

  • Better user adoption and understanding
  • Compliance with data privacy policies
  • Clear expectations and responsibilities
  • Audit trail for legal and compliance purposes
  • Professional onboarding experience

The system is production-ready and fully integrated with the existing PX360 application.