Queues and omni-channel routing

A queue is a named routing target: it points at a pool of agents and a routing model, and xMatix uses it to offer a call, a case or another record to one available agent. Queues sit between the channels that bring work in (phone numbers, mailboxes, new cases) and the agents who work it. An administrator sets up the people and their resource groups first, then the queues, then points the ways work comes in at those queues.

Overview

Each queue has five settings: a Name, a Routing model, the Channels it is meant for, an Agent pool (a resource group) and Active. A queue holds no member list of its own. The people come from the resource group, so you staff a queue by changing its group.

When something sends work to a queue, the routing service creates a Resource Work item for it. If an eligible agent is found, the item is offered to that agent (status Assigned). If nobody qualifies, it waits (status Pending). An offer is not an assignment. A case's Assigned To and Owner change only when the agent accepts the work.

When to use it

Use a queue when work should go to whoever on a team is free, not to one named person:

• an inbound phone number that should ring one free agent on a team;
• emails turned into cases by a mailbox rule, which should land with the support team;
• new cases that should be shared out as they are logged;
• high-priority or specialist work that only part of the team should handle (a separate queue and pool, or a skill).

Several queues can share one pool, and one agent can be in the pools of several queues.

How xMatix handles it

What sends work to a queue

Who is eligible for an offer

An agent is offered the work only when all of these are true:

1. In the pool. Their resource is a member of the queue's resource group.
2. Active and linked. Their resource record is active and linked to a user account.
3. Available, now. Their presence is Available, and their browser has renewed it within the last five minutes. Agents set their availability in the Calls drawer (see Using the softphone). The browser renews it every minute while they are online. Closing the tab sets them Offline. A crashed or sleeping browser stops counting after five minutes.
4. Room for it. Their open work (items Assigned or Accepted to them, across every queue) plus the new item fits under their work limit. Each item counts as one, and the limit is 5 unless it was changed through the API. No screen changes it.
5. The skill, if one was asked for. On a Skill-based queue, when the request names a skill, only agents with a Resource Skill of exactly that name at level 1 or higher stay in. See Skills.

If nobody passes, the work item is created as Pending. Nothing re-checks Pending items later: an agent going Available or finishing work does not pull them. Pending work moves only when something routes it again or a supervisor reassigns it.

Agent presence

Each agent's availability is kept on one Resource Presence record for their resource. It holds their Status (Available, Busy, Away or Offline), an optional Status Reason, their work limit (Max Work Items) and Last Changed On, the time the record was last written or renewed. Nobody creates these records by hand. The first time an agent picks a status in the Calls drawer, xMatix creates their record, and every later change updates the same record.

The Calls drawer writes presence for the agent at these moments:

The countdown sets Available even if the agent chose Away during the call, so check the pill after each call.

Presence is a lease. When a browser crashes, sleeps or loses its network, it publishes nothing, so routing goes by the timestamp. An agent whose Last Changed On is more than five minutes old is treated as Offline even though the record still says Available. A record with an empty Last Changed On is always treated as live. Renewing never brings an agent back from Offline. Only the agent picking a status does that.

The Chats drawer has its own status control with a reason box. That status stays in the browser. It is not saved to the presence record and routing does not read it.

The routing models

Ties go to the same agent each time, so on a quiet queue with Load balance, the same person tends to get the first offer.

What Active and Channels do

Routing reads neither of them. A phone route, mailbox rule, case or business rule that names an inactive queue still routes work through it. Routing also never compares the arriving channel with the queue's Channels. Active matters in two other places:

• an agent gets the call and chat dock only when they are in the pool of at least one active queue (and Telephony is switched on for your organization);
• the supervisor's queue backlog lists active queues only.

Accept, decline, transfer and reassign

These four steps are part of the omni-channel service API. None of the shipped web or mobile screens offers them, so they are used through an integration or a custom page:

• Accept: the item becomes Accepted. For a case, this sets the case's Assigned To and Owner to the agent's user.
• Decline: the item becomes Declined and is routed again through the same queue, leaving out the agent who declined. A skill from the first request is not carried over.
• Transfer: the item becomes Transferred, and a new item is offered either to a named agent or through another queue.
• Reassign (needs Supervise telephony (CTI)): the item is pointed at another agent and goes back to Assigned.

