Staff Guide
This guide is for Counter Staff (STAFF role) and Department Managers (MANAGER role) who use the Q-Flow staff dashboard to serve citizens at the counter.
Table of Contents
- Role Overview
- Logging In
- The Staff Dashboard
- Counter Assignment
- Calling the Next Token
- Serving a Citizen
- Finalising a Token
- Marking a No-Show
- Transferring a Token
- Handling Deferred Tokens
- Handling RAINCHECK Tokens
- Department Settings (Managers)
- Token States Reference
- Privacy & Scope
- Common Scenarios & Troubleshooting
1. Role Overview
Counter Staff (STAFF)
Counter Staff are the front-line operators who directly serve citizens at the counter. Their access is intentionally focused to prevent accidental exposure to other departments' data.
Staff can:
- Call the next token for their department.
- Finalise, defer, or transfer tokens.
- Mark citizens as no-shows.
- View queue depth and estimated wait times for their own department.
Staff cannot:
- View tokens from other departments.
- Change their own counter assignment.
- Access the admin panel or user management.
- View audit logs or feedback statistics.
Department Manager (MANAGER)
Managers have all staff capabilities plus:
- Update department settings (office hours, daily token limit) from the dashboard.
- Flush pending ghost tokens (DLQ replay).
- View department-level audit log entries and queue statistics.
2. Logging In
- Go to
/{orgSlug}/login(e.g.,/lalitpur-metro/login).- Alternatively: Go to
/login, click 🏛️ Find My Org, search for your organisation, and click it.
- Alternatively: Go to
- Enter your email and password.
- Click Login — you are automatically redirected to
/{orgSlug}/dashboard/staff.
Staff login gate: If you are a MANAGER or ADMIN and visit
/{org}/login/staff, you will be redirected to/{org}/login/managerinstead.
Session duration: Your login session is valid for 8 hours. You will be redirected to the login page when the session expires.
Forgotten Password
Contact your Organisation Admin to reset your password. There is no self-service password reset in the current version.
3. The Staff Dashboard
After logging in, you land on /{orgSlug}/dashboard/staff. The root dashboard/page.tsx server component checks your role and redirects STAFF to /dashboard/staff and MANAGER/ADMIN to /dashboard/manager.
The staff dashboard is divided into three areas:
A. Header / Action Bar
- Your counter name (read-only for STAFF role, shown with a 🔒 icon).
- Call Next button — calls the next highest-priority token.
- Real-time online counter count for your department.
- (MANAGER only) ⚙️ Department Settings button.
B. Queue List
Shows all tokens in your department in priority order:
| Priority | Status | Description |
|---|---|---|
| 1 | TRANSFERRED | Incoming from another department — served first |
| 2 | RAINCHECK | Service disruption priority pass — served second |
| 3 | DEFERRED | User-postponed — served third when they return |
| 4 | WAITING | Standard queue position |
Each token card shows:
- Token number (e.g.,
P-042) - Citizen name (if provided)
- Time in queue
- Status badge
- Action buttons (▶ Call Now, ↔️ Transfer, 🚫 No Show, ✅ Finalise)
C. Currently Serving Panel
Shows the active SERVING token with all citizen details and available actions.
4. Counter Assignment
Your counter is pre-assigned by the Organisation Admin and is displayed as a read-only label in the dashboard header:
🔒 Counter assigned by admin: Passport Counter 1
You cannot change your own counter. If you need to serve a different counter (e.g., due to a colleague being absent), contact your Organisation Admin or Manager to update your assignment via the admin panel.
Why is the counter fixed? Fixed counter assignments ensure clean audit trails and prevent staff from accidentally calling tokens belonging to another counter's queue. It also allows the system to enforce department-level privacy.
5. Calling the Next Token
- Click "Call Next" in the dashboard header.
- The system selects the next available token in priority order:
- TRANSFERRED tokens are called first (from other departments).
- RAINCHECK tokens are called second (priority passes from disruptions).
- WAITING tokens are called in queue order.
- DEFERRED tokens are skipped by the automatic "Call Next" — use ▶ Call Now to call them explicitly (see Section 10).
- The selected token's status changes to
SERVING. - The citizen is notified via:
- SMS (if a phone number was provided).
- Real-time update on their token status page.
- Announcement on the public display board.
No available tokens? The "Call Next" button is disabled when there are no WAITING, RAINCHECK, or TRANSFERRED tokens in your department. DEFERRED tokens alone do not enable the button.
6. Serving a Citizen
When a token is in SERVING status:
- The citizen should arrive at your counter.
- Verify their identity or documents as required by your department's procedures.
- Provide the requested service.
- When service is complete, finalise the token (see Section 7).
If the citizen does not arrive, wait a reasonable amount of time before marking them as a no-show (see Section 8).
7. Finalising a Token
After you have completed serving the citizen:
- Click "Finalise" (✅) in the currently serving panel or next to the SERVING token in the queue list.
- The token status changes to
FINALISED. - The citizen's token status page immediately shows the feedback emoji micro-survey.
- An automated SMS is sent to the citizen 15 minutes later, inviting them to rate the service.
Finalising is irreversible. If a token was accidentally finalised, only an ADMIN or SUPER_ADMIN can reactivate it within 48 hours.
8. Marking a No-Show
If a called citizen does not arrive at the counter:
- Click "No Show" (🚫) next to the SERVING token.
- The token enters STANDBY status — a 15-minute grace period begins, visible on the citizen's token page as a countdown.
- If the citizen arrives within 15 minutes, click ▶ Call Now to resume service.
- If 15 minutes elapse without the citizen appearing, the token automatically moves to NO_SHOW.
- The citizen's token page shows a one-time Re-Queue option.
9. Transferring a Token
Transfer a token when the citizen needs service from a different department or counter (e.g., passport application requires a separate biometrics scan).
- Click the Transfer icon (↔️) next to the token you want to transfer.
- In the transfer dialog:
- Select the destination department.
- Select the destination counter within that department.
- (Optional) Enter a staff note with context for the receiving staff (e.g., "Documents verified; needs biometrics only").
- Click Confirm Transfer.
After the transfer:
- The token disappears from your queue (it now belongs to the destination department).
- It appears in the destination department's queue as a TRANSFERRED token with the highest priority.
- The citizen receives an SMS with the new counter details and Pathfinder directions.
- You retain no further visibility into the token.
Circular transfer guard: The system automatically detects and rejects A → B → A transfer loops.
10. Handling Deferred Tokens
A DEFERRED token means the citizen postponed their turn (e.g., stepped out briefly) and has returned to the queue with priority.
- Deferred tokens appear in the queue list with a 🔁 badge.
- The automatic "Call Next" button skips deferred tokens — they must be called explicitly.
- To call a deferred token: click ▶ Call Now next to it in the queue list.
- Once called, the token enters SERVING and normal workflow applies.
11. Handling RAINCHECK Tokens
A RAINCHECK token is issued when a department was marked as disrupted while the citizen was waiting. It acts as a priority pass valid for 7 days.
- RAINCHECK tokens appear at the top of the queue list (priority 2, after TRANSFERRED).
- They are picked up by the automatic "Call Next" button.
- On the citizen's token page, the raincheck expiry date is shown.
12. Department Settings (Managers)
This section is for MANAGER role only.
-
On the staff dashboard, click ⚙️ Department Settings.
-
Update the fields:
Field Description Opening Time HH:MMformat. Token issuance is blocked before this time.Closing Time HH:MMformat. Token issuance is blocked after this time. The adaptive capacity guard activates in the final 2 hours.Daily Token Limit Maximum tokens per day. Leave blank for unlimited. -
Click Save.
Scope: Managers can only update their own assigned department. Admins can update any department in the organisation.
Flush Pending Tokens (DLQ Replay)
If the dashboard badge shows pending ghost tokens (tokens that failed to enter the queue due to a transient error):
- Click "Flush Pending Tokens".
- The system replays each pending ghost token and shows a summary.
13. Token States Reference
| Status | What It Means | Actions Available |
|---|---|---|
WAITING | In queue, awaiting call | Call Next (auto), Transfer |
SERVING | Called; citizen should be at counter | Finalise, No Show, Transfer |
TRANSFERRED | Moved to another dept/counter (priority) | Call Next (auto) picks up |
DEFERRED | Citizen postponed their turn | ▶ Call Now (manual only) |
RAINCHECK | Priority pass from disruption | Call Next (auto) picks up |
STANDBY | No-show grace period (15 min) | ▶ Call Now, wait for auto-expire |
NO_SHOW | Grace period expired | Admin can reactivate (within 48 h) |
FINALISED | Service completed | Read-only; feedback survey shown to citizen |
CANCELLED | Token cancelled by citizen or staff | Admin can reactivate (within 48 h) |
14. Privacy & Scope
Counter Staff have the narrowest data scope in the system. This is by design:
| What You Can See | What You Cannot See |
|---|---|
| All tokens in your own department | Tokens in other departments |
| Your assigned counter | Other counters' details or assignments |
| Your own session's actions | Other staff members' actions or queues |
This privacy boundary is enforced at four layers:
- Route-level: After login,
dashboard/page.tsxredirects STAFF to/dashboard/staffand MANAGER/ADMIN to/dashboard/manager— separate entry points for each role. - Server (page render): The dashboard page pre-filters tokens to your department before sending them to the browser.
- Client state: Every real-time token refresh re-applies the department filter in state.
- Render guard: A display filter re-applies the scope at render time as a defence-in-depth measure.
15. Common Scenarios & Troubleshooting
"Call Next" Button is Greyed Out
Cause: There are no WAITING, RAINCHECK, or TRANSFERRED tokens in your department. DEFERRED tokens do not enable the button.
Action: Check if any deferred tokens exist in the queue and call them manually with ▶ Call Now.
Citizen at the Counter but Token Still Shows WAITING
Cause: The token may have been called at a different counter, or the auto-refresh has not updated yet.
Action:
- Search for the citizen's token in the queue list.
- Click ▶ Call Now directly on their specific token.
Citizen Says Their SMS Shows a Different Counter
Cause: The token was transferred by another staff member after the SMS was sent.
Action: Check the token card for the current counter assignment and redirect the citizen accordingly.
Token Page Not Updating for the Citizen
Cause: The citizen's browser may have lost the real-time connection.
Action: Ask the citizen to refresh their token status page, or use the "Find My Token" feature at /[org]/join with their phone number to re-sync the session.
Accidentally Finalised a Token
Cause: Wrong token was finalised.
Action: Contact your Organisation Admin. ADMIN and SUPER_ADMIN can reactivate the token within 48 hours.
For admin-level operations see the Organisation & Admin Guide. For step-by-step walkthroughs see the How-To Guides.