UI flow

Area Manager UI Flow & User Guide

Overview

The Area Manager feature provides a unified interface for managing area manager departments and executing rolling transfer operations. The interface consists of two main sections accessed via tab navigation:

1. Managers Tab - CRUD operations for manager departments
2. Rolling Tab - Multi-step workflow for transferring sites between manager departments

User Roles & Permissions

• Admin/Account Holder - Full access to all features
• Organization Scope - All operations are scoped to the authenticated user’s organization

Navigation

The feature is accessed via /admin/area-manager and defaults to the Managers tab. Users can switch between tabs using the top navigation bar.

Main layout showing tab navigation between Managers and Rolling operations

---

Managers Tab

The Managers tab provides comprehensive department management capabilities for area manager departments.

Main Interface

The Managers tab displays a data table showing all manager departments with the following information:

• Department Name - Primary identifier
• Email - Contact email for the department
• Status - Active/Inactive indicator with colored badges
• Sites Count - Number of sites managed by this department
• Users Count - Number of users assigned to this department
• Actions - Quick actions menu (edit, toggle status)

Managers tab showing the main data table with filters and actions

Filtering & Search

Users can filter the manager departments list using:

• Search - Text search across department name and email
• Status Filter - Filter by active/inactive status
• Quick Filters - Predefined filter combinations

Filter form allowing users to narrow down the managers list

Creating Manager Departments

The “Add Manager” button opens a dialog with two creation modes:

Mode 1: Create New Manager Department

Create a brand new manager department from scratch:

1. Click “Add Manager” button
2. Select “Create New Manager Department” tab
3. Fill in required fields:
   • Department Name - Unique identifier
   • Email - Contact email (validated format)
   • Manager User - Select from available users
4. Click “Create” to submit

Dialog for creating a new manager department with form fields

Mode 2: Convert Existing Department

Convert an existing regular department to a manager department in 2 steps:

Step 1: Select Department

1. Click “Add Manager” button
2. Select “Convert Existing Department” tab
3. Search and select department from dropdown
4. Click “Next” or “Continue”

Step 1: Search and select department to convert

Step 2: Confirmation with Details

1. Review department details displayed:
   • Department name and email
   • Number of sites currently assigned
   • Number of users in department
   • Current status
2. Verify information is correct
3. Click “Convert to Manager Department” to confirm

Step 2: Review details and confirm conversion

Editing Manager Departments

To edit an existing manager department:

1. Click the “Edit” action in the data table row
2. Modify fields as needed:
   • Department name
   • Email address
   • Status (active/inactive)
3. Click “Save Changes”

Edit dialog showing editable fields for a manager department

Status Management

Manager departments can be activated or deactivated:

• Active - Green badge, department is operational
• Inactive - Red badge, department is suspended

Toggle status via:

• Quick action in data table row
• Status field in edit dialog

---

Rolling Tab - 3-Step Workflow

The Rolling tab provides a guided, step-by-step workflow for transferring sites between manager departments. The workflow is divided into three sequential cards, each representing a distinct phase.

Workflow Overview

Step 1: Site Selection
   �
Step 2: Transfer Configuration
   �
Step 3: Review & Execute

Lock Mechanism

When a rolling operation is active, all three cards display a = Lock Badge to prevent concurrent modifications:

• Cards are disabled during active operations
• Users can only monitor progress
• Lock automatically releases when operation completes/fails

Lock badge displayed on cards when operation is in progress

---

Step 1: Site Selection Card

The first step allows users to select which sites need to be transferred.

Interface Elements

• Step Indicator - Numbered badge (1) showing current step
• Site Counter - Shows how many sites are currently selected
• Add Sites Button - Opens site selection interface
• Lock Badge - Displays during active operations

Step 1 card showing site selection interface

Selecting Sites

1. Click “Add Sites” button
2. Use filters to narrow down sites:
   • Department Filter - Filter by current department
   • Search - Text search across site names
   • Status Filter - Filter by site status
3. Review sites in data table with columns:
   • Site name
   • Current department
   • Number of users
   • Current manager
   • Status badge
4. Click ”+ Add” button for each site to select

Data table showing available sites with filters and add buttons

Site Status Indicators

Sites display status badges indicating their eligibility:

• Eligible - Green badge, can be transferred
• Already Selected - Blue badge, already added to current transfer
• In Use - Yellow badge, currently in another pending operation
• Ineligible - Red badge, cannot be transferred (reasons provided)

