Sandboxes and promoting changes

A sandbox is an isolated copy of your xMatix tenant — its own sign-in address, its own database — where you change configuration and test against production-like data without touching production. Changes you want to keep are bundled as a DeltaPack inside the sandbox and applied to production as a separate, reviewed step. This page is the administrator's manual for the whole round trip: copy profiles, creating a sandbox, letting colleagues in, refreshing and deleting it, and building, applying, checking and undoing DeltaPacks.

Overview

Everything lives under Setup → Platform → Sandboxes & DeltaPacks, which has five screens:

Inside a sandbox, the first three screens are hidden — a sandbox cannot create sandboxes of its own — while both DeltaPack screens stay available.

When to use it

• Building or changing configuration you do not want users to see half-finished: entities and fields, layouts, business rules, approval processes, scripts, reports, security.
• Rehearsing an upgrade, an import or a new integration against realistic data.
• Training or user acceptance testing on a copy that cannot damage live records.

For a one-field change that is safe to make live, a sandbox is usually more process than you need — see Customizing xMatix.

How xMatix handles it

• Creation and refresh are background jobs. Each runs through the phases Queued → Resolve placement → Provision tenant → Export metadata → Export scripts & components → Export layouts & reports → Apply seed pack → Copy data → Recompute indices → Publish status, and the sandbox detail page follows the job live.
• Metadata is mirrored with the same identifiers as production, which is what lets a DeltaPack built in the sandbox land on the right records in production.
• Users arrive switched off. Every copied user account is inactive except the administrator who created (or refreshed) the sandbox, who is enabled with the System Admin profile and the platform-administration licence.
• Integrations arrive switched off. Integration credentials are never copied. Every integration app, trigger, connection and sync profile lands inactive, the app's sandbox opt-in is off, and integration work that was queued or running in production arrives Cancelled — so a sandbox cannot call your live external systems by accident.
• Email is held back. Where the sandbox email allow list is in force, a sandbox emails only the platform's always-allowed support addresses plus the recipients its administrator allows (see Step 4).
• A data copy either arrives complete or the job fails. The streaming copies (Master data and Copy everything) check every table's row count against production afterwards, and any missing or mismatched table fails the job rather than reporting success.
• Promotion is metadata only. A DeltaPack carries configuration, never business records, and does nothing until someone applies it on the target tenant.

Prerequisites

• The sandboxes feature (and, for promotion, the DeltaPacks feature) enabled for your organization by the platform operator. When it is off, the screens say Sandboxes are not enabled for this tenant or DeltaPacks are not available for this tenant, and the menu entries are hidden.
• The right capabilities on your security profile — see Permissions.
• A sandbox quota with a free slot. Your subscription's plan sets how many sandboxes you may have, how many refreshes each may have per day, and whether data may be copied at all.
• For a governed data copy: at least one approved copy profile (Step 1).

Procedure

Step 1 — Prepare copy profiles (optional, production)

Skip this step if you will create a Metadata only, Master data or Copy everything sandbox — those options do not use copy profiles.

1. Go to Setup → Platform → Sandboxes & DeltaPacks → Sandbox Copy Profiles and create a profile in the New sandbox copy profile dialog: Label, Name (unique key), Entity, Default Top N (default 1,000) and Dependency scope (default Parents required). Select Save.
2. Open the profile. In Filter & order, select Edit to set a Predicate (SQL WHERE fragment) that limits the rows (for example only active records, or only the last six months) and an Order by (SQL fragment) that decides which rows count as the "top N". Select Save.
3. In Sensitive field handling, select Edit and list fields to treat specially as a JSON object of field name to Mask, Null or Copy — for example {"Email":"Mask","Phone":"Mask"}. Suggest from entity fields adds every field of the entity already marked as masked, set to Mask. Fields you do not list are copied as they are. Select Save.
4. Select Approve in the page header. The Approval value changes from Draft to Approved, and only now can a sandbox use the profile. Revoke approval takes it back.
5. To reuse several profiles together, create a set under Sandbox Copy Profile Sets and add the profiles to it.

