Home / admin / sandbox-post-refresh-automation

sandbox-post-refresh-automation

Automating post-sandbox-refresh cleanup via the `SandboxPostCopy` interface — the Apex class that runs ONCE after a sandbox refresh or clone completes, before users can log in.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• Security
• Operational Excellence

• sandbox
• sandboxpostcopy
• refresh-automation
• email-masking
• integration-endpoint-scrub

Open the skill folder on GitHub

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 admin/sandbox-strategy. Generic Apex scheduling is apex/apex-scheduled-jobs. 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.

Questions to Ask Before Configuring

Ask these before writing a line of the post-copy class. Each one maps to a documented platform behaviour that will otherwise surface as a silent half-run, and an LLM that skips them produces a class that passes its tests and fails the refresh.

What a proper configuration adds over just writing the class: the refresh produces a sandbox where the scheduled-job count is provably zero, no active user holds a routable address, and every step that could not be automated has a named owner in a checklist a script can verify.

Core Concepts

The SandboxPostCopy interface

global class MySandboxPrep implements SandboxPostCopy {

    // Required. The copy process instantiates the class with this.
    global MySandboxPrep() {}

    global void runApexClass(SandboxContext context) {
        // Runs once, after sandbox refresh, before users log in.
        // Guard each step separately — see point 3.
        maskEmails();
        deactivateProdOnlyUsers();
        scrubIntegrationEndpoints();   // before the abort, not after
        disableScheduledJobs();
        repopulateSampleData();
        applyEnvironmentConfig();
    }
}

The full, deployable version — with per-step try/catch, the idempotent mask predicate and the six-state abort query — is in references/metadata-examples.md § 1.

Four things to know:

1. A no-arg constructor is mandatory. The guide's own sample carries the comment: "Implementations

   of SandboxPostCopy must have a no-arg constructor. This constructor is used during the sandbox copy process" (Apex Reference Guide L228955–228956). Constructors with arguments are allowed but "won't be used by the sandbox copy process" (L228958–228960) — a class whose only constructor takes arguments cannot be instantiated by the copy.

2. Write both the class and runApexClass global. Every Salesforce sample does (L228952, L228975).

   UNVERIFIED (2026-09-05): the guide never states that a public implementation is rejected, and its member-signature line reads public void runApexClass(System.SandboxContext context) (L228926) — see references/gotchas.md § 1 for why this skill still recommends global.

3. It runs as a restricted Automated Process user. "This user doesn't have access to all object and

   features; therefore, the Apex script cannot access all objects and features. If the script fails, run the script after sandbox activation as a user with appropriate permissions" (L228889–228891). This is the single most common cause of a post-copy that works in test and fails in the refresh.

4. SandboxContext exposes organizationId(), sandboxId(), sandboxName() (L228933–228935). Use

   these for environment-aware logic, but keep the safety steps outside the branch.

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. UNVERIFIED (2026-09-05): the copy behaviour is Help-documented only; the abort mechanism below is fully grounded. See references/gotchas.md § 3.

• Single-sign-on certificates for some IdP integrations.

What the copy rewrites for you, and what it leaves alone:

• Username is mutated automatically. "In a sandbox named test, the username user@acme.com

  becomes user@acme.com.test" (Metadata API Developer Guide L2711–2713).

• Email is not. It arrives verbatim, routable, pointing at a real person. That asymmetry is the

  whole reason the masking step below exists — see references/gotchas.md § 11.

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 restriction. Setup → Email → Deliverability → Access Level. Set at the org level, by hand. UNVERIFIED (2026-09-05): this control has no EmailAdministrationSettings field — that type's complete list is 19 booleans, none an access-level enum (api_meta L114872–114994) — so it cannot be deployed and cannot be set from the post-copy class. Track it as a manual step with a named owner; see references/metadata-examples.md § 6 for what is deployable, and § 7 for the checklist shape that stops a manual step masquerading as an automated one.

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 +sandbox@ tag preserves the original local-part for forensic debugging, and the NOT Email LIKE '%.invalid' predicate (see references/examples.md Example 2) makes the step idempotent. UNVERIFIED (2026-09-05): the claim that .invalid is IETF-reserved for non-routable use is general internet knowledge, not sourced in any Salesforce guide checked for this skill. Nothing in the platform enforces it — a mail server that chooses to route .invalid will. Masking is a strong control, not a guarantee; pair it with mitigation A.

Disabling scheduled jobs

private static void disableScheduledJobs() {
    for (CronTrigger ct : [
        SELECT Id FROM CronTrigger
        WHERE State IN ('WAITING', 'ACQUIRED', 'EXECUTING',
                        'PAUSED', 'BLOCKED', 'PAUSED_BLOCKED')
    ]) {
        try {
            System.abortJob(ct.Id);
        } catch (Exception ex) {
            System.debug(LoggingLevel.ERROR, 'abortJob failed: ' + ex.getMessage());
        }
    }
}

