Admin Guide

This guide is for people in the ADMIN role — system owners who manage users, KPI catalog, settings, and oversight.

What you'll do here

Provision users + roles (USER / MANAGEMENT / ADMIN / CUSTOMER)
Configure the KPI catalog (groups, rule types, KPI types, department-KPI mapping)
Manage countries, departments, holidays
Assign pending intake tickets
Configure global app settings (date format, ticket edit window)
Review the audit log

Sidebar at a glance

The left sidebar lists every admin area. The order is curated; click to navigate:

Section	What's there
Countries	Country list + working-hours config (timezone, workday window, working days)
Departments	Department records linked to countries
Users	User accounts, roles, department assignment, active/inactive toggle
KPI Groups	Top-level KPI categories (e.g. Issue, Internal Control, Uptime)
Rule Types	The formula behind each KPI Type (rr, acr, accuracy, submit, project, ic-*, uptime). Usually only admins of admins touch these.
KPI Types	Concrete metrics tracked. Each KPI Type picks a Rule Type, sets parameters (SLA minutes, weights, targets), and belongs to a KPI Group.
KPI Items	Raw ticket data with import-from-Excel + manual editing.
Department KPIs	Which KPI Types are valid for which Departments.
Pending Tickets	Intake tickets that arrived with no assigned user — assign or delete.
Holidays	Per-country holiday calendar + import-from-Nager-API.
Audit Log	Read-only history of ticket lifecycle events.
Other KPI Settings	Global app settings (ticket edit window, date format) + Uptime unit configuration.

User management

Roles:

CUSTOMER — auto-created the first time someone signs in with Google. Can submit intake tickets and chat on their own tickets only. No internal pages.
USER — agent. Has a Department. Can self-log KPI tickets, handle assigned intake tickets, and view their own profile.
MANAGEMENT — supervisors. Can view Performance and Monthly reports. No edit access.
ADMIN — full admin access (sidebar + all settings).

Adding an internal user: Add the user via the Users admin BEFORE they try to sign in. Sign-ins from Google accounts not in the Users table are auto-provisioned as CUSTOMER. To make someone an Agent or Admin, either:

Create the user row first with their email and role (recommended), or
Have them sign in, then edit their auto-created CUSTOMER row and change the role.

Department assignment is required for USER role only; MANAGEMENT and ADMIN can be left without one.

Active = false disables sign-in and ticket creation but preserves history. Use this instead of Delete for departing staff.

Delete removes the user and all their tickets — only do this in test environments.

KPI catalog setup

Order matters when bootstrapping a new environment:

Country → set timezone, workday start/end, working days of the week.
Department → links to a country.
KPI Group → toggle "contributes to uptime" only for groups whose KPIs feed the Uptime calculation.
Rule Type → these are pre-seeded; only edit if you understand the formula.
KPI Type → pick a Rule Type, set parameters:
- For rr: responseSlaMin, resolutionSlaMin, respWeight, resoWeight.
- For submit: submitCutoffMin.
- For accuracy: respAccTarget, dataAccTarget, respAccWeight, dataAccWeight.
- For acr: six target percentages + six weights.
- For ic-*: slaWorkingDays, targetDayOfWeek, minFindings (as relevant).
- availableForIntake: true exposes the KPI Type on the public intake form.
- ignoreWorkingDayFilter: true means weekend/holiday tickets count without the override.
Department KPIs → assign each KPI Type to the Departments that should be able to log/select it.
Other KPI Settings → for Uptime KPI Types, configure unit counts per country.

Countries

The Country form sets per-country defaults used in working-hour math:

Timezone (IANA name, e.g. Asia/Jakarta).
Workday Start / End (local time of day, e.g. 10:00-19:00).
Working Days as comma-separated ISO weekday numbers (1=Mon … 7=Sun). Default 1,2,3,4,5 (Mon-Fri).

