How to Deploy Custom Settings Records in Salesforce

Custom settings in Salesforce are an integral part of the platform that allows developers and administrators to store custom data that can be accessed efficiently without needing SOQL queries. They’re incredibly useful for application configuration, feature toggles, and environment-specific data.

However, one major hurdle Salesforce professionals often face is deploying custom settings records across environments from sandbox to production or between developer orgs. Unlike custom metadata types, custom settings data isn’t deployable using traditional metadata deployment tools like change sets or Salesforce DX by default.

1. What are Custom Settings?

Custom Settings are similar to Custom Objects, but with streamlined access and optimized storage for configuration-type data. They allow you to avoid hardcoding values and provide easier maintainability.

Types of Custom Settings

There are two types:

1. List Custom Settings

• Shared across all users
• Ideal for application-wide settings

2. Hierarchy Custom Settings

• Can have different values per user or profile
• Great for user-specific preferences

Example Use Cases:

• API endpoint configurations
• Feature flags
• Limit thresholds
• Integration keys

2. Why Custom Settings Records Are Not Deployable by Default

Unlike custom metadata types, custom settings data is treated as actual data, not metadata. That means…

• It doesn’t move with Change Sets or Metadata API.
• Salesforce assumes that custom setting records are environment-specific.
• You must deploy them manually or via script.

3. How to Deploy Custom Settings Records

Let’s explore the various ways to move Custom Settings data between orgs.

Method 1: Use Data Loader/Data Import Wizard

Step-by-step:

1. Export Records

• Go to the Custom Setting in your source org.
• Use Data Loader to export records from the Custom Setting object (API name ends with c)

2. Prepare the CSV.

• Clean up and modify record values for the target environment.
• Ensure field mappings are correct.

3. Import Records

• Use Data Loader in your target org to insert records.
• Choose the correct Custom Setting object (e.g., MyCustomSetting__c)

✅ Pros:

• Simple and straightforward
• No development required

❌ Cons:

• Manual process
• No automation or version control

Method 2: Use Apex Scripts

For repeated or automated deployments, Apex scripts can be used to insert or update custom settings.

List<MyCustomSetting__c> settings = new List<MyCustomSetting__c>{ new MyCustomSetting__c(Name = 'Setting1', API_Key__c = 'ABC123'), new MyCustomSetting__c(Name = 'Setting2', API_Key__c = 'XYZ789') }; insert settings;

How to deploy:

• Execute from Anonymous Apex in Developer Console
• Or create an Apex Class and run it post-deployment.

✅ Pros:

• Easy automation
• Can be checked into version control
• Can be bundled with deployment scripts

❌ Cons:

• Requires developer access
• Not ideal for non-technical users

Method 3: Custom Metadata Alternative

If your use case involves configuration data that needs to be deployed via Change Sets or Metadata API, consider switching to Custom Metadata Types.

✅ Pros:

• Fully deployable
• Can be included in source control
• Environment-agnostic if used with custom labels or hierarchy logic

❌ Cons:

• Limited data volume
• Not suitable for user-specific settings (use Hierarchy Custom Settings instead)

Method 4: Use Salesforce DX + SFDX Data Commands

If you are using Salesforce DX, you can include custom setting data in scratch orgs or use data import commands.

sfdx force:data:tree:export -q "SELECT Name, Field1__c FROM MyCustomSetting__c" -d ./data -p sfdx force:data:tree:import -f ./data/MyCustomSetting__c.json

✅ Pros:

• Scripted
• Version-controlled
• Repeatable

❌ Cons:

• Requires setup of SFDX and CLI
• More complex than manual tools

Method 5: Use Third-Party Tools

Tools like Gearset, Copado, Flosum, or AutoRABIT provide GUI-based solutions to move custom settings data.

✅ Pros:

• User-friendly
• Often includes backup/versioning
• Easy to use for non-developers

❌ Cons:

• Requires licenses
• Can become expensive

4. Best Practices for Deploying Custom Settings

Here are a few things to keep in mind when working with custom settings across environments:

1. Use Custom Metadata When Possible

If your data doesn’t need to change per org or user, custom metadata types are a better alternative. They are metadata and can be deployed easily.

2. Use Naming Conventions

When inserting records via script or import, ensure names are consistent. Some systems rely on it Name as a unique identifier.

3. Avoid Hardcoded IDs

Don’t hardcode record IDs in your logic—always refer to Name or create a Key__c field.

4. Document Settings

Keep a README or Confluence page that explains the purpose of each custom setting and how to update it.

5. Secure Sensitive Data

Do not store secrets or credentials in plain text. Use Named Credentials or Shield Platform Encryption if needed.

5. Real-World Scenarios

✅ Scenario 1: Feature Flag for a New Functionality

Use a list custom setting with fields like Feature_Name__c and Is_Enabled__c. Deploy data using Apex script after moving the Custom Setting metadata.

✅ Scenario 2: Org-Specific Configurations

Use Data Loader to export/import org-specific API keys or URLs for integrations, using different values in sandbox and production.

✅ Scenario 3: Migrating from Sandbox to Production

• Export via Data Loader
• Use version-controlled CSVs or Apex classes.
• Create a post-deployment script for production.

Conclusion:

Deploying Custom Settings records in Salesforce may seem tricky at first, but with the right approach and tools, you can streamline the process significantly. Whether you prefer a script-based strategy using Apex or a more user-friendly route with tools like Data Loader or Gearset, the key is consistency and planning. Whenever possible, opt for Custom Metadata Types for metadata-bound values, and reserve Custom Settings for data that is environment-specific or frequently changing.