PRD: Helpdesk SLA & Classification Configuration (Back Office)

Module	Helpdesk	PRD ID	PRD-SLA-001
Status	Ready to dev	FEAT	SLA
Epic	—	Plane	BANA-1742
Date	2026-06-30	Version	v1.1
Packages	@nx/helpdesk	URD	SLA
Surface	BO · Ops
Owner	Phát Nguyễn

TL;DR

Lets the operations team (NEXPANDO & VNPAY) configure how tickets are measured and classified from the back office: define SLA policies (each policy tied to one priority level, response/resolution targets in minutes, escalation rules), and maintain the classification tickets carry - categories with routing defaults and a custom ticket form, tags, and the five priority levels. This is the policy side of helpdesk; working tickets and routing agents are separate areas.

1. Context & Problem

The helpdesk engine already measures tickets against SLAs and classifies them by category, tag, and priority - but there is no managed place to author SLA policies or to maintain the categories, tags, and priorities that drive routing defaults. The operations team had to rely on low-level edits.

This increment is that configuration surface. It complements Agent management (who works tickets and how they route) by covering what targets tickets must meet and how they are classified. The whole screen cluster is in active development: hidden from the Back Office menu, reachable only by direct URL.

2. Goals & Non-Goals

Goals

• Author SLA policies - each policy tied to one priority level, response and resolution targets in minutes, an optional business-hours-only clock, and a list of escalation rules.
• Maintain ticket categories - routing defaults (priority, skills, SLA policy) and a custom ticket form per category; parent/child hierarchy and a default handling group are in progress.
• Manage tags used to label tickets.
• Maintain the five priority levels (Low, Medium, High, Urgent, Critical).

Non-Goals

• The SLA monitor and the auto-assignment worker themselves - already built behind the scenes.
• Agents, agent groups, and assignment rules (Agent management).
• Working individual tickets (the ticket lifecycle).

3. Success Metrics

Metric	Target / signal
Self-serve policy	The operations team authors an SLA policy without low-level edits
Routing-by-default	Classifying a ticket under a category applies that category's defaults (priority, SLA, form)
Coverage	Every priority level has at least one active SLA policy

4. Personas & Use Cases

Persona	Goal in this feature
Support manager - operations team (NEXPANDO & VNPAY)	Define SLA targets and the category/tag/priority scheme tickets use

Core scenario: a manager creates one SLA policy per priority level, with response and resolution targets in minutes and escalation rules; builds categories, giving each its default priority, required skills, SLA policy, and its own ticket form; and maintains the tags and priority levels the team uses to classify tickets.

5. User Stories

• As a support manager, I want to define SLA targets per priority level, so tickets are measured against one standard.
• As a support manager, I want escalation rules that fire before and upon an SLA breach, so the team is alerted in time.
• As a support manager, I want categories with routing defaults, so classified tickets receive their priority and SLA automatically.
• As a support manager, I want each category to have its own ticket form, so tickets of each type capture exactly the information that type needs.
• As a support manager, I want to manage tags and priority levels, so tickets are labelled and ranked the way we work.

6. Functional Requirements

#	Requirement	Status	URD ref
FR-1	SLA-policy list + form (1 policy = 1 priority level; targets in minutes; business-hours-only; active)	✅ built	URD-SLA-001 · URD-SLA-002 · URD-SLA-003
FR-2	Warning and critical thresholds as a % of SLA time	🚧 not built	URD-SLA-007
FR-3	Escalation rules within a policy: a freely add/remove/reorder list of rules	✅ built	URD-SLA-009
FR-4	Ticket-category list + form (routing defaults: priority, skills, SLA policy)	✅ built	URD-CAT-001
FR-5	Parent/child categories and a category's default handling group	🚧 not built	URD-CAT-002
FR-6	Custom ticket form per category (form builder: pick fields, order them, 13 field types, preview)	✅ built	URD-CAT-001
FR-7	Ticket-tag list + form (create, edit, remove)	✅ built	URD-CAT-003
FR-8	Five priority levels (Low, Medium, High, Urgent, Critical) used throughout	✅ built	URD-CAT-005
FR-9	A category's SLA policy overrides the global default for its tickets	✅ built	URD-SLA-010

FR-1 - SLA-policy list + form ✅

List table:

Column	Display	Filterable
Name	Bilingual, in the selected language	No
Priority	Badge, 1 of 5 levels	Yes - the only filterable column
Active	Check	No
Business hours only	Check	No
Response time (minutes)	Number	No
Resolution time (minutes)	Number	No

Row actions: Edit · Delete. Toggling active happens in the edit form.

Create/edit form:

Field	Constraint
Name	Bilingual EN/VI, required, max 200 characters
Priority	Pick one of the 5 levels - each policy is tied to exactly one priority
Response time	Minutes, minimum 1, default 5
Resolution time	Minutes, minimum 1, default 10
Business hours only	On/off, default off - when on, the SLA clock runs only during business hours
Active	On/off, default on

FR-2 - Warning / critical thresholds 🚧

Each policy declares two thresholds as a % of elapsed SLA time: a warning threshold and a critical threshold, so the team is alerted before a breach. The concept exists in the domain but is not on the form yet - once built, both % fields live in the policy form and escalation rules can reference them.

FR-3 - Escalation rules within a policy ✅

A list of rules inside the policy form, freely added/removed and drag-reordered - no fixed number of levels. Each rule holds:

Part	Constraint
Rule name	Required
Event	Pick 1 of 2: Warning · Breach
Applies to	Pick 1 of 2: First response · Resolution
Trigger	Type: % of SLA elapsed or time elapsed; the value is a number greater than 0
Actions	At least 1; each action: a type (Notify / Send email / Assign agent), targets (Agent / Manager - must not be empty), channels (Websocket / Email - must not be empty)

Business rule: within one policy, no two rules may share the same triple (event + applies-to + trigger type) - the form blocks the save.

FR-4 - Ticket-category list + form ✅

List table (flat, no column is filterable): Name (bilingual) · Description (bilingual) · Active (check). Actions: Edit · Delete.

Create/edit form:

Field	Constraint
Name	Bilingual EN/VI, required; with an icon and colour picker attached to the category
Description	Bilingual EN/VI, optional, max 400 characters
Default priority	Optional, pick 1 of the 5 levels - tickets classified under the category receive it
Sort order	Number, default 1 - decides the category's position in selection lists
Required skills	Multi-select from the skill catalogue - used for skill-based routing
SLA policy	Required, pick one of the organizer's policies - the default SLA for the category's tickets
Active	On/off

FR-5 - Parent/child categories + default handling group 🚧

Two properties exist in the domain but are not on the form yet:

• Parent category: a category can pick a parent to form a hierarchy; the parent's defaults cascade to children unless a child declares its own. The list is flat today - once built, the form needs a parent picker and the list a way to show the hierarchy.
• Default handling group: a category points at an agent group (Agent management) so its tickets route straight to that group.

FR-6 - Custom ticket form per category (form builder) ✅

The largest part of the category screen: each category defines its own ticket form - a ticket created under a category shows that category's form.

• Pick fields: tick the fields that will appear on the ticket form.
• Order them: drag-and-drop to reorder the selected fields.
• 13 field types: short text, paragraph, number, date, date-time, time, on/off switch, single select (list), single select (radio group), multi select (checkboxes), file attachment, field group, repeating group (an addable list of rows).
• Nested fields: field groups and repeating groups contain child fields, configured like regular fields.
• Width: each field takes a width on a 12-column grid (1-12).
• Preview: the form is rendered live inside the configuration screen, exactly as the ticket creator will see it.

FR-7 - Ticket-tag list + form ✅

List table (no column is filterable): Name (bilingual) · Description (bilingual) · Active (check) · Created at · Updated at. Actions: Edit · Delete.

Create/edit form:

Field	Constraint
Name	Bilingual EN/VI, required, max 200 characters
Description	Bilingual EN/VI, optional, max 400 characters
Active	On/off, default on

A tag colour exists in the domain but is not on the form yet (🚧).

FR-8 - Five priority levels ✅

One fixed set of 5 levels used everywhere (policies, categories, tickets): Low · Medium · High · Urgent · Critical - in ascending rank. The set is system-fixed; levels cannot be added or removed from the interface.

FR-9 - A category's SLA overrides the default ✅

Tickets classified under a category are measured against that category's SLA policy instead of the global default. On the interface, the link is the category form's required SLA-policy field.

Acceptance criteria