Removing Sites

Selected sites can be removed before execution:

• View selected sites in the transfer configuration card (Step 2)
• Click “Remove” action to deselect

---

Step 2: Transfer Configuration Card

The second step allows users to configure the transfer details for each selected site.

Interface Elements

• Step Indicator - Numbered badge (2)
• Transfer Summary - Shows total sites and affected users
• Site Counter - Number of sites being configured
• User Counter - Total users affected by transfers
• Lock Badge - Displays during active operations

Step 2 card showing transfer configuration interface

Configuring Transfers

For each selected site, configure:

1. Roll-out Department (Source) - Current manager department
   • Auto-populated based on site’s current manager
   • Can be changed if needed
2. Roll-in Department (Destination) - New manager department
   • Select from available manager departments
   • Dropdown shows department name and metadata
3. Review Site Details:
   • Site name and ID
   • Current department
   • Number of users affected
   • Validation status

Table showing sites with source/destination department selectors

Transfer Validation

Each transfer configuration is validated:

•  Valid - Green checkmark, ready to execute
• � Warning - Yellow warning, review recommended
• L Invalid - Red error, must be fixed before execution

Common validation errors:

• Source and destination departments are the same
• Destination department not selected
• Site already in destination department
• Circular transfer detected

Empty State

When no sites are selected, the card displays an empty state:

Empty state shown when no sites have been added yet

---

Step 3: Review & Execute Card

The final step displays a summary and provides execution controls.

Interface Elements

• Step Indicator - Numbered badge (3)
• Execution Summary - Overview of the pending operation
• Execution Controls - Buttons to schedule/execute
• Lock Badge - Displays during active operations

Step 3 card showing operation summary and execution controls

Execution Summary

The summary displays:

• Total Sites - Number of sites being transferred
• Total Users - Number of users affected
• Transfer Breakdown - List of department pairs:
  • Roll-out department � Roll-in department
  • Site count per pair
  • User count per pair
• Validation Status - Overall readiness indicator

Detailed summary showing all transfer configurations

Execution Controls

Two execution modes are available:

1. Execute Now - Immediate execution

   • Click “Execute Now” button
   • Operation starts immediately
   • Progress dialog opens automatically

2. Schedule Execution - Future execution

   • Click “Schedule” button
   • Select date and time
   • Operation queued via Cloud Tasks
   • Notification sent when complete

Buttons for immediate execution or scheduling

Execution Requirements

The “Execute Now” button is enabled only when:

• At least one site is selected 
• All transfer configurations are valid 
• No operation is currently running 

If requirements are not met, the button is disabled with a tooltip explaining why.

---

Real-Time Progress Monitoring

When a rolling operation is executed, users can monitor progress in real-time via the Progress Dialog.

Progress Dialog

The dialog provides comprehensive operation status:

Dialog displaying real-time operation progress with phase indicators

Dialog Sections

1. Header

   • Operation ID
   • Status badge (In Progress / Completed / Failed)
   • Timestamp

2. Transfer Summary

   • Roll-out department � Roll-in department
   • Sites being transferred
   • Users affected

3. Progress Indicator

   • Overall progress percentage
   • Progress bar visualization
   • Current phase indicator

4. Phase Details The rolling operation consists of 6 phases:

   • Phase 1: State Collection - Backing up current state
   • Phase 2: Sites Update - Updating site ownership
   • Phase 3: Department Index - Updating department indices
   • Phase 4: Schedule Index - Updating schedule assignments
   • Phase 5: Questionnaires - Updating auto-assignments
   • Phase 6: Completion - Finalizing operation

   Each phase shows:

   • Phase name
   • Status icon ( completed, � in progress, � pending)
   • Progress details

Detailed view of operation phases with completion status

5. Transfer Progress List Detailed breakdown by site:
   • Site name
   • Roll-out � Roll-in departments
   • Individual progress percentage
   • Status indicator

Per-site progress tracking with individual status

Status Indicators

• = In Progress - Blue badge with spinner, operation running
•  Completed - Green badge with checkmark, operation succeeded
• L Failed - Red badge with X, operation failed

Error Handling

If an operation fails:

1. Automatic Rollback initiated
2. Error Alert displayed with:
   • Error message
   • Affected phase
   • Rollback status
3. Rollback Progress tracked in real-time
4. Final State shows either:
   •  Rollback successful (data restored)
   • L Rollback failed (manual intervention needed)