Step 2 — Create the sandbox (production)

Go to Setup → Platform → Sandboxes & DeltaPacks → Sandboxes. The list shows Ordinal (s1, s2…), Status, Server, Database, Plan, Created, Last refreshed and Subscription key, with search, filter and refresh in the table header. Select New sandbox in the page header.

1. Read the counter Using X of Y sandboxes. If the quota is used up, the dialog shows the reason instead and Create is disabled.
2. Optionally enter a Display name (optional) of up to 80 characters that states the purpose, such as Q3 2026 pricing test.
3. Choose What to copy:

The four data options are disabled, with the warning Data copy is disabled for this tenant by quota policy., when your plan does not allow data copy. Master data and Copy everything copy values as they stand in production — copy-profile masking applies only to the last two options — so choose a profile set or picked entities whenever personal data must be masked.

1. Leave Allow schema drift unticked unless you have been told to tick it (see Common problems).
2. Select Create. A Sandbox queued message appears, the dialog closes and the sandbox's detail page opens.

Step 3 — Follow the job to Active

The detail page, *Sandbox sn, shows Status, Ordinal, Plan, Server, Database, a copyable Subscription key, Created and Last refreshed, and a Provisioning job card with the phase steps, Job ID, Phase, Progress, Started and Finished. It refreshes itself every few seconds. During a Master data or Copy everything copy a Data copy card counts tables complete and rows landed, and afterwards a Verification table lists each table's Source rows, Sandbox rows and match or mismatch*. A Log tail shows the latest job messages.

Expect minutes for a metadata-only sandbox and longer in proportion to the data you chose. Do not create a second sandbox because the first looks slow — that takes another quota slot. The sandbox is ready when Status reads Active; ProvisioningFailed or Failed means it is not usable, and the job message says why.

Step 4 — Sign in and let colleagues in (sandbox)

The sandbox has its own sign-in address, separate from production; your platform operator can confirm it. Sign in with the same identity you use for production. In the mobile app, choose the Sandbox environment on the sign-in screen.

Everyone except you arrives inactive. To let colleagues in, inside the sandbox:

1. Go to Setup → Access Control → Users, tick the people who need access and select *Activate (n)* in the page header.
2. In the dialog, keep Email the sign-in invite ticked to send invites, or untick it and hand out passwords yourself with Set password on each user's page. Optionally give a Security profile (for users who have none) and Add to teams. Select Activate.
3. The dialog lists anyone whose invite will be held back because their address is not on the sandbox's email allow list. To allow them, select Sandbox email in the Users page header (shown only in a sandbox with the allow list in force). Under Who this sandbox emails, keep Only allowed recipients (recommended) and add addresses or whole domains (@example.com) in Also allow, separated by commas — then use Resend invite on the user's page. Everyone — live email for user acceptance testing delivers every email the sandbox produces, including notifications to people copied from production; use it only when that is intended.

Before you test any integration in the sandbox, enter sandbox credentials for it, point it at a test endpoint, switch on its sandbox opt-in and reactivate it — see Credentials and rotation.

Step 5 — Build a DeltaPack with your changes (sandbox)

1. Go to Sandboxes & DeltaPacks → DeltaPacks and select New DeltaPack. Enter Name (required), Description and the Target tenant — the parent production tenant by default, or a sibling sandbox — and select Create.
2. On the pack's page, select Add items and pick, by kind or from the metadata tree, every configuration object to promote: entities and fields, views, relations, layouts, server actions, record types, validations, approval processes, business rules, security rules, archive rules, automation scripts, custom components, reports, dashboards, global picklists, apps, security profiles, roles and teams, messaging templates, localization resources, AI agents and models, data models, datasets, settings, module enablement and copy profiles. Remove takes an item out while the pack is a draft.
3. Select Build. The pack moves from Draft to Ready and shows Built by, Built, Payload size and Payload hash. View payload shows exactly what will be applied.
4. To change a Ready pack, select Rebase to Draft — the item list is kept, the built payload is discarded — then rebuild. An Applied, Undone or Failed pack can be copied with Clone as new draft. Only Draft packs can be deleted.

