# Al-Azeem Admin Checklist APIs Read-only checklist reporting endpoints for the Centrex Admin App. The existing Al-Azeem mobile application APIs are not changed. All three Admin endpoints use the existing Centrex `requireAuthToken()` bearer authentication and only execute `SELECT` statements against the CSP Oracle schema. Send the Centrex token from `POST /login_admin.php`: ```http Authorization: Bearer ``` Successful responses use the Centrex JSON envelope: `{"error":0,"error_msg":"...","data":...}`. Errors use `{"error":1,"error_msg":"...","error_code":...}`. ## Data source and counting rules The APIs read these tables: | Table | Use | |---|---| | `CSP.AL_AZEEM_CHECKLIST_TEMPLATES` | Checklist name and role | | `CSP.AL_AZEEM_CHECKLIST_SECTIONS` | Checklist sections | | `CSP.AL_AZEEM_CHECKLIST_ITEMS` | Checklist tasks | | `CSP.AL_AZEEM_CHECKLIST_SUBMISSIONS` | Employee checklist record, task date, submission status/time, notes, and image paths | | `CSP.AL_AZEEM_CHECKLIST_COMPLETIONS` | Per-task completion, evidence, note, and completion time | | `CSP.UM_USERS` / `CSP.EDIR` | User name and employee code | The checklist role is the template's `ROLE`. Task totals count the checklist items instantiated for each submission. A task is completed only when a matching completion row has `IS_DONE = 1`; missing or incomplete rows count as pending. Pending is `total_tasks - completed_tasks`. The `work_image_path` and `self_image_path` fields are the stored Oracle path values. These APIs return those values as stored; image hosting, access permissions, and URL signing remain controlled by the existing Al-Azeem application/deployment. ## Shared filters and pagination Dashboard and listing accept: | Parameter | Meaning | |---|---| | `grain` | `day`, `week`, or `month`; defaults to `day` | | `date` | Anchor date, `YYYY-MM-DD`. For weekly/monthly grain, selects the week/month containing the date | | `date_from`, `date_to` | Inclusive date range; both required together | | `year`, `month` | Select a calendar month; both required together | | `role` | Checklist role, e.g. `caretaker`, `sweeper`, `in_charge`, `security_guard`, `admin_hod`, or `hr` | | `employee_user_id` | Numeric `CSP.UM_USERS.USER_ID` used by the submission | | `status` | Checklist submission status, e.g. `in_progress` or `verified` | | `per_page`, `page` | Listing only; `per_page` 1–100, default 25; `page` defaults to 1 | Only one date-selection form can be supplied: `date`, `date_from`/`date_to`, or `year`/`month`. If omitted, the current day/week/month is used according to `grain`. A week starts on Monday and ends on Sunday. Month buckets use `YYYY-MM`; day and week buckets use their start date in `YYYY-MM-DD` format. ## 1. Checklist dashboard **Endpoint:** `GET /al_azeem_checklist_dashboard.php` Returns total checklists and task statistics for the selected window plus a `periods` breakdown grouped by the requested grain. Missing buckets are omitted; clients can fill them with zeroes. ```http GET /al_azeem_checklist_dashboard.php?grain=month&year=2026&month=10 Authorization: Bearer ``` ```json { "error": 0, "error_msg": "Al-Azeem checklist dashboard retrieved successfully", "data": { "grain": "month", "summary": { "total_checklists": 46, "total_tasks": 1508, "completed_tasks": 15, "pending_tasks": 1493 }, "periods": [{ "period": "2026-10", "total_checklists": 46, "total_tasks": 1508, "completed_tasks": 15, "pending_tasks": 1493 }] }, "filters": { "date_from": "2026-10-01", "date_to": "2026-10-31", "role": null, "employee_user_id": null, "status": null, "grain": "month" } } ``` ## 2. Checklist listing **Endpoint:** `GET /al_azeem_checklists.php` Returns a paginated list of checklist submissions for the selected period. Each submission includes employee identity and role, checklist/task date, submission status/time, task counts, and the checklist's task names and completion statuses. The list is paginated by submission, not by task. `summary` covers the full filtered set, not just the current page. ```http GET /al_azeem_checklists.php?grain=week&date=2026-10-26&per_page=25&page=1 Authorization: Bearer ``` ```json { "error": 0, "error_msg": "Al-Azeem checklist records retrieved successfully", "data": [{ "submission_id": 47, "checklist_name": "Sweeper Time-Wise Cleaning Checklist", "task_date": "2026-10-26", "user": { "user_id": 39, "name": "Example Employee", "username": "example", "employee_code": "138", "role": "sweeper" }, "submission_status": "in_progress", "submitted_at": null, "total_tasks": 43, "completed_tasks": 0, "pending_tasks": 43, "tasks": [{ "item_id": 126, "task": "Example checklist task", "time_label": "Morning", "is_done": false }] }], "summary": { "total_checklists": 1, "total_tasks": 43, "completed_tasks": 0, "pending_tasks": 43 }, "meta": {"current_page": 1, "per_page": 25, "total": 1, "last_page": 1}, "filters": { "grain": "week", "date_from": "2026-10-26", "date_to": "2026-11-01", "role": null, "employee_user_id": null, "status": null } } ``` ## 3. Checklist task detail **Endpoint:** `GET /al_azeem_checklist_detail.php` `submission_id` is required. Returns the selected checklist record, employee, role, date, submission status/time, notes, stored work/self image paths, and all checklist tasks with section, completion state, evidence, note, and completion time. Optionally provide `item_id` to return only that task while the task-count summary still describes the whole checklist. A missing submission or task returns HTTP 404. ```http GET /al_azeem_checklist_detail.php?submission_id=47 Authorization: Bearer ``` ```json { "error": 0, "error_msg": "Al-Azeem checklist detail retrieved successfully", "data": { "submission_id": 47, "checklist_name": "Sweeper Time-Wise Cleaning Checklist", "task_date": "2026-10-26", "submission_status": "in_progress", "submission_date": "2026-10-26", "submitted_at": null, "user": { "user_id": 39, "name": "Example Employee", "username": "example", "employee_code": "138", "role": "sweeper" }, "reports_to": "Sanctuary In-Charge", "staff_note": null, "work_image_path": "checklists/47/work.jpg", "self_image_path": "checklists/47/self.jpg", "total_tasks": 43, "completed_tasks": 1, "pending_tasks": 42, "tasks": [{ "item_id": 126, "section": {"section_id": 17, "title": "Morning", "sort_order": 1}, "task": "Example checklist task", "time_label": "Morning", "sort_order": 1, "is_done": true, "evidence": ["physical_log"], "note": null, "completed_at": "2026-10-26 08:30:00" }] } } ``` ## Live data verification The CSP Oracle schema currently contains six checklist templates, 46 submissions, and 1,508 checklist task instances across the inspected data. These figures are database-wide at the time checked, not fixed API values. The endpoint queries are scoped by the selected date/filters and will change as new checklists are submitted.