Agent & Assignment

@nx/helpdesk manages the support agent team with a dual assignment system: manual assignment via the API and auto-assignment via AutoAssignTicketUseCase running on a BullMQ worker.

Data Model

Agent

Column	Type	Description
id	bigint	Snowflake ID
merchantId	bigint	Tenant scope
userId	bigint	Unique link to a User in @nx/identity
status	enum	ONLINE / AWAY / OFFLINE / BUSY
isAvailable	boolean	Whether the agent accepts new tickets
skills	varchar[]	Skills (e.g. ['billing', 'technical'])
languages	varchar[]	Supported languages (default ['vi'])
maxConcurrentTickets	smallint	Concurrent ticket cap (default 10)
currentTicketCount	int	Number of currently active tickets
averageResponseTime	int	Average first-response time (minutes)
averageResolutionTime	int	Average resolution time (minutes)
slaComplianceRate	decimal	SLA compliance rate (0.0 − 1.0)
customerSatisfactionScore	decimal	CSAT score
schedule	jsonb	Working schedule (hours/days off)

AgentGroup

Groups of agents organized by department or skill set.

Column	Type	Description
id	bigint	Snowflake ID
merchantId	bigint	Tenant scope
name	jsonb	Group name (i18n: {en, vi})
description	jsonb	Group description
isActive	boolean	Active flag

AgentGroupMember

Junction table linking Agent ↔ AgentGroup.

REST API

Agents (/agents), agent groups (/agent-groups), and assignment rules (/assignment-rules) — full endpoint reference rendered live from /v1/api/helpdesk/doc/openapi.json. Endpoint tables are intentionally not hand-maintained.

Use Cases

Agent

Use Case	Description
CreateAgentUseCase	Create agent, link to userId
UpdateAgentUseCase	Update skills, status, schedule
DeleteAgentUseCase	Soft-delete agent
GetAgentByIdUseCase	Get details by ID
GetAgentByUserIdUseCase	Get agent by userId
ListAgentsUseCase	Paginated agent list
GetAgentTicketsUseCase	Fetch tickets by agent

Auto-Assignment

Use Case	Description
AutoAssignTicketUseCase	Orchestrates finding the best available agent
FindBestAgentUseCase	Selects agent by skills + lowest workload
FindSeniorAgentUseCase	Finds a senior agent for escalations

Auto-Assignment Flow

Agent Selection Criteria (FindBestAgentUseCase)

1. isAvailable = true and status != OFFLINE/BUSY
2. currentTicketCount < maxConcurrentTickets — not overloaded
3. Skill match against ticket.category required skills (when applicable)
4. Lowest currentTicketCount among eligible agents — load balancing

AssignmentRule

Configurable rules that override the default assignment logic:

Criterion	Description
categoryId	Apply only to a specific ticket category
priority	Ticket priority level
keywords	Keywords in subject/description
targetAgentId	Assign directly to a specific agent
targetGroupId	Assign to an agent group

Related Workers

Worker	Queue	Function
assignment.worker	helpdesk.assignment	Runs AutoAssignTicketUseCase
escalation.worker	helpdesk.escalation	Runs FindSeniorAgentUseCase on Level 2+ SLA breach

Related Pages

• Helpdesk Service — service overview
• Domain Model
• SLA & Escalation
• API Events