Step 6 — Review and apply on production

1. On the target tenant, go to Sandboxes & DeltaPacks → Inbound DeltaPacks. Every non-draft pack aimed at this tenant is listed with its status, item count, drift, and who built and applied it.
2. Open the pack and review its items and payload. A physical-changes banner flags field changes that alter the database schema as Breaking (red) or warnings.
3. Select Apply to this tenant and confirm. The status moves to Applying and then Applied, or Failed with the error, where Retry apply re-queues it. Applying writes configuration; it does not run business rules or scripts against your records.
4. After applying, select Check drift to compare production with what the pack applied. The result reads clean or Drift detected (n modified, m deleted) with a Drift details table.
5. If the change has to come out, select Undo (shown while a before-image from the apply exists). The confirmation warns when drift has been found, because undo replays the pre-apply state and overwrites later edits to the same records. A successful undo sets the status to Undone.

Step 7 — Refresh the sandbox when it falls behind (production)

A sandbox shows production as it was when it was created or last refreshed; it does not sync. To bring it up to date, select Refresh Sandbox on its row or detail page (available only while Active) and confirm Refresh this sandbox from source?.

• Build a DeltaPack first for any change worth keeping. A refresh mirrors production's configuration over the sandbox's and reloads the data in the copy plan, so do not count on anything authored only in the sandbox surviving.
• The refresh reuses the copy option the sandbox was created with: a metadata-only sandbox stays metadata-only, a data sandbox re-copies its data, and a master-data sandbox re-copies its custom-entity list.
• People who are active in the sandbox keep their access — their sign-in, profiles, roles, teams and licences. A grant to a profile, role or team that existed only in the sandbox is dropped. Inactive accounts are replaced from production, still inactive, and the administrator who ran the refresh is enabled as on create.
• The address, ordinal and subscription key do not change. Status reads Refreshing while the job runs and returns to Active; Last refreshed updates on success.

Step 8 — Delete a sandbox you no longer need (production)

Select Delete on its row or detail page and confirm Delete this sandbox?. The sandbox goes offline at once and its quota slot is released immediately, so you can create a replacement straight away. It is kept for a 7-day retention window — during which support can still reverse a mistaken delete — and then archived and permanently removed, after which it leaves the list. Ordinals are not reused. Any DeltaPack still unbuilt or unapplied in that sandbox is lost with it.

Fields

New sandbox dialog

Sandbox copy profile

Business rules

• Quota. Creation is refused when sandboxes are not enabled for the subscription (Sandboxes are not enabled for this subscription.) or the cap is reached (Sandbox limit reached (n/m).). Deleted sandboxes waiting for purge do not count against the cap.
• Refresh limits. A refresh needs the sandbox to be Active and is refused when refresh is not enabled (Sandbox refresh is not enabled for this subscription.) or the day's allowance is used (Daily refresh quota reached (n/m).).
• Copy plans. Copy profiles must be approved; an entity can appear only once per plan; a Top N override can only lower a profile's cap; a profile set must be non-empty and fully approved; custom entities can be named only for a master-data copy.
• Schema gate. If the sandbox platform lacks tables or columns that this tenant uses or holds data in, the job stops with a schema-drift error unless Allow schema drift was ticked.
• Complete-or-fail data copy. After a Master data or Copy everything copy, any table that failed or whose row count differs from production fails the job.
• Failed refresh. A refresh that fails returns the sandbox to Active rather than leaving it stuck; Last refreshed keeps its previous value, the data may be partly refreshed, and running the refresh again brings it into line.
• Users. On create, every copied account is inactive and not signed up, except the creator, who is enabled with System Admin. On refresh, accounts active in the sandbox are kept as they are.
• Integrations. Credentials never cross into a sandbox; integration apps, triggers, connections and sync profiles arrive inactive; queued or running integration work arrives Cancelled.
• DeltaPacks. Lifecycle: Draft → Ready (Build) → Applying → Applied (or Failed) → Undone (Undo). Ready can go back to Draft with Rebase. Only Draft packs can be deleted. Undo needs the before-image captured at apply.

