slackGitHub

String Replacements

sfp-pro
sfp (community)

Availability

✅

❌

From

September 2025

String replacements provide a mechanism to manage environment-specific values in your Salesforce code without modifying source files. This feature automatically replaces placeholders with appropriate values during build, install, and push operations, and converts values back to placeholders during pull operations.

String replacements complement the existing aliasfy packages feature. While aliasfy packages handle structural metadata differences by deploying different files per environment, string replacements handle configuration value differences within the same files, reducing duplication and maintenance overhead.

How It Works

String replacements work across multiple sfp commands:

Build Operations: During sfp build, replacement configurations are analyzed and embedded in the artifact for later use during installation.

Install/Deploy Operations: During sfp install or sfp deploy, placeholders are replaced with environment-specific values based on the target org:

Artifact (%%API_URL%%) → Install → Target Org (https://api.example.com)

Push Operations: During sfp push, placeholders in your source files are replaced with environment-specific values before deployment:

Source File (%%API_URL%%) → Push → Target Org (https://api.example.com)

Pull Operations: During sfp pull, environment-specific values are converted back to placeholders:

Target Org (https://api.example.com) → Pull → Source File (%%API_URL%%)

Configuration

Replacements are configured in a replacements.yml file within each package's preDeploy directory:

src/
  your-package/
    preDeploy/
      replacements.yml
    main/
      default/
        classes/

Example configuration:

replacements:
  - name: "API Endpoint"
    pattern: "%%API_ENDPOINT%%"
    glob: "**/*.cls"
    environments:
      default: "https://api-sandbox.example.com"
      dev: "https://api-dev.example.com"
      staging: "https://api-staging.example.com"
      prod: "https://api.example.com"

  - name: "Support Email"
    pattern: "%%SUPPORT_EMAIL%%"
    glob: "**/*.cls"
    environments:
      default: "[email protected]"
      dev: "[email protected]"
      prod: "[email protected]"

The properties accepted by the configuration file are:

Field
Required
Description

name

Yes

Human-readable name for the replacement

pattern

Yes

The placeholder pattern to replace (e.g., %%API_URL%%)

glob

Yes

File pattern for matching files (e.g., **/*.cls for all Apex classes)

environments

Yes

Map of environment aliases to replacement values

environments.default

No

Default value used for sandbox/scratch orgs (recommended)

isRegex

No

Whether the pattern is a regular expression (default: false)

Example Usage

API Configuration Example

Source file with placeholders:

public class APIService {
    private static final String ENDPOINT = '%%API_ENDPOINT%%';
    private static final String API_KEY = '%%API_KEY%%';
}

After pushing to a dev org, the placeholders are replaced:

public class APIService {
    private static final String ENDPOINT = 'https://api-dev.example.com';
    private static final String API_KEY = 'dev-key-12345';
}

Pattern Detection

During pull operations, sfp automatically detects potential patterns that could be converted to replacements:

  • URLs: Detects HTTP/HTTPS URLs

  • Email Addresses: Identifies email patterns

  • API Keys: Recognizes common API key formats

  • Custom Patterns: Detects repetitive values across files

When patterns are detected, sfp provides suggestions:

⚠️  Potential replacements detected:

  📄 src/package/main/default/classes/APIService.cls:
     • URL detected: 'https://new-api.example.com/v2'
       New URL pattern detected. Consider adding to replacements.yml

  💡 To include these values in future replacements, update your replacements.yml file.

Environment Resolution

Replacements are resolved based on the target org:

  • Exact Alias Match: First checks for an exact match with the org alias

  • Sandbox Default: For sandbox/scratch orgs, uses the default value

  • Production Requirement: Production deployments require explicit configuration

Org Alias Mapping

The org alias is determined from your Salesforce CLI authentication:

# Check your org aliases
sf org list

# Push with specific org alias
sfp push -o dev-sandbox -p your-package

Command Support

String replacements are supported across the following sfp commands:

Command
Support
Description

sfp build

✅

Analyzes and embeds replacement configurations in artifacts

sfp install

✅

Applies replacements during artifact installation

sfp deploy

✅

Applies replacements during artifact deployment

sfp push

✅

Applies forward replacements during source push

sfp pull

✅

Applies reverse replacements during source pull

sfp validate

✅

Applies replacements during validation

Command Line Options

Disable Replacements

# Skip replacements during install
sfp install --targetorg dev --artifactdir artifacts --no-replacements

# Skip replacements during push
sfp push -p your-package -o dev --no-replacements

# Skip replacements during pull
sfp pull -p your-package -o dev --no-replacements

Override Replacements

# Use override file during install
sfp install --targetorg dev --artifactdir artifacts --replacementsoverride custom-replacements.yml

# Use override file during push
sfp push -p your-package -o dev --replacementsoverride custom-replacements.yml

# Use override file during pull
sfp pull -p your-package -o dev --replacementsoverride custom-replacements.yml

JSON Output

Both push and pull commands support JSON output with detailed replacement information:

# Get JSON output with replacement details
sfp push -p your-package -o dev --json
sfp pull -p your-package -o dev --json

JSON Output Structure

{
  "hasError": false,
  "replacements": {
    "success": true,
    "packageName": "your-package",
    "filesModified": [
      {
        "path": "main/default/classes/APIService.cls",
        "replacements": [
          {
            "pattern": "%%API_ENDPOINT%%",
            "value": "https://api-dev.example.com",
            "count": 1
          }
        ],
        "totalCount": 1
      }
    ],
    "totalFiles": 1,
    "totalReplacements": 1,
    "errors": [],
    "orgAlias": "dev"
  }
}

Troubleshooting

Replacements Not Applied

  • Check File Location: Ensure replacements.yml is in preDeploy directory

  • Verify Glob Pattern: Test glob pattern matches your files

  • Check Org Alias: Verify the org alias matches your configuration

  • Review Logs: Check debug logs for replacement processing

Pattern Not Found

  • Case Sensitivity: Patterns are case-sensitive

  • Special Characters: Escape special regex characters if needed

  • File Encoding: Ensure files are UTF-8 encoded

Wrong Value Applied

  • Org Detection: Verify org alias with sf org list

  • Environment Priority: Check resolution order (exact match → default)

  • Override Files: Check if override file is being used

Limitations

  • Replacements are text-based and work with any text file format

  • Binary files are not supported

  • Large files may impact performance

  • Regex patterns should be used carefully to avoid unintended matches

Related Documentation

Last updated