Search and Substitute

This article is for Org Administrators in particular. The actions discussed in the article are not available to general users.

Overview

The Search and Substitute rules feature allows you to define custom find and substitute rules that ARM applies whene you commit and deploy files from one sandbox to another sandbox, one sandbox to Version Control, or vice-versa.

Procedure

1. Log in to your ARM account.

2. Hover your mouse over the Admin module and click on the Search and Substitute option.

   
3. Click on Create Rule. A rule consists of a rule label and several rule parameters.

   

Rule Parameters

1. Metadata Type

Until now, Search and Substitute could only be used to select a metadata type and then perform the search for substrings across all members in that type. Now, however, you can choose specific metadata members in a type and substitute values for the member(s).

Use Cases:

• If you have a custom label in one of your orgs with identical values across multiple labels, but you only want to change one of those values, then having the ability to search for a specific label and apply substitution rules will help.

• Suppose you need to add a few object permissions, but only to the Production environment and not the lower sandboxes. In that case, you can now do so instead of manually commenting out some metadata in the Permission Set file during sandbox deployments and then uncommenting them before a Production deployment.

• The rules can be created and used in CI Jobs to make the replacements automatically, depending on the deployment settings in the CI Job.

Supported Metadata TypesBelow is an updated list of all the metadata types compatible with the enhanced Search and Substitute functionality.

• AutoResponseRule

• CustomLabel

• CustomMetadata

• CustomObject

• CustomSite

• Dashboard

• DashboardFolderShare

• Network

• NamedCredential

• PermissionSet

• Portal

• Queue

• RemoteSiteSettings

• Report

• ReportFolderShare

• SamlSsoConfig

• SharingCriteriaRule

• SharingOwnerRule

• Workflow

2. Sub Element

The element for which you want to substitute the character.

3. Criteria

The text you want to replace.

4. Substitute

The value that will replace the text.

To substitute multiple values, click on the '+' icon to add more field parameters. Note that you can only add up to 5 parameters for a rule; anything beyond that, the application won’t allow you. Also, ensure the parameters are not duplicated, which may fail in search and substitute functionality.

Example:

The 'Formatchange' rule will be applied to the 'CustomObject' metadata type in the following example. The sub-element is 'Fields.displayFormat', and the value to be replaced is 'a-{000}'. The value to replace this with is 'a-{001}'.

Once you're done creating the rule, click on the Save button.

The rule will be displayed on the Search and Substitute home screen with an option to edit, delete, or create a new rule to add to the existing rules using the clone icon.

What's Next?

You have successfully created a new rule. The next step is to specify the newly created rule whenever you perform a CI, deployment, or commit operation in ARM.

Deploying the changes to a Sandbox with a new rule assigned

While deploying the changes from one sandbox to another sandbox, you can apply the Search and Substitute rule on the Deployment Settings screen.

From the Apply Search and Substitute Rules list, select the rule that will be associated with the current deployment process. Use the / button to add or remove the rule and use the / button to move the rules list up and down. Based on the selection, the top rule is deployed initially, and the process continues for the remaining rules.

Committing the changes from one Salesforce org to a Version Control branch with new rules assigned

While committing the metadata component changes to a Version Control Branch, you can apply the Search and Substitute rule on the Commit or Submit for Validation screen. Refer to the Commit topic for the detailed commit process.

Performing CI Job with new rule assigned

While committing the metadata component changes from a Salesforce org to a Version Control branch using CI job, you can apply the Search and Substitute rule in the Create CI Job screen under the Deploy section.