Example

A distribution company wants to add a Delivery window field to orders and a rule that requires it for one order type, without disturbing live order entry.

1. The administrator creates sandbox s2 with Display name Delivery window change and What to copy set to Master data, adding the custom entity Route_Calendar_c. The job reaches Active after a few minutes, and the Verification table shows every table as match.
2. Signed in to the sandbox, they open Setup → Access Control → Users, tick two order-desk supervisors and select Activate (2). The dialog warns that both invites will be held back, so they open Sandbox email, add @example.com under Also allow, save, and use Resend invite.
3. They add the field to the Order entity and layout, write the validation rule, and the supervisors test it against copied customers and products.
4. They create DeltaPack Order delivery window, add the field, the layout and the validation rule, and select Build. View payload shows the three items.
5. On production, under Inbound DeltaPacks, they open the pack, read the physical-changes banner (one new column, no breaking changes) and select Apply to this tenant. It reaches Applied; Check drift reports clean.
6. A week later they refresh s2 for the next project. The two supervisors keep their sandbox access.

Training

Practice exercise

In a training tenant with sandboxes enabled:

1. Create a Metadata only sandbox named Training — your name.
2. When it is Active, sign in to it, add a text field Training note to any custom entity and place it on that entity's layout.
3. Build a DeltaPack targeting the production tenant containing the field and the layout. Confirm it reads Ready and that View payload lists both items.
4. Do not apply it. Back on production, open Inbound DeltaPacks and find your pack.
5. Delete the sandbox.

Expected result: the pack is visible as an inbound pack on production with two items; the field does not exist in production; the sandbox has left the active count in the New sandbox counter.

Quick reference

• Menu: Setup → Platform → Sandboxes & DeltaPacks.
• Smallest copy that proves the change: Metadata only for configuration work.
• Masking only applies to profile-set and picked-entity copies — profiles must be Approved.
• Active is the only usable status; refresh needs Active too.
• Colleagues: *Users → Activate (n), and allow their address under Sandbox email*.
• Integrations land off with no credentials — re-supply them in the sandbox.
• Build a DeltaPack before refreshing or deleting.
• Promote: Build in the sandbox → Apply to this tenant on production → Check drift; Undo if needed.
• Delete frees the quota slot at once; the sandbox is purged after 7 days.

Permissions

A user without a capability does not see the matching screen in Setup. Activating users and changing Sandbox email inside a sandbox use the normal user-administration rights — see User accounts. Separating setup.deltapacks.manage (authors, in the sandbox) from setup.deltapacks.inbound.manage (approvers, on production) gives you a two-person promotion step; see Security profiles.

Configuration

• Feature switches and quota — whether sandboxes and DeltaPacks are enabled, the number of sandboxes, refreshes per day and whether data may be copied are set for your subscription by the platform operator, not in Setup. The New sandbox counter and its warnings tell you where you stand.
• Copy profiles and sets — Setup → Platform → Sandboxes & DeltaPacks → Sandbox Copy Profiles / Sandbox Copy Profile Sets. Approving a profile is the governance step for what data may leave production; revoking it stops new sandboxes from using it. Profiles and sets can themselves be promoted in a DeltaPack.
• Masked fields — fields marked as masked on the entity are what Suggest from entity fields picks up; mark sensitive fields once and every new profile can reuse the list.
• Sandbox email — inside a sandbox, Setup → Access Control → Users → Sandbox email decides who receives the sandbox's emails (allow list or live).
• Integrations in a sandbox — re-enter credentials and switch on the integration app's sandbox opt-in in the sandbox itself; see Integrations.