Item statuses are Pending, Assigned, Accepted, Declined, Transferred and Closed.

Prerequisites

• Telephony is part of your subscription, if you route calls or want the agent dock. The Telephony menu in Setup appears only then.
• Each agent exists as a resource with Is Active on and a linked User.
• A resource group holds the agents who will work the queue.
• To create queues you have the Manage telephony (CTI) capability.

Procedure

Step 1 — Create the queue

1. Go to Setup → Feature Hub → Service → Telephony → Queues. The table lists each queue's Name, Routing model, Channels, Agent pool and Status.
2. Choose New queue in the page header.
3. Enter a Name (required, up to 100 characters), for example Level 1 support.
4. Choose a Routing model. The dialog suggests Round robin.
5. Add a Description if it helps other administrators.
6. Pick the Channels the queue is for. The dialog suggests Voice. This is a label only (see above).
7. Choose the Agent pool: the resource group whose members take the work.
8. Leave Active on, and choose Create.

The queue appears in the table with the status Active. It is now available in the phone-route, mailbox-rule, case and business-rule queue pickers.

Queues are also listed under Support → Settings → Queues and CRM → Settings → Queues. Those forms have no Name field, so create and rename queues on the Setup screen.

Step 2 — Get agents online

Each agent opens the Calls drawer and sets their availability to Available. Agents only see the drawer once they are in the pool of an active queue. If you have just added someone to the group, they may need to sign in again. See Using the softphone.

Step 3 — Point work at the queue

Use one or more of these:

• Phone number: in Setup → Feature Hub → Service → Telephony → Routing, create or edit the number's route, set Route to to Queue and choose the queue. See Inbound routing.
• Mailbox: in Setup → Feature Hub → Platform → Mailboxes, open the mailbox, then on the Inbound rules tab edit a rule whose Creates is a case (or Auto) and choose the Default queue.
• A single case: open the case, go to the People & Queue tab and set Queue. The Auto-route new cases rule routes it when the change is saved.
• A business rule: see Step 4.

Step 4 — Route records with a business rule

1. Go to Setup → Process Studio → Business Rules and create or open a rule on the entity you want routed. Give it the OnSavedChanges trigger, because routing runs only after the record is saved. The screen refuses to save this action on a rule without that trigger.
2. Add a condition if only some records should go, for example Priority == "High".
3. On the Actions tab add a Route to queue action and fill in:
   • Queue: the queue to use. Leave it, and Or straight to a resource, empty to use the record's own Queue field.
   • Or straight to a resource: offers the work to one person and skips the queue's routing model.
   • Required skill: for a Skill-based queue, the exact skill name agents must hold.
   • Channel: leave it empty to use the record's source or channel.
4. Activate the rule and test it from its Test Runner tab. See Business rules.

Step 5 — Change or retire a queue

On Setup → Feature Hub → Service → Telephony → Queues, use Edit in the row's actions to change any setting, then Save. The change applies to the next item routed. Work already offered stays where it is.

To retire a queue, first point the phone routes, mailbox rules, business rules and cases that use it at another queue. Then switch Active off, or choose Delete and confirm. Remember that switching Active off does not stop routing.

Step 6 — Check who is online and change a work limit

1. Open the Agents tab of the Supervisor Console. It shows each agent's effective presence (an expired lease shows Offline) and their open load. The shipped Omni Supervisor dashboard also has an Agents by Presence chart and a Utilisation tile, but those read the stored status (see Business rules).
2. To give an agent a different work limit, change Max Work Items on their presence record. No shipped screen or menu opens Resource Presence records, so use the data API: find the record with GET /api/1.0/data/ResourcePresence filtered on the agent's resourceId, then send PATCH /api/1.0/data/ResourcePresence/{id} with maxWorkItems. The agent must have picked a status at least once, or there is no record to change.
3. The new limit applies the next time work is routed. Offers already made stay where they are.

An administrator can also design a form for the entity in the layout designer. Without one, a record opened by its address shows read-only.

