QueueRoutingConfig Metadata Type for Omni-Channel

Why the QueueRoutingConfig Metadata Type Is the Brain of Omni-Channel#

When an incoming Case, MessagingSession, or Lead enters an Omni-Channel Queue (or is routed via an Omni-Channel Flow), QueueRoutingConfig (queueRoutingConfigs/<Name>.queueRoutingConfig-meta.xml) determines:

1. Queue Priority (routingPriority): Lower numbers (1 vs 5) are pushed to agents first across competing queues.
2. Agent Selection Algorithm (routingModel): LEAST_ACTIVE, MOST_AVAILABLE, or EXTERNAL_ROUTING.
3. Work Item Size (capacityWeight vs. capacityPercentage): How much of an agent’s capacity (defined in PresenceUserConfig) one work item consumes—including separate pausedCapacityWeight (API v64.0+) when status-based work is paused.
4. Push Timeouts & Skill Fallback (pushTimeout, dropAdditionalSkillsTimeout): How long an agent’s widget rings before re-routing, and when optional skills are dropped so work doesn’t stall.

Key Metadata Fields on QueueRoutingConfig#

Real-World XML Example (queueRoutingConfigs/VIP_Case_Routing.queueRoutingConfig-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<QueueRoutingConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <capacityWeight>2.0</capacityWeight>
    <dropAdditionalSkillsTimeout>120</dropAdditionalSkillsTimeout>
    <isAttributeBased>false</isAttributeBased>
    <isInterruptible>true</isInterruptible>
    <label>VIP Case Routing</label>
    <pausedCapacityWeight>0.5</pausedCapacityWeight>
    <pushTimeout>45</pushTimeout>
    <routingModel>MOST_AVAILABLE</routingModel>
    <routingPriority>1</routingPriority>
</QueueRoutingConfig>

Querying QueueRoutingConfig and Linked Queues via SOQL#

You can query QueueRoutingConfig in standard SOQL and join it to Group (Type = 'Queue') to audit your entire Omni-Channel routing matrix.

1. Audit All Omni-Channel Routing Configurations by Priority#

SELECT Id, DeveloperName, MasterLabel, RoutingPriority, RoutingModel,
       CapacityWeight, CapacityPercentage, PushTimeout, DropAdditionalSkillsTimeout
FROM QueueRoutingConfig
ORDER BY RoutingPriority ASC, DeveloperName ASC

2. Find Which Queues Use Each QueueRoutingConfig#

SELECT Id, Name, DeveloperName, QueueRoutingConfigId
FROM Group
WHERE Type = 'Queue'
  AND QueueRoutingConfigId != null
ORDER BY Name ASC

Senior Architect Best Practices#

• Link QueueRoutingConfig Inside Your Queue Metadata: A QueueRoutingConfig does nothing on its own until it is referenced by <queueRoutingConfig>VIP_Case_Routing</queueRoutingConfig> inside a Queue metadata file or selected in an Omni-Channel Flow Route Work action. Always deploy QueueRoutingConfig before (or alongside) Queue.
• Use MOST_AVAILABLE When Mixing Part-Time and Senior Agents: If senior agents have a total capacity of 10 and junior agents have a capacity of 4, LEAST_ACTIVE will keep routing to a junior agent with 2 active items over a senior agent with 3 active items. MOST_AVAILABLE routes to the senior agent (7 free units vs. 2 free units).

Frequently asked questions

What is the difference between Least Active and Most Available routingModel in QueueRoutingConfig?

LEAST_ACTIVE routes the incoming work item to the agent holding the lowest total amount of consumed capacity, whereas MOST_AVAILABLE routes the work item to the agent with the largest remaining unused capacity (Configured Capacity minus Consumed Capacity).

Can you set both capacityWeight and capacityPercentage on the same QueueRoutingConfig?

No. A QueueRoutingConfig must specify either capacityWeight (exact unit weight consumed per work item) or capacityPercentage (percentage of the agent's total capacity consumed), never both.

What does dropAdditionalSkillsTimeout do in a QueueRoutingConfig?

When using skills-based routing with skills marked as additional, dropAdditionalSkillsTimeout specifies the number of seconds Omni-Channel waits for an agent with all skills before dropping additional skills to expand the eligible agent pool.

How do you query QueueRoutingConfig records using SOQL?

You can query the QueueRoutingConfig standard object in SOQL to inspect DeveloperName, MasterLabel, RoutingModel, RoutingPriority, CapacityWeight, CapacityPercentage, and PushTimeout.