Common problems

Colleagues cannot sign in to the sandbox

Copied accounts are inactive by design. Activate them in the sandbox (Step 4). If they never received an invite, their address is not on the sandbox's email allow list: add it under Sandbox email and use Resend invite, or set a password for them yourself.

New sandbox is disabled, or creation fails with a quota message

The plan's sandbox cap is reached or sandboxes are not enabled for the subscription. Delete a sandbox you no longer need — its slot is freed immediately — or ask the platform operator about the quota.

The data options are greyed out

Data copy is disabled for this tenant by quota policy. Your plan allows metadata-only sandboxes. Ask the platform operator if you need data.

A copy profile is not offered

Only Approved profiles appear. Open it under Sandbox Copy Profiles and select Approve. A profile set with any unapproved profile in it is refused as a whole.

The job failed with a schema drift error

The sandbox platform is on an older release than production and lacks tables or columns your tenant uses; the message names them. Either wait for the sandbox platform to catch up (ask the platform operator), or create the sandbox again with Allow schema drift ticked and accept that those columns' values will be missing in the sandbox.

The job failed saying the data copy was incomplete

One or more tables failed to copy or their row counts do not match production; the Verification table and the message name them. The sandbox holds the rest but is not complete. Select Refresh Sandbox to run the copy again.

Refresh Sandbox is greyed out

Refresh needs Active. Wait for a running job to finish. If a refresh failed, the sandbox is back to Active and you can try again; if the daily allowance is used, try tomorrow.

My sandbox-only work vanished after a refresh

A refresh mirrors production's configuration over the sandbox. Only what was built into a DeltaPack and applied elsewhere survives. Build packs before refreshing.

An integration does nothing in the sandbox

It arrived inactive with no credentials and with its sandbox opt-in off. Re-supply credentials, point it at a test endpoint and re-enable it in the sandbox.

A DeltaPack sits in Applying

The apply job has stalled. Contact your platform operator rather than applying again.

Common questions

Can a sandbox affect production?

No. A sandbox is a separate tenant with its own database and sign-in address; nothing you configure, break or delete in it touches production. Integrations arrive switched off without credentials, so it cannot call your live systems either. The only way back is a DeltaPack, which does nothing until someone with setup.deltapacks.inbound.manage applies it on production — and an applied pack can be undone while its before-image exists.

What exactly does a DeltaPack carry?

Configuration only — the kinds listed in Step 5, chosen item by item. Records you create in a sandbox stay there. If a test data set needs to travel, move it with export and import.

Which copy option should I choose?

The smallest one that proves your change. Metadata only for configuration and layout work. Master data when you need real customers, products and pricing but no transactions. A copy profile set or picked entities when you need some transactions and must mask personal data. Copy everything only when you need a full replica and accept that values are copied unmasked and a large tenant takes hours.

Are sensitive values copied into the sandbox?

With a profile set or picked entities, only as each approved profile allows: each listed field is copied, masked with a consistent stand-in, or blanked. Master data and Copy everything copy values as they are in production, apart from integration credentials, which are never copied. Approving profiles, and choosing the copy option, is the governance step for what leaves production.

How current is a sandbox's data?

As of its creation or last refresh, shown in Last refreshed. Sandboxes do not sync continuously. Refresh when you need production's current state.

Related topics

• Customizing xMatix — the changes you will typically build in a sandbox.
• User accounts — activating users and setting passwords.
• Security profiles — granting the sandbox and DeltaPack capabilities.
• Credentials and rotation — re-supplying integration secrets in a sandbox.
• Import data
• Export data
• Administration guide