Salesforce CLI Custom Settings Deployment: A Step-by-Step Guide

Deploying custom settings in Salesforce can be done using various methods, but one common approach is to use Salesforce CLI. Here's a step-by-step guide:

To ensure a practical illustration, this article will leverage the FSRK_ProductDiscountSettings__c custom setting taken from a previous piece as an example. In essence, this custom setting aids in determining the discount percentage for individual products and comprises just two fields - ProductType__c, defining the product type, and DiscountPercentage__c, reflecting the discount amount. In a nutshell, these two fields constitute a crucial component of our tutorial example, showcasing the deployment process using Salesforce CLI in a real-world context.

Retrieve Custom Setting Object

Use Salesforce CLI to retrieve the source metadata, including custom settings, from your source Salesforce org.

sf project retrieve start -m CustomObject:FSRK_ProductDiscountSettings__c

After executing this CLI command, along with the metadata of the FSRK_ProductDiscountSettings__c object, the two fields, ProductType__c and DiscountPercentage__c, will also be retrieved. However, if you need to retrieve them separately, you can use the following command.

Retrieve Fields Metadata

sf project retrieve start -m CustomField:FSRK_ProductDiscountSettings__c.DiscountPercentage__c, CustomField:FSRK_ProductDiscountSettings__c.ProductType__c

If you've done everything correctly, the following files should appear in your project:

force-app/
        └── main/
            └── default/
                └── objects/
                    └── FSRK_ProductDiscountSettings__c/
                        ├── fields/
                        │   ├── DiscountPercentage__c.field-meta.xml
                        │   └── ProductType__c.field-meta.xml
                        └── FSRK_ProductDiscountSettings__c.object-meta.xml

Commit Changes to Git

git add .
git commit -m "Added FSRK_ProductDiscountSettings__c and its fields metadata"

Deploy to QA Environment

sf project deploy start -m CustomObject:FSRK_ProductDiscountSettings__c -o<qaOrgAlias>

Note: use sf alias list to view a list of all connected orgs.

If you've done everything correctly, the following lines should appear:

sf project deploy start -m CustomObject:FSRK_ProductDiscountSettings__c -o <qaOrgAlias>
Deploying v58.0 metadata to <name@org.com> using the v59.0 SOAP API.
Deploy ID: 0AfIS0000001K9A0AU
Status: Succeeded | ████████████████████████████████████████ | 3/3 Components (Errors:0) | 0/0 Tests (Errors:0)

Rollback Strategy

In case of issues, initiate a rollback by canceling the deployment. Canceling a deployment is only possible if it has not been completed; otherwise "Can't cancel deploy because it's already completed" will be received.

sf project deploy cancel -i <deploymentId> -o <qaOrgAlias>

By performing the actions listed above, we deployed only the metadata, excluding the records of custom settings. Now, let's explore options for deploying the records of custom metadata.

Why are Custom Setting records not deployable?

Custom-setting records are not deployable because they are considered as runtime data specific to each Salesforce organization or environment. Unlike metadata, which defines the structure of objects, fields, and settings, custom setting records contain data that is expected to differ between environments.

To manage this, Salesforce has separated metadata (structure) and data, with the expectation that administrators will manually configure records in each environment.

So, what options do we have to migrate custom settings from one org to another?

Manual Post-Deployment Steps to Create Records

By manually creating records, you can tailor the data to each environment's specific requirements without the risk of unintentional overwrites during deployment.

Apex Script to Insert FSRK_ProductDiscountSettings__c Records

Here's an example of an Apex script that inserts a couple of FSRK_ProductDiscountSettings__c records with populated fields:

List discountSettingsList = new List();

// Record 1
FSRK_ProductDiscountSettings__c record1 = new FSRK_ProductDiscountSettings__c();
record1.DiscountPercentage__c = 10;
record1.ProductType__c = 'Electronics';
discountSettingsList.add(record1);

// Record 2
FSRK_ProductDiscountSettings__c record2 = new FSRK_ProductDiscountSettings__c();
record2.DiscountPercentage__c = 15;
record2.ProductType__c = 'Clothing';
discountSettingsList.add(record2);

// Insert Records
insert discountSettingsList;

This script creates two records with different discount percentages and product types. You can execute this script using the Developer Console or execute anonymous Apex in Salesforce.

Note: Ensure that the script is executed in an appropriate context, like a sandbox or development environment, and adjust the field values according to your specific use case.

Best Practices

Version Control

Always use version control (Git) to track changes.

Testing

Perform thorough testing in a sandbox or development environment before deploying to production.

Documentation

Keep documentation updated with changes made to metadata.

Validation in QA

Validate deployments in a QA environment to catch issues early.

Deployment Monitoring

Monitor deployment status regularly using CLI commands.

Collaboration

Collaborate with the team and stakeholders to ensure everyone is aware of the changes.

Conclusion

By following these steps and best practices, you can streamline the deployment process of custom settings and fields, ensuring a smooth and controlled transition between environments. Adjust the commands and aliases based on your project structure and Salesforce environment.

SalesForce Simplified