Sandbox Post Refresh Automation

Sandbox Post-Refresh Automation

When a sandbox is refreshed (full, partial, dev, dev-pro), the metadata + data are copied from the source. Users are then locked out for a final preparation step before the sandbox becomes available. The SandboxPostCopy interface is Salesforce's hook into that step: an Apex class you specify in the sandbox refresh configuration runs ONCE, before users can log in.

It's the right place to:

• Mask emails so test sends don't fire to real customers.
• Deactivate users who shouldn't have sandbox access.
• Scrub integration endpoints that point at production systems.
• Disable scheduled jobs that would race with prod (replicator, escalator, etc.).
• Repopulate test data that doesn't survive the copy (or shouldn't — auth tokens, caches, etc.).
• Reapply environment-specific config (named credentials, Custom Setting values keyed to environment, feature flags).

Without it, every refresh is a manual cleanup checklist that inevitably gets forgotten on one of the steps. The most common forgotten-step disaster: prod-pointing integration endpoints stay configured; a developer in the sandbox triggers the integration; production data changes.

What this skill is NOT. The strategic question of how many sandboxes / which tier / refresh cadence lives in devops/sandbox-strategy-designer. Generic Apex scheduling is apex/scheduled-apex. This skill is specifically about the post-refresh hook and what it should do.

Before Starting

• Confirm the sandbox tier matters. All tiers support SandboxPostCopy. Some org features (e.g. partial-data sandbox data sampling) interact with the post-copy step.
• Decide which actions are non-negotiable. Email masking is always non-negotiable. Endpoint scrub is non-negotiable for orgs with prod-pointing integrations. Scheduled-job disable is non-negotiable if any scheduled job mutates external state.
• Document the runbook explicitly. The post-copy class IS the runbook; it's executable documentation. Future you reads it.
• Plan idempotency. The class runs once per refresh; failure during the run can leave the sandbox half-prepared. Build the class to be safe to re-run if needed.

Core Concepts

The SandboxPostCopy interface

global class MySandboxPrep implements SandboxPostCopy {
    global void runApexClass(SandboxContext context) {
        // Runs once, after sandbox refresh, before users log in.
        maskEmails();
        deactivateProdOnlyUsers();
        scrubIntegrationEndpoints();
        disableScheduledJobs();
        repopulateSampleData();
        applyEnvironmentConfig();
    }
}

Three things to know:

1. global is required. Internal public won't satisfy the interface contract.
2. SandboxContext exposes sandboxName(), sandboxId(), and organizationId(). Use these for environment-aware logic ("if dev sandbox, do X; if full sandbox, do Y").
3. Configured at refresh time. Setup → Sandboxes → click the sandbox → Apex Class field. Specify the class name. Saved with the sandbox; persists across refreshes.

What runs vs what doesn't get copied

The metadata + data copy doesn't include:

• Login Hours / Login IP Ranges on profiles (security intentional).
• Outbound message workflow targets (always reset to a "do not deliver" placeholder by Salesforce — but verify in your org).
• Scheduled jobs — they DO copy, which is usually the wrong outcome. Sandbox post-copy disables them.
• Single-sign-on certificates for some IdP integrations.

What DOES copy and is dangerous in sandbox:

• Named Credentials — point at prod by default unless the named credential was already environment-aware.
• Connected App configurations — OAuth callback URLs are prod-shaped.
• Custom Setting values — usually carry prod values; rewrite in post-copy.
• Workflow + Apex outbound emails — if email deliverability is "All emails", the sandbox can fire emails to real customers unless masked.

Email masking patterns

Hardest constraint. A refreshed sandbox with no email mask + deliverability = "All emails" + a developer running a test = real customers receive sandbox-generated emails.

Mitigation A: Org-wide deliverability "System emails only". Setup → Email → Deliverability → Access Level → System emails only. Done at the org level; survives across refreshes if set on the sandbox post-copy. Belt-and-suspenders with email masking.

Mitigation B: Mask user emails.

private static void maskEmails() {
    List<User> toUpdate = new List<User>();
    for (User u : [SELECT Id, Email FROM User WHERE Email != NULL AND IsActive = TRUE]) {
        // Replace @ with .invalid + a tag — emails won't deliver, but
        // can be reverse-engineered for debugging.
        u.Email = u.Email.replace('@', '+sandbox@') + '.invalid';
        toUpdate.add(u);
    }
    update toUpdate;
}

