How to Deploy Custom Settings Records in Salesforce

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.

Table of Contents

1. What are Custom Settings?2. Why Custom Settings Records Are Not Deployable by Default3. How to Deploy Custom Settings Records4. Best Practices for Deploying Custom Settings5. Real-World ScenariosConclusion:

1. What are Custom Settings?

Custom settings are similar to custom objects but with streamlined access and optimised 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.

Please clean up and modify the record values for the target environment.

Ensure field mappings are correct.

3. Import Records

Use the 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 the 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

Here are a few things to consider 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 thisName 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.

✅ Scenario 1: Feature Flag for a New Functionality

Use a list custom setting with fields like Feature_Name__c ‘and’. Deploy data using an 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 the 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.

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.