Fields

The full field list is in the Queue entity reference.

Resource Presence fields

The same list is in the Resource Presence entity reference.

Business rules

• Auto-route new cases (shipped, active) routes a case to its Queue after every save, not only when the case is created. Each save of a case that has a Queue creates another Resource Work item. Each one is offered, and counts against the agent's limit, until it is closed. If your desk edits cases often, add a condition to the rule, or replace it with your own rule that runs only when Queue changes.
• Set Case Queue To High Priority (shipped, active) fills an empty Queue on a new High priority case with a specific queue that does not exist in a new organization. Until you point it at one of your queues or switch it off, routing for those cases fails silently and the case shows an unresolved queue.
• Route High-Priority Cases (shipped, inactive) is an example of routing high-priority cases to one named queue. It needs the same edit before you activate it.
• Routing never blocks or undoes the save that started it. A failure is only logged.
• When a phone route's queue has nobody eligible, the Pending item is kept and the call rings every signed-in agent instead. See Inbound routing.
• A presence record is created with Offline, a work limit of 5 and the current time when those are left empty. Afterwards each status change replaces Status Reason, so an old reason never sticks to a new status.
• Routing and the Supervisor Console use the effective status: a lease older than five minutes counts as Offline. The Agents by Presence chart on the Omni Supervisor dashboard and the Who Is Available Right Now chart on the Roster & Capacity dashboard count the stored Status, so an agent whose browser crashed still shows there as Available. The Seats available figure behind the Utilisation tile adds up Max Work Items for every presence record, whatever its status.
• xMatix finds an agent's presence record through the resource linked to their user. If one user is linked to two resources, only one of them is used. Link each agent's user to one resource only.

Example

A support team of four handles calls on the support number and emails sent to the help mailbox.

1. The administrator creates a resource group Support level 1 with the four agents, each an active resource linked to their user.
2. In Setup → Feature Hub → Service → Telephony → Queues they choose New queue: Name Level 1 support, Routing model Round robin, Channels Voice and Email, Agent pool Support level 1, then Create.
3. On Routing they set the support number's route to Queue → Level 1 support. On the help mailbox's Inbound rules they set the case rule's Default queue to the same queue.
4. At 09:00 three agents set themselves Available in the Calls drawer. The fourth stays Away.
5. A call arrives. The three available agents have never been offered work, so the first by internal order gets it and their softphone rings. The next call goes to one of the other two, and so on.
6. An email arrives. The mailbox rule creates a case with Queue Level 1 support, and Auto-route new cases offers it to the available agent offered work least recently.

Training

Practice exercise

In a sandbox with Telephony and at least one phone number:

1. Create a resource group with two resources, each active and linked to a test user.
2. Create a queue Practice queue with Routing model Load balance and that group as Agent pool.
3. On Routing, point a test number's route at Practice queue.
4. Sign in as the first test user in one browser and as the second in another. Both now see the Calls drawer. Set the first to Available and the second to Away.
5. Call the test number.
6. Set the first user to Away as well, and call again.

Expected result: the first call rings only the first user's softphone. The second call, with nobody Available, rings every signed-in agent. Then open a case, set Queue to Practice queue on People & Queue and save. The case's Assigned To does not change, because routing only offers the work.

Quick reference

• Create queues at Setup → Feature Hub → Service → Telephony → Queues.
• A queue's people are its resource group's members.
• An offer needs an active resource, linked user, Available presence renewed in the last five minutes, and room under the work limit (5).
• Blank routing model = Load balance.
• Active and Channels are not checked by routing.
• Routing offers. Accepting sets the case's Assigned To and Owner.
• Pending work is never picked up automatically.
• Auto-route new cases runs on every save of a case with a Queue.
• After a call, the agent is Busy (ACW) for 45 seconds, then Available again.
• A lease not renewed for five minutes counts as Offline. Dashboards still show the stored status.
• Change a work limit through the data API (Max Work Items on Resource Presence). No screen does it.

Permissions

A user without Manage telephony (CTI) does not see the Telephony group in Setup.

Configuration

Common problems

Calls to the queue ring everybody