The .invalid TLD is reserved by IETF for non-routable use — mail servers reject delivery. The +sandbox@ tag preserves the original local-part for forensic debugging.

Disabling scheduled jobs

private static void disableScheduledJobs() {
    for (CronTrigger ct : [
        SELECT Id FROM CronTrigger
        WHERE State IN ('WAITING', 'ACQUIRED', 'EXECUTING')
    ]) {
        try {
            System.abortJob(ct.Id);
        } catch (Exception ex) {
            // Some jobs can't be aborted (in-flight); log and continue.
        }
    }
}

Aborts every scheduled / queued job. A safer variant only aborts jobs whose name matches a documented list of "production-only" jobs; over-aggressive abort can break sandbox tests.

Scrubbing integration endpoints

Named Credentials, Custom Settings, Custom Metadata Types — all copy from production with prod values. Post-copy, rewrite to sandbox / mock endpoints:

private static void scrubIntegrationEndpoints() {
    // Named Credentials are not directly Apex-mutable for endpoint URL;
    // typically scrubbed via metadata deploy in the sandbox setup script.
    // Custom Setting / Custom Metadata are mutable.
    Integration_Config__c cfg = Integration_Config__c.getOrgDefaults();
    cfg.Endpoint__c = 'https://mock.example-sandbox.com/api';
    cfg.API_Key__c = 'SANDBOX-MOCK-KEY';
    update cfg;
}

For Named Credentials, the sandbox-prep team usually pre-deploys sandbox-pointing Named Credential metadata as part of the post-copy + a metadata deploy step.

Decision Guidance

Recommended Workflow

1. Inventory the manual post-refresh checklist. Email masking, user deactivation, endpoint scrub, scheduled-job disable, sample data, env config.
2. Build the SandboxPostCopy class — one private method per checklist item.
3. Make every method idempotent. Re-running shouldn't break anything.
4. Configure on every sandbox. Setup → Sandboxes → Apex Class field.
5. Test by refreshing a low-tier sandbox first. Verify each method ran (audit log, masked emails, disabled jobs).
6. Document the class in source control. It's runbook-as-code.
7. Keep Sandbox org-wide deliverability at "System emails only" as a belt-and-suspenders default.

Review Checklist

• Class implements SandboxPostCopy with global access.
• runApexClass covers email masking, user deactivation, endpoint scrub, scheduled-job disable, sample data, env config.
• Every step is idempotent (safe to re-run).
• SandboxContext is consulted when behavior should differ per environment.
• Class name is configured in Setup → Sandboxes for every sandbox.
• Org-wide deliverability is "System emails only" as a default.
• Failed-run procedure is documented (how to re-run).

Salesforce-Specific Gotchas

1. SandboxPostCopy requires global access modifier. public doesn't satisfy the interface contract. (See references/gotchas.md § 1.)
2. runApexClass runs ONCE per refresh. Mid-execution failure leaves the sandbox half-prepared; design for re-runnability. (See references/gotchas.md § 2.)
3. Scheduled jobs DO copy from prod to sandbox; they fire in the sandbox unless explicitly aborted in post-copy. (See references/gotchas.md § 3.)
4. Named Credential URLs are not Apex-mutable. Pre-deploy sandbox-pointing NC metadata or accept a stale URL. (See references/gotchas.md § 4.)
5. Email deliverability resets to "System emails only" on Salesforce's side after refresh — but verify; not all orgs / tiers behave identically. (See references/gotchas.md § 5.)
6. SandboxContext.sandboxName() is the developer-given name, not a hash; rely on it cautiously for branching. (See references/gotchas.md § 6.)
7. The post-copy class must be already deployed in production before refresh; the sandbox copies the class FROM production. (See references/gotchas.md § 7.)

Output Artifacts

Related Skills

• devops/sandbox-strategy-designer — strategic decision (how many sandboxes, what tiers, refresh cadence). This skill is the implementation half.
• apex/scheduled-apex — generic scheduled / batch Apex; sandbox-post-copy is a specific runtime.
• admin/email-templates-and-alerts — email infrastructure; post-copy interacts with deliverability config.
• apex/apex-mocking-and-stubs — for the test class that exercises the post-copy methods.