1. Creating an SLA policy with Name empty or no Priority selected → the form flags the fields and does not save.
2. Response or resolution time set to 0 → the form shows a "minimum 1 minute" error.
3. Each policy accepts exactly one priority level; a new policy with defaults → response 5 minutes, resolution 10 minutes, active on, business-hours-only off.
4. The SLA-policy table filters by Priority; no other column offers a filter.
5. Adding two escalation rules with the same triple (event + applies-to + trigger type) → the form blocks the save.
6. An escalation rule with no action, or an action with empty targets/channels, or a trigger value ≤ 0 → the form shows an error.
7. Creating a category without an SLA policy → the form shows an error; a description over 400 characters → the form shows an error.
8. Form builder: pick 3 fields, drag one to reorder, set one field to width 6/12 → the preview shows the right fields, order, and width.
9. Creating a tag with a name over 200 characters → the form shows an error; a new tag shows Created at/Updated at in the table.
10. The whole cluster does not appear in the Back Office menu (in development) but opens via direct URL.
11. (Once FR-2 is built) A policy with an 80% warning and 95% critical threshold → "Warning"-event escalations fire against the declared thresholds.
12. (Once FR-5 is built) A child category with no priority of its own → inherits the parent's; a category with a default group → new tickets under it route to that group.

7. Non-Functional Requirements

Area	Requirement
Tenancy & authz	Configuration is gated to helpdesk-management permissions; the SLA-policy picker in the category form lists only the working organizer's policies
Consistency	Category defaults apply to tickets classified under them; a category's SLA overrides the global default
Safety	Editing a policy or category does not retroactively rewrite tickets already measured
i18n	Policy, category, and tag names/descriptions and priority labels are bilingual (EN/VI)

8. UX & Flows

How a manager configures helpdesk policy:

What the configuration covers:

The screens live in the Back Office "Support" section, alongside Agent management. The whole cluster is currently hidden from the menu (in development) - reachable by direct URL.

9. Data & Domain

Concept	Role in this screen
SLA policy	Tied to one priority level; response/resolution targets in minutes; business-hours option; a list of escalation rules; % thresholds (in progress)
Category	A class of ticket carrying an icon/colour, default priority, required skills, an SLA policy, and a custom ticket form; parent/child and default group (in progress)
Tag	A label applied to tickets; tag colour (in progress)
Priority	One of five fixed levels (Low, Medium, High, Urgent, Critical)

Conceptual only - the SLA monitor and routing engine run behind the scenes; the data model is in the helpdesk domain model.

10. Dependencies & Assumptions

Depends on

• SLA monitor & routing engine - already built; these screens configure what it enforces.
• Agent management (PRD-AGT-001) - a category's default handling group (FR-5) points at an agent group; skill-based routing uses the category's required skills.

Assumptions

• The manager is authenticated with helpdesk-management permissions.
• The helpdesk engine (SLA tracking, classification) predates this configuration surface.

11. Risks & Open Questions

Risk / question	Mitigation / status
Screen cluster in development, hidden from the menu	Accept against the FR status table in §6 before exposing the menu
% thresholds (FR-2) not built while the "Warning" escalation event already exists	Decide the threshold source for the Warning event when building FR-2; until then Warning rules rely on their own trigger condition
Editing a policy could affect in-flight tickets	Changes apply going forward; in-flight measurements are not rewritten
Category hierarchy (FR-5) not built - the list is flat today	Once built, show the hierarchy in the list and cap the depth at 3 levels

12. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - in active development in the Back Office
Rollout	Operations team with helpdesk-management permissions; the cluster stays hidden from the menu until launch criteria are met
Migration	None - it configures the existing engine
Launch criteria	Every acceptance criterion in §6 passes, including the 🚧 FRs (% thresholds, parent/child categories + default group)
Monitoring	SLA-policy and category edits; share of tickets classified under a category

13. FAQ

Is this where tickets are worked? No - this configures SLA policy and classification; working tickets is the ticket lifecycle.

Where are agents and routing rules? In Agent management.

What does a category's SLA do? It overrides the global default for tickets classified under that category.

Can one SLA policy cover several priority levels? No - each policy is tied to exactly one level; covering all five means creating five policies.

Where does the custom ticket form show up? A ticket created under a category shows exactly the form that category defined in the form builder.

References

• URD: Helpdesk - SLA · CAT (Categories, Tags & Priorities)
• Related: PRD-AGT-001 - Agent manager groups
• Module: Helpdesk - URD · Roadmap: Phase 2 - By Month
• Developer: @nx/helpdesk