PRD: Agent manager groups
| Module | Helpdesk | PRD ID | PRD-AGT-001 |
| Status | Ready to dev | FEAT | AGT |
| Epic | — | Plane | BANA-1501 |
| Date | 2026-06-03 | Version | v1.1 |
| Packages | @nx/helpdesk | URD | AGT |
| Surface | BO · Ops | ||
| Owner | Phát Nguyễn | ||
TL;DR
A cluster of back-office screens for the operations team (NEXPANDO & VNPAY) to manage support agents and ticket routing: an agent list and profile (including work schedules), a "Manage groups" dialog on the agent screen, a unified member-edit flow on the group screen, and a prioritized assignment-rule management screen - all scoped per organizer, with group names that must not repeat within one organizer. Grouping and auto-routing become self-serve instead of piecemeal, low-level edits.
1. Context & Problem
The Helpdesk agent model already carries agents, agent groups, and assignment rules - but the back-office surface to manage them is incomplete. Membership can only be edited piecemeal, group names carry no uniqueness rule, and assignment rules have no management screen. The operations team can't curate who belongs where or how tickets route without ad-hoc, low-level changes.
This increment builds that missing surface on top of the existing agent-group and assignment-rule domain. The whole screen cluster is in active development: it is hidden from the Back Office menu and reachable only by direct URL until launch criteria are met.
2. Goals & Non-Goals
Goals
- Agent list and profile: see working status and current ticket load, and edit agent details - including the work schedule (weekly schedule, exception dates, temporary overrides).
- Manage an agent's group memberships from the agent screen (add/remove via the "Manage groups" dialog).
- Edit a group's members from the group screen through a single unified edit-members flow (one save applies all changes).
- Enforce unique agent-group names within an organizer.
- Carry organizer scope through every agent/group picker in these flows.
- An assignment-rule management screen, including a priority order between rules.
Non-Goals
- The auto-assignment logic itself (the worker that evaluates rules) - already present; see URD-AGT-006…007.
- Agent performance tracking (URD-AGT-008).
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Self-serve grouping | Group membership is managed entirely from the back office (no low-level edits) |
| Name uniqueness | Zero duplicate agent-group names within an organizer |
| Routing coverage | Assignment rules per organizer are created and managed through the management screen |
| Flow simplicity | Member edits go through one unified flow, not separate add/remove paths |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Support Manager - operations team (NEXPANDO & VNPAY) | Manage agents, work schedules, agent groups, memberships, and assignment rules |
| Support Agent | Be placed in the right groups with the right schedule so the relevant tickets route to them |
Core scenarios: open an agent → edit their profile and work schedule → manage their group memberships in a dialog → open a group → edit its members in one save → create assignment rules and order them by priority so new tickets route to the right place.
5. User Stories
- As a support manager, I want to add or remove an agent's group memberships from the agent screen, so I can manage grouping where I already work.
- As a support manager, I want to set an agent's work schedule (weekly schedule, exception dates, temporary overrides), so the system only routes tickets when the agent actually works.
- As a support manager, I want to edit a group's members in a single flow, so I don't juggle separate add and remove actions.
- As a support manager, I want agent-group names to be unique within my organizer, so groups don't share a name across merchants.
- As a support manager, I want a screen to create and order assignment rules by priority, so I can control how new tickets are routed.
- As a support agent, I want my group memberships to reflect my real skills/teams, so the right tickets reach me.
6. Functional Requirements
| # | Requirement | Status | URD ref |
|---|---|---|---|
| FR-1 | Agent list + form: profile, load limit, timezone, groups | ✅ built | URD-AGT-001 |
| FR-2 | Configure the agent's work schedule inside the agent form | ✅ built | URD-AGT-009 |
| FR-3 | Manage group memberships from the agent screen via the "Manage groups" dialog | ✅ built | URD-AGT-004 |
| FR-4 | Membership roles in a group (Member / Lead / Manager) | 🔶 partial | URD-AGT-004 |
| FR-5 | Agent-group list + form; edit members through one unified flow | ✅ built | URD-AGT-004 |
| FR-6 | Agent-group names unique within one organizer | 🚧 not built | URD-AGT-004 |
| FR-7 | Organizer scope across every agent/group picker | 🔶 partial | URD-AGT-001 · URD-AGT-005 |
| FR-8 | Assignment-rule list + form (name, active, target agent, strategy) | ✅ built | URD-AGT-005 |
| FR-9 | Priority order between assignment rules, reorderable | 🚧 not built | URD-AGT-005 |
| FR-10 | Applicability conditions on an assignment rule | 🚧 not built | URD-AGT-005 |
FR-1 - Agent list + form ✅
List table (no column is filterable):
| Column | Display |
|---|---|
| Name | Bilingual, shown in the selected language |
| User | Full name of the linked user |
| Available for tickets | Yes/no check |
| Status | Badge, one of 4 values: Online, Away, Offline, Busy - display only, not set by hand from the form |
| Max tickets | Number |
| Current tickets | Number |
Row actions: Edit · Delete (with a confirmation dialog) · "Manage groups" (opens the dialog - see FR-3).
Create/edit form:
| Field | Constraint |
|---|---|
| Name | Bilingual EN/VI, required, max 200 characters |
| User | Picked from the organizer's users, required; selectable only on create - on edit, the user link is locked |
| Max concurrent tickets | Number, required, minimum 1 |
| Groups | Multi-select from the organizer's groups, at least 1 group required |
| Timezone | Picked from a list of standard timezones, default Asia/Ho_Chi_Minh |
On edit, the form additionally shows (read-only): the linked user's username, email, and phone number.
FR-2 - Agent work schedule ✅
Inside the agent form, three parts:
- Weekly schedule: each day of the week (Monday → Sunday) declares its working time slots as start-end times within the day, minute-precise.
- Exception dates: declared per specific date (holidays, ad-hoc leave) - overriding the weekly schedule for that date.
- Temporary overrides: a period with a start date and an end date; the start date must be before the end date, otherwise the form shows an error and does not save.
FR-3 - "Manage groups" dialog ✅
From an agent row in the list, the "Manage groups" action opens a dialog with one multi-select of groups (limited to the organizer's groups). Saving the dialog replaces the agent's full membership list with the new selection.
FR-4 - Membership roles 🔶
Every membership carries a role. Today every membership is assigned the Member role (✅). Choosing the Lead or Manager role for a member is not yet on the interface (🚧) - once built, both the "Manage groups" dialog and the member-edit flow must allow picking a role per agent.
FR-5 - Agent-group list + form; unified member edit ✅
List table (no column is filterable): Name (bilingual) · Description (bilingual) · Active (check).
Row actions: Edit · Delete · "Edit member" (opens the member-edit dialog).
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 |
Unified member-edit flow: the "Edit member" dialog holds one multi-select of agents; one save applies all changes (additions and removals together). A failed save applies nothing - the group is never left half-edited.
FR-6 - Group names unique per organizer 🚧
Within one organizer, two agent groups must not share a name. Checked at the server on save; on a duplicate, the form shows the error at the Name field and does not save. Before enforcing the rule, existing duplicate group names must be de-duplicated per organizer. The form does not block duplicates yet.
FR-7 - Organizer scope 🔶
Every agent/group/user picker in this screen cluster shows only the data of the organizer being worked on. Applied to: the user and group pickers in the agent form, the "Manage groups" dialog, and the target-agent picker in the assignment-rule form (✅). Not yet applied to: the agent picker in the group screen's "Edit member" dialog (🚧) - it must filter by organizer like the other pickers.
FR-8 - Assignment-rule list + form ✅
List table (no column is filterable): Name (bilingual) · Active (check) · Assignment strategy (badge).
Row actions: Edit · Delete.
Create/edit form:
| Field | Constraint |
|---|---|
| Name | Bilingual EN/VI, required, max 200 characters |
| Active | On/off, default on |
| Target agent | Pick one agent of the organizer |
| Assignment strategy | Pick one of 7 values, default Manual |
The full strategy set (all 7): Manual · Round-robin · Skill-based · Load-balanced · Best experience · Fastest resolution · Skill-based round-robin.
FR-9 - Priority order between rules 🚧
Every assignment rule has a priority position within its organizer; during routing, earlier rules are evaluated first and the first matching rule wins. The operations team can reorder rules from the list screen. Today the list is flat CRUD - there is no order column and no reorder interaction yet.
FR-10 - Rule applicability conditions 🚧
A rule can declare applicability conditions (for example by ticket category) so only matching tickets pass through it. Not yet on the interface.
Acceptance criteria
- Creating an agent with Name, User, or Max concurrent tickets empty, or with no group selected → the form flags each field and does not save.
- Max concurrent tickets set to 0 or a negative number → the form shows a "minimum 1" error.
- Editing an agent → the User field is locked; the user link cannot be changed.
- Adding a temporary override in the work schedule with start date ≥ end date → the form shows an error and does not save.
- "Manage groups": unselect one group and add another, save → reopening the dialog shows exactly the new list; every membership's role is Member.
- "Edit member" on the group screen: add 2 agents and remove 1 in the same save → the member list reflects all three changes.
- (Once FR-6 is built) Creating a group with the same name as an existing group in the same organizer → rejected on save, with the error shown at the Name field.
- Creating an assignment rule with only a Name → saves with the default Manual strategy and active on; the strategy badge shows correctly in the table.
- Every agent/group/user picker in the cluster lists only the working organizer's data (once FR-7 is complete, including the "Edit member" dialog).
- (Once FR-9 is built) Swapping the order of two rules → the new order persists after reload, and new tickets are evaluated in the new order.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | An agent appears at most once in a group (no duplicate memberships); deleting an agent/group leaves no orphaned memberships |
| Tenancy & authz | Agent-group and assignment-rule operations are scoped per organizer; gated by helpdesk management permissions |
| Consistency | One member-edit save applies all changes or none; a failed save never leaves a group half-edited |
| i18n | User-facing labels/statuses are bilingual (English/Vietnamese) |
8. UX & Flows
Key screens (in the back office): the agent list + form (with work schedule), the "Manage groups" dialog, the group list + form with the "Edit member" dialog, and the assignment-rule management screen. The whole cluster is currently hidden from the menu (in development) - reachable by direct URL.
9. Data & Domain
| Concept | Role |
|---|---|
| Agent | A user of the organizer who works tickets; carries a working status (Online/Away/Offline/Busy), a concurrent-ticket limit, a timezone, a work schedule, and group memberships |
| Agent group | A named group of agents (unique per organizer once FR-6 is on), with a description and an active state |
| Group membership | The agent ↔ group link with a role (always Member today) |
| Assignment rule | An organizer's routing rule: assignment strategy (7 options), target agent, active state; priority order and applicability conditions in progress |
Conceptual only - the detailed schema lives in the helpdesk domain model.
10. Dependencies & Assumptions
Depends on
- Agent ↔ user link (URD-AGT-001) - an agent exists within a merchant before it can be grouped.
- Assignment strategies & worker (URD-AGT-006…007) - the management screen configures rules the existing auto-assignment evaluates.
- User Management (CORE-01) - agents are users linked to a merchant.
Assumptions
- The organizer has agents to group and at least one group to route to.
- The underlying agent-group and assignment-rule domain predates this increment.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Screen cluster in development, hidden from the menu | Treat as in progress; accept against the FR status table before exposing the menu |
| Rule priority order (FR-9) not built - the worker needs an order to evaluate rules | Build the order column + reorder interaction before launch; until then rule evaluation order is not user-controlled |
| The "Edit member" agent picker does not filter by organizer yet | Complete FR-7 before launch; verify no cross-organizer data leakage |
| Unique-name rule may collide on legacy duplicate group names | De-duplicate existing group names per organizer before enforcing the rule |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 - AGT is P1 (see the Helpdesk feature catalog) |
| Rollout | All organizers; the cluster is currently hidden from the menu (in development), exposed once launch criteria are met |
| Migration | De-duplicate any existing per-organizer group names before enforcing the unique-name rule |
| Launch criteria | Every acceptance criterion in §6 passes, including the 🚧 FRs (unique names, rule priority order, organizer scope for "Edit member") |
| Monitoring | Group membership changes, assignment-rule edits, and duplicate-name rejection rate |
13. FAQ
Where do I manage an agent's groups? From the agent screen - the "Manage groups" action opens a dialog to add or remove memberships in place.
Why one unified flow instead of separate add/remove? One save applies all member changes, avoiding piecemeal operations and half-edited states.
why are group names scoped per organizer and not per merchant? Group names must not repeat across an organizer's merchants, so uniqueness and assignment scoping sit at the organizer level.
Does this change auto-assignment behavior? No - the auto-assignment logic and strategies already exist; this increment only adds the screens to configure rules.
Where is the agent's work schedule set? Right inside the agent form: a per-day weekly schedule, exception dates, and temporary overrides.
References
- URD: Helpdesk - Agent Management (
AGT) - requirements (URD-AGT-001, URD-AGT-004, URD-AGT-005, URD-AGT-009) - Module: Helpdesk - URD
- Developer: @nx/helpdesk · domain model