CaseSettings Metadata Type for Service Cloud

Architectural Overview#

The CaseSettings metadata type is the central configuration backbone for Salesforce Service Cloud. It governs org-wide support processes, including default Case ownership, Email-to-Case (emailToCase), Web-to-Case (webToCase), Case Feed item visibility (caseFeedItemSettings), Case Merge behavior (keepRecordTypeOnAssignmentRule), and automated customer/owner email notifications.

From a release engineering perspective, CaseSettings is one of the most environment-sensitive metadata files in a Salesforce repository. Because it frequently embeds usernames (defaultCaseOwner, defaultCaseUser), queue names, and email templates (closeCaseThroughStatusChange, notifyContactOnCaseComment), architects must carefully parameterize or scrub org-specific references before promoting Case.settings-meta.xml through a CI/CD pipeline.

Directory Location and File Suffix#

In Salesforce DX projects, CaseSettings is stored in the settings directory as Case.settings-meta.xml and referenced via the Settings type in package.xml.

Key Metadata Fields#

The CaseSettings metadata schema contains critical Service Cloud switches and nested configuration blocks:

Declarative Metadata Example#

The following Case.settings-meta.xml file configures a Queue as the defaultCaseOwner (avoiding hard-coded usernames where possible), enables Lightning threading and On-Demand Email-to-Case, and preserves Record Types during assignment rule execution.

<?xml version="1.0" encoding="UTF-8"?>
<CaseSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <caseAssignNotificationTemplate>unfiled$public/SupportCaseAssignmentNotification</caseAssignNotificationTemplate>
    <caseCreateNotificationTemplate>unfiled$public/SupportCaseCreatedPhoneInquiries</caseCreateNotificationTemplate>
    <caseFeedItemSettings>
        <characterLimit>400</characterLimit>
        <displayFormat>Default</displayFormat>
        <feedItemType>EmailMessageEvent</feedItemType>
    </caseFeedItemSettings>
    <closeCaseThroughStatusChange>true</closeCaseThroughStatusChange>
    <defaultCaseOwner>Tier_1_Support_Queue</defaultCaseOwner>
    <defaultCaseOwnerType>Queue</defaultCaseOwnerType>
    <enableCaseFeed>true</enableCaseFeed>
    <enableCollapseEmailThread>true</enableCollapseEmailThread>
    <enableDraftEmails>true</enableDraftEmails>
    <enableEarlyEscalationRuleTriggers>false</enableEarlyEscalationRuleTriggers>
    <enableSuggestedSolutions>false</enableSuggestedSolutions>
    <keepRecordTypeOnAssignmentRule>true</keepRecordTypeOnAssignmentRule>
    <notifyContactOnCaseComment>false</notifyContactOnCaseComment>
    <notifyDefaultCaseOwner>true</notifyDefaultCaseOwner>
    <notifyOwnerOnCaseComment>true</notifyOwnerOnCaseComment>
    <notifyOwnerOnCaseOwnerChange>true</notifyOwnerOnCaseOwnerChange>
    <showEmailAttachmentsInCaseAttachmentsRL>true</showEmailAttachmentsInCaseAttachmentsRL>
    <useSystemEmailAddress>true</useSystemEmailAddress>
    <useSystemUserAsDefaultCaseUser>true</useSystemUserAsDefaultCaseUser>
    <emailToCase>
        <enableE2CAttachmentAsFile>true</enableE2CAttachmentAsFile>
        <enableE2CDeduplicateAttachments>true</enableE2CDeduplicateAttachments>
        <enableE2CExternalServer>false</enableE2CExternalServer>
        <enableEmailToCase>true</enableEmailToCase>
        <enableHtmlEmail>true</enableHtmlEmail>
        <enableM2CModeration>false</enableM2CModeration>
        <enableOnDemandEmailToCase>true</enableOnDemandEmailToCase>
        <enableThreadTokenInBody>true</enableThreadTokenInBody>
        <enableThreadTokenInSubject>true</enableThreadTokenInSubject>
        <overEmailLimitAction>Requeue</overEmailLimitAction>
        <preQuoteSignature>true</preQuoteSignature>
        <unauthorizedSenderAction>Discard</unauthorizedSenderAction>
    </emailToCase>
    <webToCase>
        <caseOrigin>Web</caseOrigin>
        <enableWebToCase>true</enableWebToCase>
    </webToCase>
</CaseSettings>

Package Manifest (package.xml)#

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

SFDX CLI Retrieval and Deployment#

CaseSettings is retrieved and deployed through the Metadata API Settings:Case target:

# Retrieve CaseSettings into force-app/main/default/settings/Case.settings-meta.xml
sf project retrieve start --metadata Settings:Case

# Validate CaseSettings deployment before promoting to production
sf project deploy start --metadata Settings:Case --dry-run

Architect Best Practices and Gotchas#

• Email-to-Case Routing Address Traps: When you retrieve Settings:Case from Production, Salesforce includes every <routingAddresses> block under <emailToCase>. Deploying those routing addresses to a sandbox triggers verification emails or fails if the routing address caseOwner user does not exist in the sandbox. Exclude <routingAddresses> from version control or manage them via environment-specific replacements.
• Lightning Threading vs. Ref ID: In API version 50.0 and later (68.0 in Winter ’27), Ref ID threading (enableThreadIDInBody and enableThreadIDInSubject) is superseded by Lightning threading (enableThreadTokenInBody and enableThreadTokenInSubject). Always enable thread tokens for secure header and token-based email matching.
• Email Template Dependencies: Any email template referenced in caseAssignNotificationTemplate, caseCreateNotificationTemplate, or caseCloseNotificationTemplate must be deployed prior to or alongside CaseSettings.

Frequently asked questions

Why do Email-to-Case routing addresses cause CaseSettings deployments to fail across sandboxes?

EmailToCaseRoutingAddress entries inside CaseSettings often contain org-specific caseOwner users or queues and verified email addresses. If the target user does not exist or email-to-case is not enabled first, deployment fails.

How is CaseSettings named in package.xml?

Like all org-level settings in Salesforce Metadata API, use the Settings metadata type with member name Case in package.xml, which maps to Case.settings-meta.xml in SFDX source format.

What happens if defaultCaseOwner in CaseSettings references an inactive user?

Salesforce rejects the CaseSettings deployment if the username specified in defaultCaseOwner or defaultCaseUser does not exist or is inactive in the target environment.

Can I deploy CaseSettings without overwriting existing Email-to-Case routing addresses?

Yes, omitting the routingAddresses block or individual routing address elements in Case.settings-meta.xml leaves existing routing addresses in the target org untouched.