Search and Substitute

Audience: Org Administrators only – general users don’t see these controls.

Why Use Search & Substitute?

When you move metadata between environments, small but critical differences can break deployments:

  • Hard-coded URLs that point to Production instead of Sandbox.

  • Object-level permissions that should exist only in lower tiers.

  • Label values that need slight tweaks per org.

Search & Substitute lets you define rules that automatically find and replace text inside selected metadata before the deployment or commit occurs. The rules run when you:

  • Deploy sandbox → sandbox

  • Deploy sandbox → Version Control

  • Commit Version Control → sandbox (CI jobs)

That means fewer manual edits, fewer post-deployment fixes, and more predictable pipelines.

Creating a Rule

  1. Log in to ARM.

  2. Go to Admin › Search and Substitute.

    Admin menu showing the Search and Substitute option

  3. Click Create Rule.

    Create Rule button on the Search and Substitute page

Each rule has a label plus one or more parameters.

Rule Parameters Explained

Rule parameter fields: Metadata Type, Sub Element, Criteria, Substitute
#
Field
Purpose

1

Metadata Type

Choose a metadata type – or an individual member – where the replacement should occur.

2

Sub Element

The XML path / JSON key holding the text you want to change.

3

Criteria

The exact string (or pattern) to search for.

4

Substitute

The replacement value.

Click + to add up to 5 parameter sets per rule. Duplicate rows are not allowed.

Supported Metadata Types

AutoResponseRule, CustomLabel, CustomMetadata, CustomObject, CustomSite, Dashboard, DashboardFolderShare, Network, NamedCredential, PermissionSet, Portal, Queue, RemoteSiteSettings, Report, ReportFolderShare, SamlSsoConfig, SharingCriteriaRule, SharingOwnerRule, Workflow

Tip: Combining Search & Substitute with CI Job deployment settings lets you adjust the same package differently for each target org.

Example

Need to change an invoice number format in one org only? Create a rule like this:

  • Metadata Type: CustomObject › Invoice__c

  • Sub Element: Fields.displayFormat

  • Criteria: a-{000}

  • Substitute: a-{001}

Example rule that changes displayFormat from a-{000} to a-{001} for a CustomObject

Click Save to store the rule. It appears in the list with Edit, Delete, and Clone icons.

Rule list with edit, delete, and clone actions

Using a Rule in Deployments & Commits

Sandbox → Sandbox Deployment

On the Deployment Settings screen:

  1. Open Apply Search and Substitute Rules.

  2. Move rules to Selected with / .

  3. Use the arrows to order execution (top rule runs first).

Deployment Settings with Search and Substitute rules selected

Commit to Version Control

During Commit or Submit for Validation, pick your rule under Search and Substitute.

Commit screen showing Search and Substitute rule selection

CI Job

When creating a CI Job, expand the Deploy section and choose the rule.

CI Job creation with Search and Substitute rule dropdown

Best Practices

  • Granularity first – target specific metadata members when possible to avoid false replacements.

  • Limit to five – ARM enforces a max of 5 parameters; combine similar changes into one rule.

  • Test in Sandbox – run a dry-run deployment to validate your substitutions before Production.

  • Clone, don’t copy-paste – use the Clone icon to reuse rule logic with small tweaks.

With Search & Substitute configured, your deployments self-adjust to each environment—no manual XML edits required.

PreviousWorkspacesNextALM Management

Last updated

Was this helpful?