Error alert showing rollback in progress after operation failure

Dialog Controls

• Close button - Only enabled when operation completes/fails
• View Details link - Opens full operation log
• Retry button - Available after failed operations (with validation)

---

User Workflows

Workflow 1: Create a New Manager Department

Goal: Add a new area manager to the system

Steps:

1. Navigate to /admin/area-manager (defaults to Managers tab)
2. Click “Add Manager” button
3. Select “Create New Manager Department” tab
4. Fill in required information:
   • Department name (e.g., “North Region”)
   • Contact email
   • Select manager user from dropdown
5. Click “Create”
6. Success toast notification appears
7. New department appears in the data table

Expected Outcome: New manager department is created and immediately available for rolling operations.

---

Workflow 2: Convert Existing Department to Manager

Goal: Upgrade a regular department to manager status

Steps:

Step 1: Select Department

1. Navigate to /admin/area-manager → Managers tab
2. Click “Add Manager” button
3. Select “Convert Existing Department” tab
4. Search and select department from dropdown
5. Click “Next” or “Continue”

Step 2: Review Details and Confirm 6. System displays department details:

• Department name and email
• Current sites assigned (count)
• Current users (count)
• Current status

7. Verify information is correct
8. Click “Convert to Manager Department”
9. Success notification appears
10. Converted department appears in managers table with manager badge

Expected Outcome: Existing department is flagged as isManager: true and can now participate in rolling operations.

---

Workflow 3: Execute a Simple Rolling Operation

Goal: Transfer 3 sites from Manager A to Manager B

Steps:

Phase 1: Site Selection

1. Navigate to /admin/area-manager � Rolling tab
2. Click “Add Sites” in Step 1 card
3. Select “Manager A” from department filter
4. Review sites in data table
5. Click ”+ Add” for Site 1, Site 2, Site 3
6. Verify counter shows “3 sites selected”

Phase 2: Transfer Configuration

1. Review Step 2 card - 3 sites listed
2. For each site:
   • Verify roll-out department is “Manager A” (auto-populated)
   • Select “Manager B” from roll-in dropdown
3. Verify all rows show  valid status
4. Review summary: “3 sites, 15 users”

Phase 3: Execution

1. Step 3 card appears automatically
2. Review execution summary:
   • Manager A � Manager B
   • 3 sites
   • 15 users affected
3. Click “Execute Now”
4. Confirmation dialog appears
5. Click “Confirm”
6. Progress dialog opens immediately

Phase 4: Monitoring

1. Watch progress bar advance
2. Monitor phase indicators (6 phases)
3. Observe per-site progress
4. Wait for completion (~2-3 minutes for 3 sites)
5. Success notification appears
6. Click “Close” to dismiss dialog
7. Rolling tab state is cleared and ready for next operation

Expected Outcome: All 3 sites are successfully transferred from Manager A to Manager B with updated:

• Site ownership
• Department indices
• Schedule assignments
• Questionnaire auto-assignments
• Supervisor assignments

---

Workflow 4: Schedule a Rolling Operation

Goal: Schedule a transfer to occur during off-hours

Steps:

Phase 1-2: Same as Workflow 3 (Site Selection & Configuration)

Phase 3: Scheduling

1. In Step 3 card, click “Schedule” button (not “Execute Now”)
2. Date/time picker dialog opens
3. Select future date and time (e.g., “Tonight at 2:00 AM”)
4. Optional: Add description/notes
5. Click “Schedule Operation”
6. Confirmation notification appears
7. Scheduled operation appears in recent operations list
8. Email notification sent to user

Phase 4: Execution (Automatic)

1. At scheduled time, Cloud Task triggers execution
2. Operation runs in background
3. User receives email notification when complete
4. Next time user visits Rolling tab, completed operation shows in history

Expected Outcome: Operation executes automatically at scheduled time without user interaction.

---

Workflow 5: Handle a Failed Operation with Rollback

Goal: Understand what happens when an operation fails

Scenario: Operation fails during Phase 4 (Schedule Index) due to database timeout

Steps:

Phase 1-3: Same as Workflow 3 (Select sites, configure, execute)

Phase 4: Failure Detection

1. Progress dialog shows phases 1-3 completed 
2. Phase 4 shows � in progress
3. After timeout, Phase 4 shows L failed
4. Error alert appears in dialog:
   • “Operation failed during Phase 4: Schedule Index Update”
   • “Database timeout exceeded”
   • “Rollback initiated automatically”