Nobody in the pool was eligible, so the call fell back to every signed-in agent. Check the queue has an Agent pool and that its members are active resources linked to users. Then check they are Available in the Calls drawer and under their work limit.

An agent who was getting offers has stopped getting any

Their open work has reached the limit of 5. Shipped screens never accept, decline or close work items, so every offer stays Assigned and keeps counting. A case saved several times with a Queue also creates one item per save. Free the agent's finished items: decline or transfer them through the omni-channel API, or have an integration set them to Closed. Then limit Auto-route new cases so it does not re-route on every edit.

An agent shows Available but is never offered work

Check, in this order:

• The lease. Their browser may have stopped renewing it (a sleeping laptop, a lost network). The Supervisor Console shows them Offline. Have them reload the page and pick Available again.
• The work limit. Their open items may already fill Max Work Items, or the limit was set to 0. Compare open load and limit on the Supervisor Console's Agents tab.
• The resource. Their user may be linked to two resources, and the presence record belongs to the one that is not in the pool. Keep one resource per user.

The dashboard says agents are Available, but calls ring everybody

The Agents by Presence and Who Is Available Right Now charts count the stored status. Agents whose browsers closed without signing off still count as Available there for good, while routing treats them as Offline after five minutes. Use the Supervisor Console's Agents tab for the live picture.

"No routing resource is linked to your user account."

An integration that sets presence through the omni-channel API gets this reply when the signed-in user has no resource linked. The Calls drawer does not show this message: it appears only for users whose resource is in an active queue's pool, and it does not report a failed status save. Link the user on their resource record and try again.

The case was routed but still shows the old Assigned To

This is expected. Routing only offers the work, and Assigned To and Owner change when the agent accepts. Set Assigned To by hand, or accept through the API.

High-priority cases show a queue that doesn't exist

The shipped Set Case Queue To High Priority rule still names its original queue. Edit the rule's value to one of your queues, or switch the rule off.

An agent can't see the Calls drawer

They are not in the pool of any active queue, their resource is not linked to their user, or Telephony is off. Fix that, then have them sign in again.

"Routing requires the case's QueueId, or a queueId/resourceId argument."

The case's Route action ran with no Queue on the case and none given. Set Queue on People & Queue and try again.

Common questions

Does switching a queue to inactive stop work reaching it?

No. Routing does not check Active, so phone routes, mailbox rules, cases and business rules that name the queue still send work through it. Inactive does take the queue out of the supervisor backlog. It also takes away the call and chat dock from agents who are in no other active queue. To stop work, point every source at another queue first, then deactivate or delete it.

Can one agent work several queues?

Yes. Put them in each queue's resource group. Their work limit is one number across everything they hold, so an item from one queue counts against offers from all the others. Round robin and Load balance look at all of the agent's work, not just the work from this queue.

What happens to work when nobody is available?

It is created as Pending against the queue and stays there. Nothing re-routes it when an agent becomes Available, so someone has to route it again or a supervisor reassigns it through the API. Calls are different: besides leaving a Pending item, the call rings every signed-in agent so it is not missed.

Can an agent have a different limit for calls and for cases?

No. Routing uses one number, Max Work Items on the agent's presence record, for everything the agent holds. The record also has a Max Per Channel field, but routing does not read it, so filling it in changes nothing. To keep an agent's call work and case work apart, give them a lower overall limit, or put them only in the pools of the queues they should serve.

Does my chat status affect routing?

No. The status you pick in the Chats drawer stays in your browser and is not saved. Routing reads only the status from the Calls drawer. Setting the Calls status to Away or Offline stops new offers from every queue, including queues that route cases and emails.

Do I need the Channels setting for email or chat queues?

Not for routing. Routing ignores it. Fill it in so that other administrators can see what each queue is for when they pick a queue for a phone route or mailbox rule.

Related topics

• Resource groups
• Resources
• Skills
• The case lifecycle
• Inbound routing
• Telephony configuration
• Using the softphone
• Business rules
• Support configuration reference
• Troubleshooting the support desk
• Queue entity reference
• Resource Presence entity reference
• Supervisor Console
• Data API