ServiceSetupAssistantSettings in SFDX

Architectural Overview#

ServiceSetupAssistantSettings manages the state of Salesforce’s Service Setup Assistant, an administrative onboarding wizard designed to rapidly configure core Service Cloud capabilities in fresh orgs. When toggled on, the Assistant automatically generates essential service plumbing, including baseline support queues, case record types, Omni-Channel routing definitions, default lightning service console apps, and email-to-case routing addresses.

In modern DevOps and enterprise governance architectures, understanding and tracking ServiceSetupAssistantSettings is essential. While the wizard accelerates initial proof-of-concept setups in developer edition orgs or trial environments, enterprise development teams often prefer to keep it disabled in CI/CD scratch orgs to prevent unwanted automatic creation of unmanaged metadata artifacts that could conflict with deterministic source code.

Directory and File Conventions#

In SFDX source format, ServiceSetupAssistantSettings is stored in the settings directory under the filename ServiceSetupAssistant.settings-meta.xml.

Key Metadata Fields#

The ServiceSetupAssistantSettings schema contains primary toggles controlling the setup assistant lifecycle:

Declarative XML and Package Manifest Examples#

Below is the declarative XML configuration setting the assistant state:

<?xml version="1.0" encoding="UTF-8"?>
<ServiceSetupAssistantSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableServiceSetupAssistant>false</enableServiceSetupAssistant>
</ServiceSetupAssistantSettings>

Manifest Definition (package.xml)#

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

Retrieval and Deployment#

To retrieve or deploy ServiceSetupAssistantSettings via the CLI:

# Retrieve Service Setup Assistant settings
sf project retrieve start --metadata "Settings:ServiceSetupAssistant"

# Deploy settings to target org
sf project deploy start --metadata "Settings:ServiceSetupAssistant"

Senior Architect Deployment Best Practices and Gotchas#

1. Enterprise CI/CD Recommendation: Keep enableServiceSetupAssistant set to false in production and staging repositories. Allowing wizard-generated metadata can lead to naming collisions with enterprise queue definitions and permission sets.
2. Irreversible Metadata Creation: Disabling enableServiceSetupAssistant after it was previously enabled does not automatically delete the queues, apps, or records that the wizard created. Cleaning up those artifacts requires explicit destructive changes.
3. Scratch Org Consistency: If developers rely on the assistant in scratch orgs, document the exact post-provisioning steps so that the resulting configuration matches the metadata stored in version control.
4. Integration Impact: The assistant may create default routing addresses that could intercept inbound test emails intended for dedicated sandbox email services.

Frequently asked questions

What is the purpose of ServiceSetupAssistantSettings?

It enables the guided Service Setup Assistant, provisioning out-of-the-box queues, layouts, email routing, and sample service data.

Where is ServiceSetupAssistantSettings stored in SFDX?

In force-app/main/default/settings/ServiceSetupAssistant.settings-meta.xml under the Settings:ServiceSetupAssistant type.

Should ServiceSetupAssistant be enabled in enterprise CI/CD orgs?

Typically no; enterprise pipelines manage queues and settings deterministically through metadata rather than wizard automation.

Can ServiceSetupAssistant changes be reversed automatically?

No, artifacts created by the assistant like sample queues and record types must be manually cleaned up or destroyed.