Phase 5: Automatic Rollback

1. Rollback progress section appears
2. Progress bar shows rollback phases:
   •  Restoring sites (Phase 2 rollback)
   •  Restoring department indices (Phase 3 rollback)
   • � Restoring schedules (Phase 4 rollback)
3. All rollback phases complete
4. Success notification: “Rollback completed successfully”
5. Error summary appears:
   • Original operation ID
   • Failure reason
   • Rollback status:  Complete
   • Data integrity:  Verified

Phase 6: Post-Failure

1. Click “Close” dialog
2. Rolling tab state is preserved (sites still selected)
3. User can:
   • Review and adjust configurations
   • Click “Retry” to attempt again
   • Or click “Clear” to start fresh

Expected Outcome:

• All database changes reverted to pre-operation state
• No data corruption
• Sites remain in original manager departments
• Operation marked as failed in history
• Detailed error log available for debugging

---

Advanced Features

Concurrent Operation Protection

The system prevents multiple simultaneous rolling operations:

• Lock Mechanism - Only one operation per organization at a time
• Lock Badge - Visual indicator on all cards
• Queue System - Scheduled operations queue automatically
• Heartbeat Monitoring - Detects stalled operations and releases locks

Operation History

Recent operations are tracked and displayed:

• View in “Recent Operations” section on Rolling tab
• Filter by status (completed, failed, in progress)
• Click operation to view detailed log
• Export operation details as JSON/CSV

List of recent rolling operations with status and timestamps

Validation Rules

The system enforces several validation rules:

1. Site Eligibility

   • Site must exist and be active
   • Site must have a current manager department
   • Site cannot be in another pending operation

2. Department Validation

   • Both roll-out and roll-in must be manager departments
   • Roll-out and roll-in cannot be the same
   • Destination department must be active

3. Circular Transfer Detection

   • System detects circular transfers (A�B, B�A)
   • Warns user and suggests alternatives

4. User Assignment Validation

   • Users must exist and be active
   • User roles are preserved during transfer
   • Supervisor assignments updated automatically

Mobile Responsiveness

The entire UI is responsive and works on mobile devices:

• Tablet - Side-by-side cards with adjusted spacing
• Mobile - Stacked cards with touch-optimized controls
• Progress Dialog - Full-screen on mobile for better visibility

---

Keyboard Shortcuts

Power users can use keyboard shortcuts:

• Ctrl + K - Quick search
• Ctrl + N - Add new manager
• Ctrl + E - Execute operation (when ready)
• Esc - Close dialogs/cancel actions
• Tab - Navigate between input fields
• Enter - Submit forms

---

Accessibility

The UI follows WCAG 2.1 AA standards:

• Screen Readers - All elements have proper ARIA labels
• Keyboard Navigation - Full keyboard support
• Color Contrast - Minimum 4.5:1 ratio on all text
• Focus Indicators - Clear focus rings on interactive elements
• Status Announcements - Screen readers announce operation progress

---

Tips & Best Practices

For Efficient Rolling Operations

1. Plan Ahead - Review sites and their configurations before starting
2. Use Filters - Narrow down site lists to avoid mistakes
3. Validate First - Ensure all configurations are valid before executing
4. Schedule Off-Hours - Large transfers (>50 sites) should run during low-traffic periods
5. Monitor Progress - Keep progress dialog open for real-time updates
6. Document Changes - Add notes to scheduled operations for future reference

For Manager Department Management

1. Consistent Naming - Use clear, descriptive department names
2. Active Status - Keep only current managers active
3. Email Accuracy - Ensure contact emails are correct and monitored
4. Regular Audits - Periodically review manager assignments
5. Convert Thoughtfully - Consider impact before converting regular departments to managers

For Troubleshooting

1. Check Locks - If cards are locked, wait for current operation to complete
2. Review Validation - Red validation errors must be fixed before execution
3. Network Issues - Progress dialog remains functional even if connection drops briefly
4. Failed Operations - Review error messages carefully before retrying
5. Contact Support - For persistent issues, provide operation ID for faster resolution

---

Related Documentation

• Manager Rolling Overview - High-level feature description
• BE Architecture - Technical implementation details
• Department Management - Regular department management
• Site Management - Site configuration details
• User Assignment - User assignment workflows