Waiting Line Management System — Embassy of Palestine in Doha

1. For visitors / clients

The waiting-line system lets you join a service queue at the embassy without standing in a physical line. You scan a QR code (or type the embassy URL), pick the service you need, and receive a digital ticket. The page then refreshes itself to show how many people are ahead of you and roughly when your turn will come.

1.1. Joining a queue

1. Open the embassy waiting-line page in your phone browser. The embassy provides a QR code on a sign at reception — scan it with your camera.
2. You see the list of available services with how many people are currently waiting and an estimated ready time.
3. Tap the service you need. A short form asks for:
   • Your first name
   • Your family name
   • Your mobile number (Qatar local numbers accepted; the country code is added automatically).
4. Tap Continue. You see a preview with the current wait time and your name. Tap Yes, join the line to confirm.
5. You receive your ticket page showing your ticket code (e.g. T-CIV-0042), your queue position, and the estimated ready time. Keep this page open. It updates automatically.

1.2. Reconnecting to your ticket

If you accidentally close the browser tab, do not register again. Instead:

1. Open the embassy waiting-line page.
2. Tap I already have a ticket at the bottom of the service list.
3. Type either your mobile number or your ticket code.
4. Tap Find ticket. You return to your live status page.

1.3. Understanding your ticket page

Element	Meaning
Ticket code	Your unique reference. Show it at the desk if asked. Format: T-XXX-NNNN.
Position	Your place in the queue today. Lower is sooner.
Clients ahead	How many people the desk staff need to serve before you.
Ready around	Estimated time you will be called — based on average service times. Estimate, not a promise.
Status: waiting	You are in the queue. Wait until called.
Status: called	Your turn! Proceed to the desk shown on the page within a few minutes — otherwise you may be marked absent.
Status: in_service	The desk manager is currently serving you.
Status: served	Your visit is complete.

1.4. Cancelling your ticket

If you change your mind, tap Cancel my ticket at the bottom of the ticket page. Cancelled tickets free up your spot for others. You can register again later if needed.

1.5. Switching language

The top-right of every page has a language picker. Tap it to choose between English and العربية. Your choice is remembered between visits.

1.6. Best practices for visitors

• Arrive a few minutes before "Ready around". The estimate is not exact — some clients take longer than average, others shorter.
• Keep your phone awake on the ticket page if you can. The status changes to "called" as soon as the desk is ready for you.
• Have your documents ready. Civil certificate requests need ID; passport renewals need the existing passport; legalizations need the original document.
• If you must leave before being called, cancel your ticket. Letting it expire as "absent" makes the queue estimates less accurate for the people behind you.

2. For desk managers

Desk managers operate the live queue: calling the next client, starting service, marking people served or absent. The system tracks every action so the statistics dashboard reflects real activity.

2.1. Logging in

1. Visit https://s.palestine-embassy-qa.net/login.
2. Type your username and password (provided by the administrator).
3. You arrive on the service picker showing the services you are authorised to manage.

2.2. The desk dashboard

Tap a service to open its live queue. The dashboard has three sections:

Banner: who is at the desk

The top banner shows your name, role, and a confirmation that you are on duty. This is the identity the system associates with every action you take — useful for the audit log and for shift handover.

Coming clients

A live table of every client currently waiting, with their queue position, ticket code, first/family name, mobile number, status, and action buttons. Refreshes automatically every few seconds.

Recently handled

The last 10 clients you served, marked absent, or whose tickets were cancelled today. Useful for confirming you closed out correctly.

2.3. The standard workflow

1. Tap Call next client. The next waiting client moves to called. The client's phone shows "Your turn!" and the desk reference. The client should head to your desk.
2. When they arrive, tap Start service on their row. Status becomes in_service. The timer starts (this is what the system uses to learn how long the service really takes).
3. When done, tap Complete. Status becomes served. The row moves to "Recently handled". The next client can now be called.

2.4. Handling exceptions

Situation	Action
Client is called but does not show up after a few minutes.	Tap Absent. Their slot is freed; the queue moves on.
Client cancels at the desk before being served.	Tap Cancel. The ticket is closed without counting as served.
You called the wrong client by accident.	Mark them Absent — this returns them to a terminal state. The actual next client can then be called fresh. (There is no "uncall" button on purpose.)
Client has the wrong service (e.g. wants passport but registered in legalizations).	Tap Cancel on their ticket and ask them to register again under the correct service.
Service complete but you forgot to "Start service" first.	Tap Served directly from "called". The system accepts this and just records a shorter service duration.

2.5. Sharing a desk with a co-worker

A single desk can have several authorized managers (a "primary" plus any number of "co-managers"). Both see the same queue and can take any action. This is useful for shift handover or when two staff share a counter.

Co-manager assignments are made by an administrator (Section 3.4). If you should be able to operate a desk but it does not appear in your service picker, ask the admin to add you as a co-manager.

2.6. End-of-day checklist

• All visible queue rows are in a terminal state (served, absent, or cancelled). No waiting or in_service rows lingering.
• Optional: glance at the "Recently handled" panel — the day's volume should look right.
• Logout via the navbar to clear the session on shared computers.

2.7. Best practices for desk managers

• Call clients by name. The system surfaces their first and family name precisely so you can do this.
• Stay on the queue page while at the desk. It auto-refreshes; constantly reloading manually is unnecessary and costs the server a bit of work.
• Mark absences honestly. The "absent" rate feeds into the wait-time estimate for everyone else; over- or under-marking hurts accuracy for visitors.
• Do not register clients on their behalf from your own logged-in account — the system has a separate visitor flow that runs without authentication. Direct visitors to the QR code or to a kiosk if you have one.

3. For administrators

