Queue Metadata Type Reference

The Queue metadata type represents a shared ownership pool for records that await triage, assignment, or Omni-Channel routing—such as inbound Lead records, support Case tickets, MessagingSession conversations, or custom objects (Invoice_Approval__c). Introduced in API version 24.0, a Queue defines which SObjects can be assigned to it (queueSobject), which users, roles, or public groups belong to it (queueMembers), and whether Omni-Channel pushes work automatically (queueRoutingConfig).

In Salesforce DX projects, queue files are stored in force-app/main/default/queues/ with the .queue-meta.xml suffix.

Key Metadata Fields#

Production-Grade XML Example#

Below is a CI/CD-safe Queue definition (Tier_3_Engineering_Queue.queue-meta.xml) that assigns membership via a Group and Role rather than brittle environment-specific usernames:

<?xml version="1.0" encoding="UTF-8"?>
<Queue xmlns="http://soap.sforce.com/2006/04/metadata">
    <doesSendEmailToMembers>false</doesSendEmailToMembers>
    <email>tier3-support@example.com</email>
    <name>Tier 3 Engineering Queue</name>
    <queueMembers>
        <publicGroups>
            <publicGroup>Tier_3_Support_Engineers</publicGroup>
        </publicGroups>
        <roleAndSubordinatesInternal>
            <roleAndSubordinateInternal>Director_Support_Engineering</roleAndSubordinateInternal>
        </roleAndSubordinatesInternal>
    </queueMembers>
    <queueSobject>
        <sobjectType>Case</sobjectType>
    </queueSobject>
    <queueSobject>
        <sobjectType>Incident</sobjectType>
    </queueSobject>
</Queue>

Querying Queues, Supported Objects, and Members with SOQL#

In Apex and SOQL, a Queue is stored as a record in the Group table where Type = 'Queue':

-- 1. Get Queue Id by DeveloperName (for assigning OwnerId in Apex/Flows)
SELECT Id, Name, DeveloperName, Email, DoesSendEmailToMembers, RelatedId
FROM Group
WHERE Type = 'Queue'
  AND DeveloperName = 'Tier_3_Engineering_Queue'

-- 2. List all SObjects supported by each Queue
SELECT Id, QueueId, Queue.DeveloperName, Queue.Name, SobjectType
FROM QueueSobject
WHERE SobjectType = 'Case'
ORDER BY Queue.Name ASC

-- 3. Inspect direct members (Users or nested Groups) of a Queue
SELECT Id, GroupId, Group.DeveloperName, UserOrGroupId
FROM GroupMember
WHERE Group.Type = 'Queue'
  AND Group.DeveloperName = 'Tier_3_Engineering_Queue'

Frequently asked questions

How are Queues represented in the Salesforce database when querying via SOQL?

Queues are stored in the standard Group object with Type = 'Queue'. Supported object associations are stored in the QueueSobject table, and queue members are stored in the GroupMember table.

Why should I avoid hardcoding user usernames inside queueMembers in Git?

Usernames vary across sandboxes and scratch orgs, causing Queue deployments to fail when a user is missing. Best practice is to assign Public Groups or Roles inside queueMembers and manage individual user membership in the target org.

How do I enable a custom object to be owned by a Queue?

Ensure the custom object has a sharingModel of ReadWrite or Private (not ControlledByParent), and add a queueSobject block containing the custom object API name inside the Queue metadata file.

What does queueRoutingConfig do on a Queue?

Setting queueRoutingConfig links the Queue to an Omni-Channel QueueRoutingConfig metadata component, which automatically pushes records assigned to the Queue to available agents based on capacity and priority.

What was introduced for Queue metadata in API version 67.0?

API version 67.0 introduced the doesIncludeBosses boolean field on Queue metadata to explicitly control whether users higher in the Role Hierarchy automatically inherit access through the queue.