CallCenterRoutingMap Metadata Type in SFDX

Architectural Overview#

In Service Cloud Voice (both with Amazon Connect and Partner Telephony), routing decisions span two systems: Salesforce Omni-Channel (which evaluates CRM data, Omni-Channel Flows, Queues, and Skills) and the cloud telephony engine (which controls physical media streams and agent voice states). The CallCenterRoutingMap metadata type is the synchronization bridge between these two worlds.

Each CallCenterRoutingMap record binds a specific callCenter (CallCenter), an internal Salesforce entity (referenceRecord pointing to a Queue, Skill, or User), and the externalId (for example, an Amazon Connect Queue ARN or Agent ARN). When an Omni-Channel Voice Call Flow routes a VoiceCall to a Salesforce Queue, Service Cloud Voice looks up the CallCenterRoutingMap to translate that Queue into the target Amazon Connect Queue ARN.

SFDX Directory & File Suffix#

Key Metadata Fields#

The CallCenterRoutingMap metadata type exposes the following XML elements:

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<CallCenterRoutingMap xmlns="http://soap.sforce.com/2006/04/metadata">
    <callCenter>ACME_US_Voice_Center</callCenter>
    <externalId>arn:aws:connect:us-east-1:111122223333:instance/a1b2c3d4-5678-90ab-cdef-111111111111/queue/f9e8d7c6-5432-10fe-dcba-222222222222</externalId>
    <masterLabel>Tier 1 Billing Voice Map</masterLabel>
    <quickConnect>arn:aws:connect:us-east-1:111122223333:instance/a1b2c3d4-5678-90ab-cdef-111111111111/transfer-destination/99998888-7777-6666-5555-444444444444</quickConnect>
    <referenceRecord>Tier_1_Billing_Voice_Queue</referenceRecord>
</CallCenterRoutingMap>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Tier_1_Billing_Voice_Map</members>
        <name>CallCenterRoutingMap</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL & SFDX CLI#

Audit existing contact center routing mappings in any org using standard SOQL:

SELECT Id, DeveloperName, MasterLabel, CallCenter.InternalName,
       ReferenceRecordId, ExternalId, QuickConnect
FROM CallCenterRoutingMap
ORDER BY CallCenter.InternalName, MasterLabel ASC

Retrieve and deploy CallCenterRoutingMap components with the Salesforce CLI:

# Retrieve all CallCenterRoutingMap records
sf project retrieve start --metadata CallCenterRoutingMap

# Deploy a specific CallCenterRoutingMap
sf project deploy start --metadata CallCenterRoutingMap:Tier_1_Billing_Voice_Map

Senior Architect Best Practices & Gotchas#

• Deploy Queue and Skill Dependencies First: The referenceRecord field must resolve to an existing Queue, Skill, or User in the target org. Always include your voice Queue (queues/*.queue-meta.xml) and Skill metadata in the deployment manifest alongside CallCenterRoutingMap.
• Separate User Mappings from Queue/Skill Mappings in Git: While Queue and Skill CallCenterRoutingMap files belong in source control, User-level CallCenterRoutingMap records (mapping individual agent User records to Amazon Connect agent ARNs) are dynamically generated when users are added to the Contact Center. Avoid committing hundreds of user-specific routing maps to Git; only version-control Queue and Skill routing maps.
• Missing Mapping Fallback Behavior: If an Omni-Channel Flow routes a VoiceCall to a Salesforce Queue that lacks a CallCenterRoutingMap for the active CallCenter, the call transfer or routing action fails at runtime in Amazon Connect and drops back to the default fallback queue.

Frequently asked questions

What is the role of CallCenterRoutingMap in Service Cloud Voice?

It links a Salesforce routing entity—such as an Omni-Channel Queue, Skill, or User—to its external telephony routing identifier, like an Amazon Connect queue or routing profile ARN.

Where are CallCenterRoutingMap files stored in SFDX source format?

They are stored in the force-app/main/default/callCenterRoutingMaps/ directory with the .callCenterRoutingMap-meta.xml file extension.

Why do CallCenterRoutingMap deployments often require environment variables?

The externalId field stores telephony provider identifiers such as AWS Account and Connect Instance ARNs, which differ between sandbox and production telephony instances.

Can I query CallCenterRoutingMap records in SOQL?

Yes, CallCenterRoutingMap is queryable via SOQL and Tooling API to verify mappings between ReferenceRecordId, CallCenterId, and ExternalId.