# 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 **Settings › Search and Substitute**.
3. Click **Create Rule**.
Each rule has a **label** plus one or more **parameters**.
***
### Rule Parameters Explained
| # | 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}`
Click **Save** to store the rule. It appears in the list with **Edit**, **Delete**, and **Clone** icons.\
***
## 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).
### Commit to Version Control
During **Commit** or **Submit for Validation**, pick your rule under **Search and Substitute**.\
### CI Job
When creating a **CI Job**, expand the **Deploy** section and choose the rule
***
## 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.
