Deploying changes with change sets

A change set carries setup you built in a sandbox to your production organization. You build it in the sandbox, upload it, and an admin validates and deploys it in production. Only setup moves: a deploy never changes production’s records.

How it works

1. 1BuildIn the sandbox, add what you changed to a change set.
2. 2UploadThe change set is frozen and sent to production.
3. 3ValidateIn production, a trial run shows what would change and any problems.
4. 4DeployEverything is applied together, or nothing is. It can be rolled back.

Building, validating, deploying and rolling back need the Deploy changes permission (the Admin profile has it). Both sides are in Settings → Change Sets: in a sandbox it shows the change sets you’re building, in production the ones uploaded from your sandboxes.

What can be deployed

Anything an item needs is added only if production doesn’t have it yet. An item that was copied from production into the sandbox is matched to the same item in production even if you renamed it.

Build a change set (in the sandbox)

1. Sign in to the sandbox at sandbox.crmsix.com and go to Settings → Change Sets.
2. Choose New change set, give it a name that says what it delivers (for example “Billing fields and layout”) and, if useful, a description.
3. Choose Add items, pick a type (Custom field, Page layout, Report, Dashboard, …), tick the items and choose Add. Repeat for each type.
4. Check the list. Items added because others need them are marked Added because other items need it. Each item shows what it would do in production: New in production, Changes production (with the settings that differ) or Same as production. Remove anything you don’t want to deploy.
5. Choose Upload to production.

Validate (in production)

In production, go to Settings → Change Sets and open the change set. Validate runs the whole deploy and then undoes it, so nothing in production changes. It shows:

• What would happen to each item: created, updated (with what changes) or no change.
• Problems that would stop the deploy: for example a validation-rule or formula-field formula that uses a field production doesn’t have, or a name production already uses for something else.
• Things to check after deploying: for example a rule that assigns to a user or support team that exists only in the sandbox, or a flow that still needs finishing.

Validate as often as you like; the latest result stays on the page.

Deploy

1. Validate first and fix any problems in the sandbox (then upload a new change set).
2. Choose Deploy and confirm.
3. Everything is applied in one go. If any item fails, nothing is changed and the problems are listed, so production is never left half-updated.
4. When it succeeds, each item shows Created, Updated or No change.

The deploy is recorded in the Admin Activity Log, and the field history of changed items shows the change set’s name. People working in production see the changes straight away.

When an item already exists in production, production keeps:

• its counters and statistics (how often a rule or flow has run);
• webhook secrets;
• which version of a flow is active;
• the owner of a report or dashboard.

Flows

A flow arrives as a new, inactive version; the version production is running isn’t touched. A new flow arrives inactive too. When you’re ready, open it in Settings → Flows in production, check the new version (Debug runs it without saving anything) and activate it. Problems in a flow are shown as things to check rather than stopping the deploy, because activating checks the flow again.

Reports and dashboards

• Adding a dashboard also adds the saved reports its components show, if production doesn’t have them. Standard reports are in every organization and don’t need moving.
• Adding a report also adds the custom fields it shows or filters by, if production doesn’t have them.
• A report is matched by its type (object) and name, a dashboard by its name.
• Ownership: an existing report or dashboard keeps its production owner. A new one keeps its sandbox owner if that person is a user in production; otherwise it belongs to whoever deploys the change set.
• Only their settings move: in production they show production’s records, filtered by each viewer’s access as usual.

Roll back a deploy

If a deploy isn’t what you wanted, open the change set and choose Roll back. What the deploy created is deleted and what it changed goes back to how it was before, in one go. A rolled-back change set can be deployed again later.

• A flow version the deploy added can’t be rolled back once it has been activated. Activate the previous version first, then roll back.
• Records aren’t deleted or changed, but a custom field the deploy created is removed, so anything entered in it since is no longer shown.

Good practice

• Refresh before you build. Start from a recently refreshed sandbox, so it matches production.
• Small change sets. One change set per piece of work is easier to validate and to roll back.
• Validate, then deploy at a quiet time. Changes apply immediately for everyone.
• Check the things to check. After deploying, fix any references to users or support teams that exist only in the sandbox.

Troubleshooting

“Production already has one with that name”

Production has a different item with the same name or API name. Rename one of them, then upload a new change set.

A problem starting “Formula:”

A validation rule or formula field doesn’t work with production’s fields, usually because it uses a field production doesn’t have. Add that field to the change set (adding the rule again adds the custom fields it needs), then upload a new change set.

“It refers to something production doesn’t have”

An item points at a record that exists only in the sandbox. Add that item to the change set, or change the reference.

I can’t see Settings → Change Sets

Your profile needs the Deploy changes permission.

The change set doesn’t appear in production

It hasn’t been uploaded yet: in the sandbox, open it and choose Upload to production.