The admin role can configure everything: services, desks, slots, users, translations, the public display board, and the QR codes visitors scan. Admins also see all statistics.

3.1. The admin dashboard

Logging in as an admin lands you on the dashboard. It shows today's snapshot: tickets issued, clients served, currently waiting, average wait. Each service tile mirrors the public status page so you see at a glance how things are running. The page auto-refreshes every 30 seconds.

3.2. Managing services

A "service" is a category of work you offer (e.g. Civil Certificate, Passport renewal). Each service has its own queue.

• Create a service: Services menu → New service. Enter a name (the canonical English name — visible on every staff screen and in tickets), an optional description, and an average duration (minutes per client). Save.
• Add a translation: on the Services list, click the small translate icon next to a service. Enter the Arabic name and description. Save. Visitors who have Arabic selected will now see the localized text on the public pages.
• Deactivate a service that is temporarily unavailable. It stops appearing on the public pages but keeps its historical tickets.
• Delete a service only if it has no historical tickets. The system refuses if data exists.

3.3. Setting service hours (slots)

A service is "open" only during a configured slot for the current day. Slots define which days and which hours a service accepts new tickets, plus an optional capacity (max tickets per slot).

• Slots menu → New slot.
• Pick the service, the date, and start/end time (in local Qatar time).
• Capacity is optional. Leave blank for unlimited; set a number to stop accepting tickets after that many are issued.
• You can create multiple slots per day for the same service (e.g. morning + afternoon with a break in between).

3.4. Managing desks

A "desk" is a physical or logical counter that serves a service. A service can have multiple desks (parallel counters) and a desk belongs to exactly one service.

• Create a desk: Desks menu → New desk. Pick the service, give the desk a short reference (e.g. CIV-01), optional location text ("Main hall"), and assign a primary manager.
• Co-managers: below the primary-manager picker is a checkbox list of additional users authorized to operate this desk. Tick all who should have access. Selected users see the desk in their service picker and can use all its actions.
• Deactivate a desk to take it offline without deleting it (e.g. counter under maintenance).

3.5. Managing users

Two roles exist:

• admin: full access to everything in this manual.
• desk_manager: can operate the queue for desks they are authorized on. Cannot edit services, slots, or other users.

Create users via Users menu → New user. Each user needs a username and password. Optionally add a full name (shown on the desk dashboard) and phone number.

3.6. The public display board

The display board is a TV-style page that shows currently-called tickets and their assigned desks. Useful for hanging on a screen in the waiting area.

• Display menu → the page generates a unique signed URL.
• Open that URL on the display computer. Bookmark it.
• The page polls every 20 seconds and shows the most recent "called" tickets.
• The URL is signed and unguessable but is not authenticated — anyone with the link can view it. Treat it like a semi-public asset (do not embed in a public website).

3.7. QR codes

QR codes menu → signed page with two QR codes you can print:

• The main app QR: takes visitors to the service picker.
• One per-service QR per active service: takes visitors directly to that service's join form, skipping the picker. Useful if you have separate signage at each desk.

3.8. Statistics

Statistics menu → aggregated metrics over a date range: tickets issued, served, absent, cancelled, and average wait time per service. Use this for monthly reports or to spot patterns (e.g. "Tuesdays are 30% busier on Civil Certificate — we need a second counter").

3.9. Localization (translations)

The interface speaks English and Arabic. UI strings (buttons, labels) come from a translation catalog the system ships with. Service names and descriptions are stored in the database and translated per-service via the Services list.

To adjust UI wording, the catalog files are at translations/ar/LC_MESSAGES/messages.po. Edit, run pybabel compile -d translations, redeploy. Plan ~5 minutes per round-trip.

3.10. Daily backups

The server creates a database backup automatically before every code redeploy. Backups live in /home/wlms/backups/ on the server (last 7 retained).

3.11. Best practices for administrators

• Configure slots in advance — at least a week ahead. Visitors trying to register outside slot hours see "Closed", which is the right behaviour but unhelpful if you forgot to set the slot.
• Audit users monthly. Deactivate accounts of staff who have left.
• Keep a backup admin account. If the primary admin password is lost, the backup admin can reset it. With only one admin and a forgotten password, the system requires shell access to recover.
• Test the flow yourself after every config change — create a test ticket with your own number, watch it appear on the desk dashboard, verify the display board picks up the "called" status. End-to-end tests in 90 seconds.
• Do not edit the SQLite file directly. Use the admin UI. Direct writes can violate constraints the application relies on (unique service references, ticket-status FSM, etc.).

4. Troubleshooting

Symptom	Likely cause and fix
Visitor says "the page is closed" but the slot should be open.	Check the slot configuration: today's date, the time range, and whether the slot is marked active. Server time is Asia/Qatar.
Desk manager logs in but sees no services in the picker.	Either no desk is assigned to them (primary or co-manager), or the desks they are assigned to are deactivated. Check the Desks page.
Visitor cannot register — "You already have an active ticket" message.	Working as designed. The visitor has a ticket open from earlier in the day. Either send them to that ticket, or have a desk manager cancel the old ticket if it is stale.
Public site is slow to load.	Most likely a single client polling rapidly from many tabs. The auto-refresh cadence is 5-10 seconds; one tab per visitor is fine but dozens get expensive.
Public site is unreachable entirely.	Check the server with system logs. If the service is down, an administrator with shell access needs to restart it.
"500 Internal Server Error" on a specific page.	Take a screenshot of the page, note the URL, and report it to the system administrator.
Translation mistake on a specific phrase.	Note the exact phrase and which language it is in; the administrator can edit the translation catalog and redeploy.

---

Manual version 1.0 — 2026-06-11. The code base evolves; sections marked with technical paths may need updating after major upgrades.