Six states, not three. CronTrigger.State has nine documented values; only COMPLETE, ERROR and DELETED are terminal (Object Reference L86799–86811). A three-state filter leaves BLOCKED and PAUSED_BLOCKED jobs alive, and PAUSED returns to WAITING by itself once a release window closes. Full table in references/metadata-examples.md § 4.

abortJob is not a kill. "The specified job is stopped, but any code that is in progress will continue to execute until it completes" (Apex Reference Guide L238662–238663). Scrub endpoints before aborting so an in-flight run lands on mocks. And it needs the CronTrigger Id: "You can't abort a scheduled Apex job using an AsyncApexJob ID" (L238678–238680). CronTrigger itself takes no DML — supported calls are describeSObjects(), query(), retrieve() only (L86722).

A safer variant aborts only 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 what is still live, from the source org. Run the CronTrigger query in

   references/metadata-examples.md § 4 — all six live states, with CronJobDetail.JobType so you can see the Scheduled Flows an Apex-only sweep would miss. Answer the seven questions above against that list. Fill templates/sandbox-post-refresh-automation-template.md.

2. Write config/sandbox/post-refresh-checklist.json first, from references/metadata-examples.md

   § 7. Every step gets an owner (apex / pipeline / manual) and a verify query. The steps you mark manual — the deliverability Access Level among them — are the ones this skill cannot automate, and naming them now is the point of doing this before the Apex.

3. Build the class and its test from references/metadata-examples.md § 1 and § 2. No-arg

   constructor, per-step try/catch, idempotent mask predicate, six-state abort, scrub before abort. The test uses the 5-arg Test.testSandboxPostCopyScript(..., true) overload and asserts on state queried back, not on a return value.

4. Run the checker — it reads the checklist JSON, the Apex, and the settings file together:

   python3 scripts/check_sandbox_post_refresh_automation.py --manifest-dir force-app/main/default. Fix every finding before you deploy; each maps to a numbered gotcha.

5. Validate then deploy to PRODUCTION with RunSpecifiedTests on the post-copy test class

   (references/metadata-examples.md § 8). The sandbox copies Apex from the source org, so a class that only ever lived in a sandbox is gone after the next refresh.

6. Bind the class to each sandbox (references/metadata-examples.md § 3), then refresh the

   lowest-tier sandbox first and run the three verification queries from § 8 — zero live CronTrigger rows, zero unmasked active users, IsSandbox = true.

7. Work the manual rows of the checklist, deploy EmailAdministration.settings to the activated

   sandbox, and record which steps needed the post-activation re-run. Those are your Automated Process user access gaps; move them permanently into the pipeline half.

Review Checklist

• [ ] Class implements SandboxPostCopy with global access and a no-arg constructor.
• [ ] runApexClass covers email masking, user deactivation, endpoint scrub, scheduled-job disable, sample data, env config — each in its own try/catch.
• [ ] Endpoint scrub runs before the job abort.
• [ ] The abort query covers all six live CronTrigger states, not three.
• [ ] Every step is idempotent (safe to re-run).
• [ ] The test class uses the 5-arg testSandboxPostCopyScript with RunAsAutoProcUser = true.
• [ ] SandboxContext is consulted when behavior should differ per environment, and the safety steps sit outside the branch.
• [ ] Class is deployed to production and bound to every sandbox.
• [ ] Checklist JSON exists, every step has an owner and a verify, and the checker passes.
• [ ] Deliverability Access Level is recorded as a manual step with a named owner.
• [ ] Failed-run procedure is documented (how to re-run after activation, as a permissioned user).

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.)
8. The script runs as a restricted Automated Process user that isn't visible in the org and can't reach every object or feature. (See references/gotchas.md § 10.)
9. The copy rewrites Username automatically; Email it leaves routable. Derive masked addresses from Email, never from Username. (See references/gotchas.md § 11.)
10. Implementations need a no-arg constructor — an args-only constructor can't be used by the copy process. (See references/metadata-examples.md § 1.)
11. The 4-arg testSandboxPostCopyScript runs as the test initiator, so it can't reproduce the access failure that most often breaks a real refresh. (See references/gotchas.md § 13.)
12. Three CronTrigger states aren't enough — PAUSED, BLOCKED and PAUSED_BLOCKED are live too. (See references/gotchas.md § 12.)
13. abortJob lets in-flight code finish and needs the CronTrigger Id, not an AsyncApexJob Id. (See references/gotchas.md § 14.)

Output Artifacts

Reference Files

Related Skills

• admin/sandbox-strategy — strategic decision (how many sandboxes, what tiers, refresh cadence). This skill is the implementation half.
• apex/apex-scheduled-jobs — generic scheduled / batch Apex; sandbox-post-copy is a specific runtime, and this is where the jobs you abort come from.
• admin/email-deliverability-strategy — the org-wide deliverability controls this skill can only mark as a manual step.
• 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.
• data/sandbox-refresh-data-strategies — re-seeding reference data after the copy, which this skill deliberately stubs out.
• security/sandbox-data-masking — masking beyond User.Email: the wider set of customer-identifying fields.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/sandbox-post-refresh-automation-template.md
• scripts/check_sandbox_post_refresh_automation.py