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 when you commit and deploy files from one sandbox to another sandbox, one sandbox to Version Control, or vice-versa.
Procedure
Log in to your ARM account.
Hover your mouse over the
Admin
module and click on theSearch and Substitute
option.
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.
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.
Last updated