OmniChannelSettings Metadata Type Guide

Architectural Overview#

OmniChannelSettings is an org-level settings metadata type that acts as the primary ignition switch for Salesforce Service Cloud Omni-Channel routing infrastructure. It activates the real-time presence engine, push-based routing models, Skills-Based Routing, and Omni-Channel Supervisor consoles.

In customer service and contact center architecture, deploying OmniChannelSettings is an absolute prerequisite before creating Routing Configurations, Presence User Configs, Service Channels, or Omni-Channel Flows. Without this setting active, dependent metadata types cannot be compiled or deployed.

Directory and File Conventions#

OmniChannelSettings is managed as a singleton settings file under settings/.

Key Metadata Fields#

The XML schema defines core contact center routing engines:

Declarative XML and Package Manifest Examples#

A comprehensive production configuration enabling skills routing and supervisor oversight:

<?xml version="1.0" encoding="UTF-8"?>
<OmniChannelSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableOmniChannel>true</enableOmniChannel>
    <enableOmniSecondaryRoutingPriority>true</enableOmniSecondaryRoutingPriority>
    <enableOmniSkillsRouting>true</enableOmniSkillsRouting>
    <enableOmniSupervisor>true</enableOmniSupervisor>
    <enableStatusBasedWorkContinuation>true</enableStatusBasedWorkContinuation>
</OmniChannelSettings>

Scratch Org Configuration (config/project-scratch-def.json)#

{
  "orgName": "Omni-Channel Contact Center Scratch Org",
  "edition": "Enterprise",
  "features": ["ServiceCloud", "OmniChannel"],
  "settings": {
    "omniChannelSettings": {
      "enableOmniChannel": true,
      "enableOmniSkillsRouting": true,
      "enableOmniSupervisor": true,
      "enableOmniSecondaryRoutingPriority": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage OmniChannelSettings using the Salesforce CLI:

# Retrieve OmniChannel settings from the environment
sf project retrieve start --metadata Settings:OmniChannel

# Deploy OmniChannel settings to the target org
sf project deploy start --metadata Settings:OmniChannel

Architect Best Practices and Gotchas#

• CI/CD Pipeline Sequence: Always deploy Settings:OmniChannel in an initial foundational deployment step before deploying ServiceChannel, QueueRoutingConfig, PresenceDeclineReason, or PresenceUserConfig. Deploying these without Omni-Channel enabled causes immediate failure.
• Capacity Model Choices: When configuring Omni-Channel, evaluate whether your workloads benefit from Status-Based Capacity (work consumed until record status changes) vs. Tab-Based Capacity (work consumed only while the agent has the console tab open).
• Secondary Routing Priority Rules: If enableOmniSecondaryRoutingPriority is enabled, ensure your routing configurations specify a secondary priority model, or incoming work will default to first-in-first-out timestamp sorting.

Frequently asked questions

What core capabilities are unlocked by OmniChannelSettings?

It enables Omni-Channel presence, queue-based and skills-based work routing, secondary priorities, and Omni-Channel Supervisor consoles.

How is OmniChannelSettings referenced in an SFDX package manifest?

It is retrieved under the Settings metadata type using OmniChannel as the member name.

Can skills-based routing be enabled via OmniChannelSettings?

Yes. Setting enableOmniSkillsRouting to true activates skills routing engines across standard and custom work items.