These settings drive response time, resolution time, uptime windows, and ticket inclusion filters. Change carefully — re-running rebuildKpiReports is automatic but consider the impact on historical scoring.

Holidays

The Holidays admin lets you:

Add/edit/delete holidays for any country.
Filter the list by country with the radio group.
Import public holidays from Nager.Date by picking a country + year and clicking Import. The country must have a 2-letter abbreviation (e.g. ID, US).

Holidays apply to tickets whose country matches.

Pending tickets

Intake tickets submitted without a specific user appear here.

Pick a user from the destination department's dropdown.
Click the green check to assign — the user gets an email and the ticket flips to On Progress.
Click the trash to discard (e.g. spam) — the ticket is permanently deleted.

Once assigned, the ticket lives on the agent's profile and disappears from this list.

Audit log

Path: Admin → Audit Log.

A read-only log of ticket lifecycle events. Filters: action, actor, date range. Columns: When, Who, Action, Entity, Details.

Events captured (v1):

TICKET_INTAKE_SUBMITTED — a customer (or signed-in user) submitted via intake.
TICKET_SELF_LOGGED — an agent created via /input.
TICKET_ASSIGNED — admin assigned a pending ticket.
TICKET_UPDATED — agent edited a ticket (no status change).
TICKET_STATUS_CHANGED — agent moved status forward.
TICKET_DELETED — ticket removed (pending-tickets admin or agent's profile).

Logs are append-only; nothing here can be edited or deleted from the UI.

Global settings

Other KPI Settings page has:

Ticket Edit Window (days) — USER-role accounts can only modify tickets dated within this window. ADMIN/MANAGEMENT always bypass.
Date Format — date-fns format pattern used everywhere in the app (table dates, ticket dates, email dates). Examples: dd/MM/yyyy, MM/dd/yyyy, yyyy-MM-dd.

Both fields save together when you click Save.

This page also hosts the Uptime Unit table — pairing each Uptime KPI Type with its country and unit count (number of units, e.g. number of stores).

Operational tasks

Backfilling closed tickets

If you have closed tickets pre-dating the response/resolution auto-tracking, run:

npx tsx scripts/backfill-intake-metrics.ts

It will fill in metrics.responseTimeMin, metrics.resolutionTimeMin, closedAt, and firstAgentReplyAt for closed tickets that are missing them, using createdAt, the first agent chat message, and closedAt ?? updatedAt as anchors. Then it rebuilds the KPI reports.

Rebuilding reports

KPI reports rebuild automatically on every ticket / KPI catalog change. If something looks stale (e.g. you imported a batch of holidays and the working-day exclusion didn't update), trigger a manual rebuild via:

POST /api/admin/rebuild-reports

(or just edit any ticket — it triggers the same code path.)

Importing KPI items from Excel

The KPI Items admin has an Import button that accepts an Excel file. Preview the rows first, then run. The preview shows: which rows will create, update, skip, or error. Errors usually mean unmatched user / country / department / KPI Type names — make sure those exist before importing.

Frequently asked

A user can sign in but doesn't have admin access. Check Users page — they're probably CUSTOMER (auto-provisioned). Change their role to ADMIN.

Country deletion fails with "Cannot delete country with existing department associations". Move or delete the dependent Departments first.

Holiday import says "Country has no abbreviation". Edit the Country and set a 2-letter abbreviation. Nager.Date uses ISO country codes.

The audit log has no entries before today. Audit logging started recently; pre-existing tickets aren't retroactively logged. Going forward, every ticket action is captured.

An intake ticket appears stuck in "Pending Tickets" forever. Assign it manually here. Auto-assignment only happens when the customer picked a specific user at submission.

Pick a role: Customer — Submit a ticket and chat with the agent. · Agent — Handle tickets, self-log activity, close tickets. · Management — Read dashboards and monthly reports. · Admin — Manage users, KPIs, settings, and audit history. · Developer — Public intake API reference for external integrations.