Salesforce.

com: Winter ’14

Deploy Enhancements from Sandboxes

Last updated: January 4, 2014

© Copyright 2000–2013 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are other
names and marks. Other marks appearing herein may be trademarks of their respective owners.
 Table of Contents

Table of Contents

Deploy Enhancements from Sandboxes.................................................................................................1

Welcome, Salesforce Integrators, Developers and Administrators............................................................................................1
Setup and Manage Your Sandbox.............................................................................................................................................1
Deploy Your Changes.............................................................................................................................................................14

Index.................................................................................................................................................36

i
DEPLOY ENHANCEMENTS FROM
SANDBOXES

Welcome, Salesforce Integrators, Developers and

Administrators
Want to customize your organization in a staging environment where you can test changes without affecting your production
organization or its users? Want to have an organization that users can log into and test new features before they’re
production-ready? Or maybe you just want to log into a Salesforce organization for training or development that mirrors your
production organization.
Salesforce.com offers sandboxes and a set of deployment tools, so you can:

• Isolate customization and development work from your production environment until you’re ready to deploy changes.
• Test changes against copies of your production data and users.
• Provide a training environment.
• Coordinate individual changes into one deployment to production.

Whether you’re an administrator adding features to an organization, a solo developer writing code, or a team of developers
working to enhance your organization, you should work with the right tools in the right environment to build and deploy
change successfully to your production organization. For a broad overview of the development process and recommendations
for organizing your work, see the Development Lifecycle Guide.

See Also:
Sandbox Overview
Deployment Overview
Choose Your Tools for Developing and Deploying Changes

Setup and Manage Your Sandbox

Sandbox Overview
Available in: Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To view a sandbox: “View Setup and Configuration”
To create, refresh, activate, and delete sandbox: “Modify All Data”

Salesforce gives you the ability to create multiple copies of your organization in separate environments for a variety of purposes,
such as testing and training, without compromising the data and applications in your Salesforce production organization.

1
Deploy Enhancements from Sandboxes Sandbox Overview

These copies are called sandboxes and are nearly identical to your Salesforce production organization. For a list of differences,
see Sandbox Setup Tips and Considerations on page 9.
Sandboxes are completely isolated from your Salesforce production organization, so operations you perform in your sandboxes
do not affect your Salesforce production organization, and vice versa.
From Setup, click Sandboxes or Data Management > Sandboxes to view and manage your existing sandboxes or create new
ones. For instructions, see Managing Sandboxes on page 7.
The sandbox types are:
Developer Sandbox
Developer sandboxes are special configuration sandboxes intended for coding and testing by a single developer. Multiple
users can log into a single Developer sandbox, but their primary purpose is to provide an environment in which changes
under active development can be isolated until they’re ready to be shared. Just like Developer Pro sandboxes, Developer
sandboxes copy all application and configuration information to the sandbox. Developer sandboxes are limited to 200
MB of test or sample data, which is enough for many development and testing tasks. You can refresh a Developer sandbox
once per day.

Developer Pro Sandbox

Developer Pro sandboxes copy all of your production organization's reports, dashboards, price books, products, apps,
and customizations under Setup, but exclude all of your organization's standard and custom object records, documents,
and attachments. Creating a Developer Pro sandbox can decrease the time it takes to create or refresh a sandbox from
several hours to just a few minutes, but it can only include up to 1 GB of data. You can refresh a Developer Pro sandbox
once per day.

Partial Data Sandbox

Partial Data sandboxes include all of your organization’s metadata and add a selected amount of your production
organization's data that you define using a sandbox template. A Partial Data sandbox is a Developer sandbox plus the
data you define in a sandbox template. It includes the reports, dashboards, price books, products, apps, and customizations
under Setup (including all of your metadata). Additionally, as defined by your sandbox template, Partial Data sandboxes
can include your organization's standard and custom object records, documents, and attachments up to 5 GB of data
and a maximum of 10,000 records per selected object. A Partial Data sandbox is smaller than a Full sandbox and has a
shorter refresh interval. You can refresh a Partial Data sandbox every 5 days.

Full Sandbox
Full sandboxes copy your entire production organization and all its data, including standard and custom object records,
documents, and attachments. You can refresh a Full sandbox every 29 days.

Sandbox templates allow you to pick specific objects and data to copy to your sandbox, so you can control the size and content
of each sandbox. Sandbox templates are only available for Partial Data or Full sandboxes.

Sandbox Availability
You purchase licenses for each sandbox type, and can purchase multiple licenses of each type. Sandbox licenses are hierarchical.
Specifically, the following table shows the type of sandbox you can create with each license:

Full Sandbox Partial Data Developer Pro Developer

license Sandbox Sandbox license Sandbox license
Allows you to create:
Developer sandbox type

Developer Pro sandbox type

2
Deploy Enhancements from Sandboxes Creating or Refreshing a Sandbox

Full Sandbox Partial Data Developer Pro Developer

license Sandbox Sandbox license Sandbox license
Allows you to create:
Partial Data sandbox type

Full sandbox type

License stages are:

Available
A purchased sandbox license. Salesforce displays the number of “Available” sandboxes. This is your total number of used
and unused sandboxes.

In use
The active, or ready to be activated, sandboxes you created with your license.

Note: If you don’t see a sandbox option or need licenses for more sandboxes, contact salesforce.com to order sandboxes
for your organization.

The status of a Sandbox can be:

Copying
A sandbox in the initial creation stage. When you create (or refresh) a sandbox, Salesforce copies the configuration and
data you specify to the sandbox. A sandbox in the “Copying” stage is not yet ready for use. Copy time depends on the
size of the data, and can take several hours.

Ready for use

Salesforce finished copying data to the sandbox, and you can log into the sandbox or run application tests on the sandbox.

Replacement Ready
When you refresh an existing sandbox, you also need to activate it. The “Replacement Ready” status indicates Salesforce
has a copy of your object data and is ready for you to activate the sandbox so you can use it.

See Also:
Creating or Refreshing a Sandbox
Sandbox Restrictions and Licenses
Development Lifecycle Guide

Creating or Refreshing a Sandbox

Available in: Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To view a sandbox: “View Setup and Configuration”
To create, refresh, activate, and delete sandbox: “Modify All Data”

You have two ways to copy your data to a sandbox.

3
Deploy Enhancements from Sandboxes Creating or Refreshing a Sandbox

1. Create a new sandbox.

When you create a new sandbox, Salesforce automatically copies your data from a production organization to a sandbox
organization. While creating a Partial Data or Full sandbox, you can apply a sandbox template, if you have created one.
Customers create sandbox templates to define specific object data to copy into the Partial Data or Full sandbox.
2. Refresh and activate an existing sandbox.
If you already created a sandbox, you can refresh the sandbox with new object metadata and data from your production
organization. You only refresh or activate an existing sandbox. The first time you create a sandbox, Salesforce activates the
sandbox for you.

To create a new sandbox:

1. From Setup, click Sandboxes or Data Management > Sandboxes.

2. Click New Sandbox.
3. Enter a name and description for the sandbox. You can only change the name when you create or refresh a sandbox.
Tip: We recommend that you choose a name that:

• Reflects the purpose of this sandbox, such as “QA.”

• Has few characters because Salesforce automatically appends the sandbox name to usernames and email
addresses on user records in the sandbox environment. Names with fewer characters make sandbox logins
easier to type.

4. Select the type of sandbox you want.

Developer Sandbox
Developer sandboxes are special configuration sandboxes intended for coding and testing by a single developer.
Multiple users can log into a single Developer sandbox, but their primary purpose is to provide an environment in
which changes under active development can be isolated until they’re ready to be shared. Just like Developer Pro
sandboxes, Developer sandboxes copy all application and configuration information to the sandbox. Developer
sandboxes are limited to 200 MB of test or sample data, which is enough for many development and testing tasks.
You can refresh a Developer sandbox once per day.

Developer Pro Sandbox

Developer Pro sandboxes copy all of your production organization's reports, dashboards, price books, products, apps,
and customizations under Setup, but exclude all of your organization's standard and custom object records, documents,
and attachments. Creating a Developer Pro sandbox can decrease the time it takes to create or refresh a sandbox
from several hours to just a few minutes, but it can only include up to 1 GB of data. You can refresh a Developer Pro
sandbox once per day.

Partial Data Sandbox

Partial Data sandboxes include all of your organization’s metadata and add a selected amount of your production
organization's data that you define using a sandbox template. A Partial Data sandbox is a Developer sandbox plus
the data you define in a sandbox template. It includes the reports, dashboards, price books, products, apps, and
customizations under Setup (including all of your metadata). Additionally, as defined by your sandbox template,
Partial Data sandboxes can include your organization's standard and custom object records, documents, and attachments
up to 5 GB of data and a maximum of 10,000 records per selected object. A Partial Data sandbox is smaller than a
Full sandbox and has a shorter refresh interval. You can refresh a Partial Data sandbox every 5 days.

Note: Partial Data sandboxes require a sandbox template to select the data from your organization. For
more information, see Creating Sandbox Templates on page 6.

4
Deploy Enhancements from Sandboxes Creating or Refreshing a Sandbox

Full Sandbox
Full sandboxes copy your entire production organization and all its data, including standard and custom object records,
documents, and attachments. You can refresh a Full sandbox every 29 days.

Note: If you don’t see a sandbox option or need licenses for more sandboxes, contact salesforce.com to order
sandboxes for your organization.

If you have reduced the number of sandboxes you purchased, but you still have more sandboxes of a specific type than
allowed, you will be required to match your sandboxes to the number of sandboxes that you purchased. For example, if
you have two Full sandboxes but purchased only one, you cannot refresh your Full sandbox as a Full sandbox. Instead, you
must choose one Full sandbox to convert to a smaller sandbox, such as a Developer Pro or a Developer sandbox, depending
on which types you have available.
5. Select the data you want to include in your sandbox (you have this option for a Partial Data or Full sandbox).
For a Partial Data sandbox, select the template you created to specify the data for your sandbox. If you have not created a
template for this Partial Data sandbox, see Creating Sandbox Templates on page 6.
For a Full sandbox, choose how much object history, case history, and opportunity history to copy, and whether or not to
copy Chatter data. Object history is the field history tracking of custom and most standard objects; case history and
opportunity history serve the same purpose for cases and opportunities. You can copy from 0 to 180 days of history, in
30–day increments. The default value is 0 days. Chatter data includes feeds, messages, and discovery topics. Decreasing
the amount of data you copy can significantly speed up sandbox copy time.
You can choose to include Template-based data for a Full sandbox. For this option, you need to have already created a
sandbox template. Then you can pick the template from a list of templates you’ve created. For more information, see
Creating Sandbox Templates on page 6.
6. Click Create.
The process may take several minutes, hours, or even days, depending on the size and type of your organization.

Tip: Try to limit changes in your production organization while the sandbox copy proceeds.

To refresh an existing sandbox:

1. From Setup, click Sandboxes or Data Management > Sandboxes.
You’ll see a list of your sandboxes. Sandboxes that you can refresh have a Refresh link next to the sandbox name.
2. Next to the sandbox name, click Refresh.
3. Select the data you want to copy.
For a Full sandbox, choose how much object history, case history, and opportunity history to copy, and whether or not to
copy Chatter data. Object history is the field history tracking of custom and most standard objects; case history and
opportunity history serve the same purpose for cases and opportunities. You can copy from 0 to 180 days of history, in
30–day increments. The default value is 0 days. Chatter data includes feeds, messages, and discovery topics. Decreasing
the amount of data you copy can significantly speed up sandbox copy time.
4. Click Refresh.
Salesforce starts copying data to the sandbox.
After Salesforce finishes copying data to the sandbox, you still need to activate the sandbox before you can use the refreshed
data. Salesforce sends you an email when your sandbox is ready to activate.

To activate a refreshed sandbox:

5
Deploy Enhancements from Sandboxes Creating Sandbox Templates

1. From Setup, click Sandboxes.

You’ll see a list of your sandboxes. Sandboxes that you can activate have an Activate link next to the sandbox name.
2. Click the Activate link next to the sandbox you wish to activate.
This will take you to a page warning of removal of your existing sandbox.

Warning: Activating a replacement sandbox that was created using the Refresh link completely deletes the
sandbox it is refreshing. All configuration and data in the prior sandbox copy will be lost, including any application
or data changes you have made. Please read the warning carefully, and press the Activate link only if you have no
further need for the contents of the sandbox copy currently in use. Your production organization and its data will
not be affected.

3. Read the warning carefully and if you agree to the removal, enter the acknowledgment text at the prompt and click the
Activate button.

When your sandbox is ready for use:

• You will receive a notification email when your newly created or refreshed sandbox has completed copying. If you are
creating a new sandbox, the newly created sandbox is now ready for use.
• You can click the link in the notification email to access your sandbox.
• Users can log into the sandbox at https://test.salesforce.com by appending .sandbox_name to their Salesforce
usernames. For example, if a username for a production organization is [email protected], and the sandbox is named
“test”, then the modified username to log into the sandbox is [email protected].

Note: Salesforce automatically changes sandbox usernames, but not passwords.

Newly created sandboxes have the default email deliverability setting System email only. The System email
only setting is especially useful for controlling email sent from sandboxes so that testing and development work
doesn’t send test emails to your users.

See Also:
Sandbox Overview
Creating Sandbox Templates
Managing Sandboxes
Sandbox Setup Tips and Considerations
Sandbox Restrictions and Licenses

Creating Sandbox Templates

Sandbox templates control what data is copied into a sandbox.

Available in: Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To view a sandbox: “View Setup and Configuration”
To create, refresh, activate, and delete sandbox: “Modify All Data”

6
Deploy Enhancements from Sandboxes Managing Sandboxes

Sandbox data templates allow you to pick specific objects and data to copy to your Full or Partial Data sandbox so you can
control the size and content of each sandbox. Sandbox data templates are only available for use with Full or Partial Data
sandboxes.
When you create a sandbox data template, you select the object data (standard and custom) to copy. All of the records for the
selected objects are copied to the new sandbox.
Some objects are included even before you’ve selected anything because they’re required in any organization. The template
starts with all of the required objects and metadata for a Developer Pro sandbox, and then adds the object data you selected
in the template. Other objects are added automatically when you select objects that are dependent on them. As you configure
the template, the Copy Statistics panel shows you an estimate of how much data would be copied to a sandbox based on this
template.
As you change the schema of the objects in your organization, Salesforce updates the template by adding or subtracting the
related, included objects. For example, if Object A is a master of Object B, and you add Object B to a template, Salesforce
requires Object A in the template, and adds Object A.

1. From Setup, click Sandboxes > Sandbox Templates tab or Data Management > Sandboxes > Sandbox Templates tab.
2. Click New Sandbox Template or click Edit next to an existing template you want to modify.
3. Enter a name and description for the sandbox template.
4. To add objects to the template, select the checkbox for each object you want from the available Objects list.
The Object Details section shows you the objects to be added automatically with the one you’ve selected.
5. To remove objects from the template, deselect the checkbox for the object in the available Objects list.
If you remove an object you previously selected, dependent objects you didn’t explicitly select are removed. If you attempt
to remove an object with dependent objects, you’ll receive a warning requesting a confirmation of the removal. Once you
confirm your choice, those objects will also be removed.
6. Click Save.

See Also:
Creating or Refreshing a Sandbox
Sandbox Overview

Managing Sandboxes
Available in: Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To view a sandbox: “View Setup and Configuration”
To create, refresh, activate, and delete sandbox: “Modify All Data”

To manage your sandboxes, in Setup click Sandboxes. Salesforce displays the available sandboxes you've purchased, as well
as a list of your sandboxes in use.
Your sandbox information is organized by tabs.

Sandbox Tab
This tab lists any available sandboxes you have created.
• Click New Sandbox.

7
Deploy Enhancements from Sandboxes Managing Sandboxes

Salesforce deactivates the New Sandbox button when an organization reaches its sandbox limit. If necessary, contact
salesforce.com to order more sandboxes for your organization.
Also, Salesforce deactivates all refresh links if you have exceeded your sandbox limit. For detailed steps, see Creating or
Refreshing a Sandbox on page 3.
• Administrators can click Login to log into a sandbox as a user.
Salesforce only displays this option for active sandboxes, and you must be logged into your organization as an administrator
to see the Login button.
Users can log into the sandbox at https://test.salesforce.com by appending .sandbox_name to their Salesforce
usernames. For example, if a username for a production organization is [email protected], and the sandbox is named
“test”, then the modified username to log into the sandbox is [email protected].
• Click a sandbox name to see the sandbox detail page. On the sandbox detail page, you can:
◊ Click Refresh to replace an existing sandbox with a new copy. Salesforce only activates the Refresh button for sandboxes
that are eligible for refreshing. For full-copy sandboxes, this is any time after 29 days from the previous creation or
refresh of that sandbox. For Developer Pro sandboxes (including developer sandboxes), you can refresh once per day.
Your existing copy of this sandbox remains available while you wait for the refresh to complete. The refreshed copy is
inactive until you activate it.
◊ Click Activate to activate a refreshed sandbox. Salesforce only displays this option for sandboxes that are not activated.
You must activate your refreshed sandbox before you can access it.
Warning: Activating a refreshed sandbox replaces the existing sandbox with the refreshed version. This
permanently deletes the existing version and all data in it. Your production organization and its data will not
be affected.

◊ Click Edit to change the name or description of the sandbox.

◊ Click Delete to remove the sandbox entirely. If you delete a sandbox, you must wait 29 days before replacing it with
a new full-copy sandbox, or one day before you can replace it with another Developer Pro sandbox.
Warning: Deleting a sandbox permanently erases the sandbox and all data in it. Your production organization
and its data will not be affected.

Sandbox Templates Tab

If you have purchased a license for Partial Data or Full sandboxes, this tab lists any templates you have created.
In the Sandbox Templates tab, you can create a new Sandbox Data Template, create a new sandbox from an existing template,
edit or delete an existing template, or find more information about the template by clicking the template name. For more
information about creating a Sandbox Data Template, see Creating Sandbox Templates on page 6

Sandbox History Tab

This tab displays a log of your sandbox creation and refresh history, including when sandboxes were created and who created
them. This tab provides information only. To see more detail or make changes to an existing sandbox, use the Sandbox tab.

See Also:
Creating or Refreshing a Sandbox
Sandbox Restrictions and Licenses
Development Lifecycle Guide

8
Deploy Enhancements from Sandboxes Sandbox Setup Tips and Considerations

Sandbox Setup Tips and Considerations

Available in: Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To view a sandbox: “View Setup and Configuration”
To create, refresh, activate, and delete sandbox: “Modify All Data”

Consider the following before you create a sandbox.

Servers and IDs

• Salesforce substitutes a new organization ID for your sandbox in place of your production organization ID because two
organizations cannot share the same ID. So, the organization ID of your sandbox changes each time your sandbox is
refreshed. Salesforce inserts the new value in any place the organization ID is used, such as text values and metadata.
The organization ID you are currently logged into can be found in Setup at Company Profile > Company Information.
Any script or process, such as test scripts or Web-to-Lead, that depends on a “hard coded” organization ID needs to use
the current ID for the sandbox. When you deploy your changes to a production organization, update those scripts or
processes with the production organization ID.
• Salesforce stores sandbox organizations on several instances. When a sandbox is created or refreshed, an instance is selected
for your sandbox, so your sandbox organizations may appear on different instances and have different URLs.
• When data is copied to a sandbox, the object IDs (the unique identifiers for all objects— the same as the ID Field Type
in the developer API) are also copied to the sandbox instance. However, after the copy or refresh of data to a sandbox, the
object IDs do not synchronize between the production organization instance and your sandbox instance. The sandbox
instance and its corresponding production organization instance act as independent organizations. Object data (and the
corresponding object IDs) created in the production organization instance after the creation or refresh of a sandbox are
not synchronized into the sandbox instance. The sandbox instance has the same behavior— new objects created in the
sandbox instance are not synchronized back to the production organization instance.

Users and Contacts

• User information is included in a sandbox copy or refresh for all sandbox types. Because all Salesforce usernames must be
unique and reference a single organization, all copied usernames are modified to ensure uniqueness during the copy process.
For each username, the copy process applies modifications as necessary to generate a unique, new username:
◊ First, the sandbox name is appended to the username. For example, the username [email protected] for a sandbox
named test becomes [email protected].
◊ If the resulting username is not unique, a second modification is performed in which a number of characters and digits
are prepended to the modified username. This second modification may result in a username such as
[email protected].

When you log in with the modified username, you log into the corresponding sandbox.
• The copy process doesn’t copy Contact data to developer sandboxes. Therefore, Customer Portal users aren’t copied.
However, the copy process does copy the Customer Portal licenses, so you can create Customer Portal users in these
sandboxes as needed.
• User email addresses are modified in a sandbox so that production users, who may not know of the sandbox, don’t receive
automatically generated email messages from the sandbox, such as notifications from triggered workflow or escalation
rules. If you do want sandbox users to receive automatically generated emails as part of your testing, you can manually
correct the email addresses while logged into the sandbox.

9
Deploy Enhancements from Sandboxes Sandbox Setup Tips and Considerations

Warning: Sandboxes automatically change Salesforce user email addresses, but don’t change other email addresses
in Salesforce, such as those in contact records. To avoid sending unsolicited email from your sandboxes, manually
invalidate or delete all email addresses in your sandboxes that don’t belong to users of the sandbox. When testing
outbound email, change contact email addresses to those of testers or an automated test script.

Email Deliverability
Newly created sandboxes have the default email deliverability setting System email only. To configure email deliverability
settings, in the sandbox organization, from Setup, click Email Administration > Deliverability. If editable, set the Access
level in the Access to Send Email section. You may not be able to edit the Access level if salesforce.com has
restricted your organization’s ability to change this setting.
• No access>: Prevents all outbound email to and from users.
• System email only: Allows only automatically generated emails, such as new user and password reset emails.
• All email>: Allows all types of outbound email. Default for new, non-sandbox organizations.

Tip: The System email only setting is especially useful for controlling email sent from sandboxes so that testing
and development work doesn’t send test emails to your users.
• Newly created sandboxes default to System email only.
• Sandboxes created before ’Spring 13 default to All email.

Creating, Refreshing, and Deleting Sandboxes

• You can now copy Site.com and Site.com community sites to sandbox.
• Sandbox copy is a long-running operation that occurs in the background. You are notified of the completion of a sandbox
copy via email. Sandbox refreshes might complete in minutes, days, or even more than a week.
• A number of conditions factor into the duration of a sandbox copy or refresh, including the number of customizations,
data size, numbers of objects and configuration choices (for full copies), and server load. Also, sandbox refreshes are queued,
so your requested copy may not start immediately after your request.
• A sandbox is not a point-in-time snapshot of the exact state of your data. Furthermore, we recommend that you limit
changes to your production organization while a sandbox is being created or refreshed. Setup and data changes to your
production organization during the sandbox creation and refresh operations may result in inconsistencies in your sandbox.
You might detect and correct some inconsistencies in your sandbox after it is copied or refreshed.
• Copying or refreshing a sandbox occurs over time, so running a large process (such as a weekly “data scrubbing”) or making
changes to organizations of 30 GB or more during the creation or refresh process can cause some inconsistencies in your
sandbox organization.
• Some types of sandboxes might not be available to choose from if you already reached your organization's limit of the types
of sandboxes you can create or refresh. For example, if your organization is limited to one full sandbox, and a full sandbox
is already created, you may not select a Full sandbox when creating a new sandbox. However, you may refresh your existing
Full sandbox.
• When you are finished with a sandbox, you can refresh it to create a new copy. However, if you have reduced your
organization's number of sandboxes, a Delete link displays next to existing sandboxes, allowing you to delete a sandbox
of your choice. Note that you must delete a sandbox before you can refresh any more sandboxes.
• If you have active Salesforce-to-Salesforce connections in your sandbox, you must deactivate and then reactivate the
connection(s) after the sandbox is refreshed. The connections and mappings are not copied to the refreshed sandbox.

Configuring Full Sandboxes

When you create or refresh a full sandbox, you can configure it not to copy some data that is generally not useful in a sandbox.
Keeping the minimum selections will speed up your sandbox copy.

10
Deploy Enhancements from Sandboxes Sandbox Setup Tips and Considerations

• The Object History, Case History, and Opportunity History options allow you to select the number of days of history
from your production organization to copy to your sandbox. You can copy from 0 to 180 days of history, in 30–day
increments. The default value is 0 days.
• By default, Chatter data won’t be copied to your sandbox. Chatter data includes feeds, messages, and discovery topics.
Select the Copy Chatter Data checkbox if you need to copy it.
• The setup audit trail history of your production organization won’t be copied to your sandbox. The audit trail for your
sandbox organization will start when you begin to use it.
• Archived activities (tasks and events that aren’t available in the production organization because they’re over a year old)
and password history (users’ previous passwords) won’t be copied to your sandbox.

Note: Don’t increase the default selections unless special circumstances require it. Too much data can cause significant
delays in the time it takes to copy your sandbox.

Accessing Sandboxes
• Access changes for sandbox users:
◊ A sandbox refresh deletes and recreates the sandbox as a new copy of the production organization. In effect, this reverses
any manual access changes you've performed. If you created sandbox-only users, they will no longer exist, and a user’s
profile and permissions revert to their values in the production organization. This means that after a refresh, any access
changes will need to be repeated in the new copy.
◊ You can create users in your production organization that are inactive, and then activate them in a sandbox. This is a
good way to create a user in a sandbox that has the appropriate permissions to develop in a sandbox.
◊ Many development and testing tasks require the “Modify All Data” permission. Because your developers might not
have that permission in the production organization, you may need to increase their permissions in a sandbox. Exercise
caution when granting this permission in sandbox organizations that contain sensitive information copied from production
(for example, social security numbers).
◊ Users added in a production organization instance after creating or refreshing a sandbox do not have access to the
production organization instance’s related sandboxes. To create new users in a sandbox, you must log in as the
administrator on the sandbox organization, and create them in the sandbox instance.
◊ You can create new users for sandbox development, but these count against the number of licensed users in your
organization. To reduce your license count, you can disable production users who won’t need access to the sandbox
before you create or refresh a sandbox.

• Always log in to your sandbox organization using the https://test.salesforce.com login URL.
• Remember to log in using the modified username as described in Users and Contacts on page 9.
• If using the API, after you log in you must use the redirect URL that is returned in the loginResult object for subsequent
access. This URL reflects the instance on which the sandbox is located and the appropriate server pool for API access.
• All sandbox copies are made with federated authentication with SAML disabled. Any configuration information is preserved,
except the value for Recipient URL. The Recipient URL is updated to match your sandbox URL, for example
http://cs1.salesforce.com, after you re-enable SAML. To enable SAML in the sandbox copy, from Setup, click
Security Controls > Single Sign-On Settings; then click Edit, and select SAML Enabled. You must change the value
of the Recipient URL in the certificate for your client application as well.

Sandbox Storage Limits

• Partial Data sandboxes have a 5 GB storage limit.
• Developer Pro sandboxes have a 1 GB storage limit.
• Developer sandboxes have a 200 MB storage limit.
• Full sandboxes have the same storage limit as your production organization.
• Sandboxes don’t send email notifications when storage limits are reached. However, if you reach the storage limit of your
sandbox, you cannot save new data in your sandbox. To check your storage limits, from Setup, click Data Management
> Storage Usage in your sandbox.

11
Deploy Enhancements from Sandboxes Sandbox Setup Tips and Considerations

Customization and Data Changes

• Customizations and data changes in your production organization don’t automatically appear in your sandboxes. You must
create a new sandbox or refresh an existing one to see the customizations made to your organization since the last time
you created or refreshed a sandbox.
• You can only add, edit, or delete Apex using the Salesforce user interface in a Developer Edition or sandbox organization.
In a Salesforce production organization, you can only make changes to Apex by using the compileAndTestAPI() call.
• If your sandbox is the same version as Force.com AppExchange, you can:
◊ Install and deploy apps from Force.com AppExchange in your sandbox.
◊ Publish apps from your sandbox to Force.com AppExchange.
Publishing managed packages from a Force.com Sandbox is not advised, as refreshing or deleting the sandbox will
prevent any revisions to that managed package.

The version of your sandboxes may differ from Force.com AppExchange around the time of a Salesforce release. Check
the logo in the upper left corner of your sandbox home page for version information.
• If your organization uses quote templates, and you create a Developer Pro sandbox, templates that contain Text/Image
fields cannot be opened for editing within the sandbox.
• If your production organization uses an image in quote templates and you copy the organization to your sandbox, the image
path will no longer be correct and the image will appear as a broken link. To display the image, reinsert it from the correct
location on your sandbox.

Service Exclusions
• The following features are disabled and cannot be enabled in sandboxes:
◊ Case escalation.
◊ Contract expiration warnings.
Case escalation, and contract expiration warnings are disabled because they automatically send email to contacts,
customers, and users who should not interact with sandboxes.
◊ Subscription summary.
◊ Data exports (in Setup at Data Management > Data Export > Export Now or Data Management > Data Export >
Schedule Export).
◊ The ability to create Salesforce sandboxes.
◊ Email service addresses that you create in your sandbox cannot be copied to your production organization.
◊ The ability to publish Site.com sites.

Other Service Differences

• Only custom links created as relative URLs, such as /00Oz0000000EVpU&pv0={!Account_ID} will work when copied
to your sandboxes. Custom links created as absolute URLs, such as
https://na1.salesforce.com/00Oz0000000EVpU&pv0={!Account_ID}, don’t work in your organization's
sandboxes. We recommend that you use only relative URLs in your production organization. Otherwise, you will need to
correct the URLs in each sandbox.
• Salesforce has a background process that permanently deletes records in the Recycle Bin that are older than 15 days. This
process runs at different times on different servers, so its timestamp in your sandbox differs from its timestamp in your
production organization. Applications and integrations that depend on this timestamp may fail if they are first connected
to one environment, such as your production organization, and then later connected to another environment, such as your
sandbox. Keep this in mind when developing applications and integrations that depend on this timestamp.

12
Deploy Enhancements from Sandboxes Sandbox Restrictions and Licenses

Note that the time of the latest execution of the background delete process is available through the getDeleted() API
call.

See Also:
Creating or Refreshing a Sandbox
Sandbox Overview
Sandbox Restrictions and Licenses

Sandbox Restrictions and Licenses

Available in: Enterprise, Performance, Unlimited, and Database.com Editions

The following information includes restrictions and troubleshooting information for access to sandboxes.
Sandbox services are restricted if your organization doesn't comply with salesforce.com's licensing rules. This typically happens
when sandbox licenses expire.
As sandbox licenses expire, Salesforce.com decreases the count of available sandbox licenses for the selected sandbox type.

Note: Salesforce.com does not automatically delete sandbox organizations due to a license expiration. When the
licenses expire and your current license count is lower than the number of provisioned sandbox organizations,
Salesforce.com removes sandbox services, such as Refresh, Sandbox Org Accessibility, or Login.

There are a few different types of restrictions you might encounter when your organization doesn't comply with licensing
rules.
Unactivated Sandboxes
New sandboxes that aren’t activated within 30 days will be deleted. Users who have created or most recently refreshed
any sandbox for your organization will get at least two email notifications before we schedule the sandbox for deletion.

Locked Sandboxes
Sandboxes that have been locked for 60 days will be deleted. Users who have created or most recently refreshed any
sandbox for your organization will be notified prior to scheduling the sandbox for deletion. They will get at least three
email notifications over 30 days. Sandboxes become locked when all the licenses for that type of sandbox expire.

Unused Sandboxes
Sandboxes that no one has logged into for 180 days will be deleted. Users who have created or most recently refreshed
any sandbox for your organization will be notified prior to scheduling the sandbox for deletion. They will get at least
three email notifications over 30 days. To keep a sandbox active and avoid email notifications, log in periodically.

Based on licensing and usage, you might encounter the following scenarios. Follow the suggested resolutions:
Unable to Refresh a Particular Type of Sandbox
Cause—Your organization is using more sandboxes of a specific type than its sandbox licenses permit.
Example—Your organization has three full sandboxes, but only two full sandbox licenses.
Effect—You can't refresh a sandbox of this type. In the example, you can't refresh full sandboxes.
Resolution—Delete sandboxes to comply with the number allowed by your organization's sandbox licenses, or purchase
more sandbox licenses.

13
Deploy Enhancements from Sandboxes Deploy Your Changes

All Sandboxes of a Particular Type are Locked

Cause—The license count of a given type, including higher hierarchical types, is zero.
Example—Your organization has three full sandboxes and zero full sandbox licenses.
Effect—All sandboxes of a particular type are locked. You don't have access to the sandboxes.
Resolution—Purchase the correct sandbox licenses to unlock the sandboxes. If you don't purchase enough licenses, you
can't refresh sandboxes of that type.

All Sandboxes are Locked

Cause—Your production organization is locked.
Example—Your organization has one full sandbox and one developer-sandbox, but you can't log in to either sandbox.
Effect—If your production organization is locked, all sandboxes associated with the organization are locked.
Resolution—Contact your salesforce.com representative to unlock your organization. When your production organization
is unlocked, the sandboxes are unlocked as well.

See Also:
Sandbox Overview
Creating or Refreshing a Sandbox
Managing Sandboxes
Sandbox Setup Tips and Considerations

Deploy Your Changes

Deployment Overview
User Permissions Needed
To edit deployment connections: “Deploy Change Sets”
To use outbound change sets:
“Create and Upload Change Sets,”
“Create AppExchange Packages,”
AND
“Upload AppExchange Packages”

To use inbound change sets: “Deploy Change Sets”

From Setup, click Deploy to access tools used for migrating metadata changes between organizations.
Deployment Connections
In order to use the change sets feature, a deployment connection is required. You can specify connection permissions
for both outbound and inbound change sets on the Deployment Connections page.

Outbound Change Sets

Make changes in the organization you are logged into, and upload those changes to another organization.

14
Deploy Enhancements from Sandboxes Choose Your Tools for Developing and Deploying Changes

Inbound Change Sets

Accept, modify, or reject change sets uploaded from other organizations.

From Setup, click Deployments or Deploy > Monitor Deployments to monitor the progress of deployments made through
the Metadata API.

See Also:
Change Sets Overview
Monitoring Metadata Deployments

Choose Your Tools for Developing and Deploying Changes

Available in: Performance, Unlimited, Developer, Enterprise, and Database.com Editions

Whether you’re an administrator using point-and-click tools or a developer writing code, you can pick the right tool, work in
a sandbox, and deploy complete changes to a production organization. You can customize and code changes for your organization
in a sandbox using one, or more, of the tools provided by Salesforce.

Develop and Deploy Apex in the Developer Console

Develop and Deploy Using the Force.com IDE
Develop and Deploy Using SOAP API
Deploy Using the Force.com Migration Tool
Deploy Using Change Sets

Develop and Deploy Apex in the Developer Console

Available in: Performance, Unlimited, Developer, Enterprise, and Database.com Editions

User Permissions Needed

To use the Apex Deployment Tool: “Author Apex”

The Developer Console is an integrated development environment with a collection of tools you can use to create, debug, and
test applications in your Salesforce organization.
To open the Developer Console, click Your name > Developer Console.

Develop and Deploy Using the Force.com IDE

Available in: Performance, Unlimited, Developer, Enterprise, and Database.com Editions

You can download the Force.com IDE to help you code projects for your organization. Using this tool, you can also compile
and test the code you write, synchronize changes in a sandboxt, and deploy your code to a production organization.
For more information, see the Force.com IDE page.

15
Deploy Enhancements from Sandboxes Choose Your Tools for Developing and Deploying Changes

Note: The Force.com IDE is a free resource provided by salesforce.com to support its users and partners, but is not
considered part of our Services for purposes of the salesforce.com Master Subscription Agreement.

See Also:
Develop and Deploy Using SOAP API
Choose Your Tools for Developing and Deploying Changes

Develop and Deploy Using SOAP API

Available in: Performance, Unlimited, Developer, Enterprise, and Database.com Editions

You can use the SOAP API to develop and deploy changes to a development or sandbox organization, programmatically.
For more information about the SOAP API, and other API, see the SOAP API Developer’s Guide.

See Also:
Choose Your Tools for Developing and Deploying Changes

Deploy Using the Force.com Migration Tool

Available in: Performance, Unlimited, Developer, Enterprise, and Database.com Editions

User Permissions Needed

To use the Apex Deployment Tool: “Author Apex”

Download the Force.com Migration Tool if you want to perform a file-based deployment of metadata changes and Apex
classes from a Developer Edition or sandbox organization to a production organization using Apache's Ant build tool.
To download the Force.com Migration Tool:

1. From Setup, click Develop > Tools.

2. Click Force.com Migration Tool.
3. Save the salesforce_ant.zip file and unzip its contents to the location of your choice.

The salesforce_ant.zip file contains the files you need to run an ant task that exercises the compileAndTest API call,
including:

• A Readme.html file that explains how to use the tools

• A Jar file containing the ant task: ant-salesforce.jar
• A sample folder containing:

◊ A codepkg\classes folder that contains SampleDeployClass.cls and SampleFailingTestClass.cls

◊ A codepkg\triggers folder that contains SampleAccountTrigger.trigger
◊ A mypkg\objects folder that contains the custom objects used in the examples
◊ A removecodepkg folder that contains XML files for removing the examples from your organization

16
Deploy Enhancements from Sandboxes Connect Organizations for Deployment

◊ A sample build.properties file that you must edit, specifying your credentials, in order to run the sample ant tasks
in build.xml
◊ A sample build.xml file, that exercises the deploy and retrieve API calls

Note: The Force.com Migration Tool is a free resource provided by salesforce.com to support its users and partners,
but is not considered part of our Services for purposes of the salesforce.com Master Subscription Agreement.

See Also:
Force.com Migration Tool Guide
Choose Your Tools for Developing and Deploying Changes

Deploy Using Change Sets

Available in: Performance, Unlimited, Enterprise, and Database.com Editions

You can deploy workflows, rules, Apex classes and triggers, and other customization from a sandbox organization to your
production organization. You can create an outbound change set in the Salesforce user interface and add the components that
you would like to upload and deploy to the target organization. To access change sets, from Setup, click Deploy.

See Also:
Change Sets Overview
Choose Your Tools for Developing and Deploying Changes

Connect Organizations for Deployment

Deployment Connections
User Permissions Needed
To edit deployment connections: “Deploy Change Sets”

In order for change sets to be sent from one organization to another, a deployment connection is required between the
organizations. Deployment connections can't be created between arbitrary organizations; instead, a deployment connection
is created between all organizations affiliated with a production organization. For example, if you have a production organization
(Prod) and two sandboxes (Dev and Test), a deployment connection is created between production and each sandbox (Prod
and Dev, and another connection between Prod and Test), as well as between the sandboxes (Dev and Test).
A deployment connection alone doesn't enable change sets to be sent between organizations. Each organization must be
authorized to send and receive change sets. This added level of security enforces code promotion paths and keeps organizations'
setup metadata from being overwritten by mistake.
For example, the following figure illustrates one possible migration path for a production organization and two sandboxes. In
this example, the production organization can only receive changes that have been fully tested, so only the Test sandbox is
authorized to upload change sets to production. In order to synchronize development projects with the production organization,

17
Deploy Enhancements from Sandboxes Connect Organizations for Deployment

the Prod organization can send change sets to the Dev sandbox, but not to the Test sandbox. Finally, because the features in
development need iterative testing, Dev and Test sandboxes should be able to send change sets back and forth.

Figure 1: Change Set Authorization Enforces Code Path

Note: This illustration describes one possible code migration path. Your department must create its own policies for
organizations to send and receive change sets to one another.

See Also:
Deploying a Change Set
Viewing Available Deployment Connections
Authorizing a Deployment Connection
Viewing Details of a Deployment Connection

Authorizing a Deployment Connection

In order for another organization to send change sets to the organization you are logged into, you must authorize the inbound
change set:

1. From Setup, click Deploy > Deployment Connections.

2. Click Edit next to the organization you want to authorize.
3. Select Allow Inbound Changes.
4. Click Save.

See Also:
Viewing Available Deployment Connections
Viewing Details of a Deployment Connection
Deployment Connections

Viewing Available Deployment Connections

A deployment connection enables customizations to be copied from one organization to another. The deployment connections
list shows which organizations are authorized to upload changes to this organization, and which organizations allow this
organization to upload changes to them.

18
Deploy Enhancements from Sandboxes Connect Organizations for Deployment

To view available connections, from Setup, click Deploy > Deployment Connections.
Action
Click Edit next to the organization that you want to allow or disallow change sets from.

Name
A list of organizations that have deployment connections to the organization you are currently logged into. Click the
name of an organization to view more information about the connection.

Description
A brief description of the connected organizations.

Type
The type of organization you are connected to. Possible values are Production, Full Copy Sandbox, Configuration Only
Sandbox, and Developer Sandbox.

Upload Authorization Direction

The arrows show the direction in which uploads can occur. A broken line means that no change sets are authorized in
either direction. To authorize the connected organization to send you inbound change sets, edit the deployment connection
for this organization. If you want to send outbound change sets to a connected organization, the administrator for that
organization must edit the connection for that organization.

See Also:
Authorizing a Deployment Connection
Viewing Details of a Deployment Connection
Deployment Connections

Viewing Details of a Deployment Connection

A deployment connection enables customizations to be copied from one organization to another. The deployment connections
list shows which organizations are authorized to upload changes to this organization, and which organizations allow this
organization to upload changes to them.
To view connection details:

1. From Setup, click Deploy > Deployment Connections.

2. Click the name of the organization you want to view.

Name
The name of the selected organization. This is not the organization you are logged into.

Description
A brief description of the organization.

Type
The type of organization you are connected to. Possible values are Production, Full, Partial Data, Developer Pro, and
Developer.

Allow Inbound Changes

If selected, the named organization can send change sets to the organization you are currently logged into. This is a
read-only field and can only be modified by selecting Allow Inbound Changes in the target organization.

19
Deploy Enhancements from Sandboxes Change Sets

Accepts Outbound Changes

If selected, the named organization allows change sets to be sent to it from the organization you are currently logged
into.

See Also:
Authorizing a Deployment Connection
Viewing Available Deployment Connections
Deployment Connections

Change Sets

Change Sets Overview

Available in Enterprise, Performance, Unlimited, and Database.com Editions

User Permissions Needed

To edit deployment connections: “Deploy Change Sets”
To use outbound change sets: “Create and Upload Change Sets,”
“Create AppExchange Packages,”
AND
“Upload AppExchange Packages”

To use inbound change sets: “Deploy Change Sets”

A change set is a means by which one organization can send customizations to another organization. For example, you could
create a new object in a sandbox organization and send it to your production organization using a change set. Change sets can
only contain modifications you can make through the Setup menu; therefore, you can't use a change set to upload a list of
contact records. In other words, change sets contain metadata, not data.
When you want to send customizations from your current organization to another organization, you create an outbound change
set. Once you send the change set, the receiving organization sees it as an inbound change set.
Sending a change set between two organizations requires a deployment connection. Change sets can only be sent between
organizations that are affiliated with a production organization—for example, a production organization and a sandbox, or
two sandboxes created from the same organization.

See Also:
Inbound Change Sets
Outbound Change Sets
Components Available in Change Sets
Special Behavior in Deployments

20
Deploy Enhancements from Sandboxes Change Sets

About Permission Sets and Profile Settings in Change Sets

Available in Enterprise, Performance, Unlimited, and Database.com Editions

Developers can use permission sets or profile settings to specify permissions and other access settings in a change set. When
deciding whether to use permission sets, profile settings, or a combination of both, consider the similarities and differences.

Behavior Permission Sets Profile Settings

Included permissions and settings • Standard object permissions • Assigned apps
• Standard field permissions • Tab settings
• User permissions (such as “API • Page layout assignments
Enabled”) • Record type assignments
Note: Assigned apps and tab • Login IP ranges
settings are not included in • User permissions
permission set components.

Included permissions and settings that • Custom object permissions • Custom object permissions
require supporting components • Custom field permissions • Custom field permissions
• Apex class access • Apex class access
• Visualforce page access • Visualforce page access

Added as a component? Yes No. Profiles are added in a separate

setting.

For custom object permissions, custom field permissions, Visualforce page access, and Apex class access, you must include
supporting components in the change set. For example, object permissions for the custom object Items are included only if the
Items object is also included.

Note: Login IP ranges included in profile settings will overwrite the login IP ranges for any matching profiles in the
target organization.

See Also:
Inbound Change Sets
Outbound Change Sets

Components Available in Change Sets

The following types of components may be added to a change set.

Note:

• The components available for a change set vary by edition.

21
Deploy Enhancements from Sandboxes Change Sets

• If you create or modify components that aren’t available in a change set, you can't send those components from
one organization to another in a change set. In this case, migrate the changes manually by repeating the steps you
performed when you created or modified the component.
• List views and tabs are visible to all users when you deploy a change set. Change the visibility in the destination
organization if necessary.

• Account Criteria Based Sharing Rule

• Account Owner Sharing Rule
• Account Territory Owner Sharing Rule
• Action (includes object-oriented publisher actions and global publisher actions)
• Analytic Snapshot
• Apex Class
• Apex Sharing Reason
• Apex Trigger
• App
• Approval Process (with some restrictions)
• Assignment Rule
• Auth. Provider
• AutoResponse Rule
• Button or Link
• Call Center
• Campaign Criteria Based Sharing Rule
• Campaign Owner Sharing Rule
• Case Criteria Based Sharing Rule
• Case Owner Sharing Rule
• Communities (Zones)
• Compact Layout
• Contact Criteria Based Sharing Rule
• Contact Owner Sharing Rule
• Custom Data Type
• Custom Field
• Custom Label
• Custom Object
• Custom Object Criteria Sharing Rule
• Custom Object Owner Sharing Rule
• Custom Report Type
• Custom Setting
• Dashboard
• Document
• Email Template
• External Data Source
• Escalation Rule
• Field Set
• Flexible Page
• Flow

22
Deploy Enhancements from Sandboxes Change Sets

• Folder
• Group
• Home Page Component
• Home Page Layout
• Letterhead
• Language Translation
• Lead Criteria Based Sharing Rule
• Lead Owner Sharing Rule
• List View
• Opportunity Criteria Based Sharing Rule
• Opportunity Owner Sharing Rule
• Page Layout
• Permission Set
• Post Templates for Approvals in Chatter
• Queue
• Record Type
• Remote Site
• Report
• Role
• S-Control
• Send Action
• Static resource
• Tab
• Territory
• User Criteria Based Sharing Rule
• User Membership Based Sharing Rule
• Validation Rule
• Visualforce Component
• Visualforce Page
• Workflow Email Alert
• Workflow Field Update
• Workflow Outbound Message
• Workflow Rule
• Workflow Task
• Workflow Time Trigger

See Also:
Validating a Change Set
Creating an Outbound Change Set
Selecting Components for an Outbound Change Set
Special Behavior in Deployments

Restrictions for Approval Processes in Change Sets

Understand these restrictions before you include approval processes in change sets.

23
Deploy Enhancements from Sandboxes Change Sets

• If the approval page fields include any custom fields on standard objects, you need to manually add those custom fields to
outbound change sets. The View/Add Dependencies option for selecting change set components won’t include these
fields.
• If the approval process references any post templates that contain custom fields, then you need to resave those post templates
in the originating organization before adding them to the change set. From Setup, click Create > Workflow & Approvals
> Post Templates. For each post template, click Edit and then Save.
• Change sets don’t include the order of active approval processes from the source organization. You may need to reorder
the approval processes in the destination organization after deployment.
• If you change the Unique Name of an approval process that was previously included in a change set and deployed in
another organization, and you resend the approval process via a change set, a new approval process will be created upon
deployment in the other organization. The previously deployed approval process will not be modified.

Change Sets Implementation Tips

Authorization required to upload changes
Before you can deploy a change set from one organization to another, an administrator in the target organization must
authorize uploads across the deployment connection between the two organizations.

Deployment Connections list displays all connections

The Deployment Connections list is automatically populated with your production organization and all sandboxes. It
is possible to deploy between any of these organizations, but no other organizations.

Change set connections unavailable during maintenance

Authorizing deployment connections and uploading pages require information from the production organization, and
are unavailable when production is undergoing maintenance. During this time you can construct outbound change sets
but not upload them.

Sandboxes must be available

If an organization has no sandboxes provisioned, the user may see an Insufficient Privileges error on the Deployment
Connections page.

Deployment doesn’t automatically restart

If an error occurs during change set validation or deployment, you must manually restart the process. Be sure your
organization is not locked, undergoing maintenance, or otherwise inaccessible.

Deployment is a one-way transaction

A change set is deployed in a single transaction. If the deployment is unable to complete for any reason, the entire
transaction is rolled back. After a deployment completes successfully, all changes are committed to your organization
and the deployment can’t be rolled back.

Deployments maintain user references

If a component in a change set refers to a specific user, such as recipients of workflow email notifications or dashboard
running users, then during deployment the system attempts to locate a matching user in the destination organization by
comparing usernames.
When you copy data to a sandbox, the fields containing usernames from the production organization are altered to
include the sandbox name. For example, in a sandbox named test, the username [email protected] becomes

24
Deploy Enhancements from Sandboxes Change Sets

[email protected]. During a deployment using change sets, the .test in the username is ignored. This process
transfers a user added to a component in one sandbox to other sandboxes or production organizations.

See Also:
Change Sets Best Practices
Special Behavior in Deployments

Change Sets Best Practices

Deploy all dependent components
Make sure each outbound change set contains all interdependent components that don't exist in the target organization.
If you try to deploy a component that refers to another component missing from the target organization and from the
change set, the deployment fails.
Change sets give you fine-grained control over what you deploy. For example, you can migrate custom fields individually.
To deploy a custom object and all of its fields, you must add the custom object and every field to the change set; adding
just the custom object to the change set won't cause deployment to fail, but results in an empty custom object.

Add permissions and access settings to outbound change sets

Adding profiles or permission sets to outbound change sets allows administrators to migrate permissions for users so
they can access the new functionality. There are significant differences between permission sets and profile settings in
change sets. For details, see “About Permission Sets and Profile Settings in Change Sets on page 21”.

Clone a change set to add dependent components to an uploaded change set

After you upload a change set, you can't change its contents. If you need to add dependent components to a change set
you already uploaded, clone the change set, add the dependent components, and then upload it again.

Plan deployments around maintenance schedule

Plan your deployment activities around the maintenance schedule for both your production and sandbox organizations.
Some features require information from your production organization when accessed from a sandbox. In addition, the
originating organization is locked while validating an outbound change set, and the target organization is locked while
deploying an inbound change set. (When change sets lock an organization, you can still read and write data to the
organization, but you can’t make any setup changes that would modify the metadata.)

Validate change sets before deployment

You can perform a test deployment of an inbound change set to view the success or failure messages that would occur
with an actual deployment. This is a good idea if you are planning a deployment on a schedule (for example during
low-use hours) and want to determine if the deployment will succeed ahead of time. However, you don't need to perform
a test deployment every time you deploy, as this process takes time to complete and the organization is locked for the
duration. (You can still read and write data to the organization, but you can’t make any setup changes that would modify
the metadata.) To test deploy an inbound change set, click its name and then click Validate.

View component details

You can view the XML representation of a component before you upload an outbound change set or deploy an inbound
change set.

Limit change sets to 5,000 files

Change sets are limited to 5,000 files. If your change set exceeds this limit, you can create separate change sets for email
templates, dashboards, and reports. These components are often the most numerous and have fewer dependencies.

25
Deploy Enhancements from Sandboxes Change Sets

Delete or rename components using the Web interface

You can't use change sets to delete or rename components. To delete components, use the Web interface on the target
organization. To rename a component, first delete the component on the target organization and then upload the new
component in a change set.

Plan for tests to run in the target organization

When a change set is deployed to a production organization, all of the Apex tests in that organization are run, regardless
of whether the classes or tests are part of the change set. If the target organization is a sandbox, however, tests aren’t
automatically run.

See Also:
Change Sets Implementation Tips
Special Behavior in Deployments

Deploy Inbound Changes

Inbound Change Sets
User Permissions Needed
To deploy inbound change sets: “Deploy Change Sets”

Watch a Demo: Change Sets Overview (2:30 minutes)

An inbound change set is a change set that has been sent from another organization to the organization you are logged into. A
change sent must be deployed for the changes to take effect. You can deploy the contents of an inbound change set as a whole,
but not on a component-by-component basis.

See Also:
Viewing Inbound Change Sets
Outbound Change Sets
Change Sets Overview

Viewing Inbound Change Sets

The Inbound Change Sets page lists change sets awaiting deployment, as well as the history of deployed change sets. To view
inbound change sets, from Setup, click Deploy > Inbound Change Sets.

Note: Inbound change sets are permanently deleted six months after the change set is uploaded.

See Also:
Viewing Change Set Details
Validating a Change Set
Deploying a Change Set

26
Deploy Enhancements from Sandboxes Change Sets

Viewing Change Set Details

The Change Sets detail page lists information about a particular change set.

1. From Setup, click Deploy > Inbound Change Sets.

2. Click the name of a change set.

See Also:
Viewing Inbound Change Sets
Validating a Change Set
Deploying a Change Set

Validating a Change Set

You can validate a change set without deploying changes. Validating a change set allows you to view the success or failure
messages you would receive with an actual deploy.

1. From Setup, click Deploy > Inbound Change Sets.

2. Click the name of a change set.
3. Click Validate.

Note: You can't make any changes to your organization while a test deployment is in progress.

4. After the validation completes, click View Results.

See Also:
Viewing Inbound Change Sets
Viewing Change Set Details
Deploying a Change Set

Deploying a Change Set

To deploy a change set:

1. From Setup, click Deploy > Inbound Change Sets.

2. In the Change Sets Awaiting Deployment list, click the name of the change set you want to deploy.
3. Click Deploy.

A change set is deployed in a single transaction. If the deployment is unable to complete for any reason, the entire transaction
is rolled back. After a deployment completes successfully, all changes are committed to your organization and the deployment
can’t be rolled back.

27
Deploy Enhancements from Sandboxes Change Sets

Note: The Force.com platform requires that at least 75% of your code is covered by unit tests before you can deploy
it to a production organization. Ideally, you should strive for 100% coverage. The code coverage restriction is not
enforced for sandbox or Developer Edition organizations.

See Also:
Viewing Inbound Change Sets
Viewing Change Set Details
Special Behavior in Deployments
Monitoring Deployments

Monitoring Deployments
The size and complexity of the change set determines how long it takes for a change set to deploy. During this time, it can be
helpful to monitor the deployment. To track the status of deployments that are in progress from Setup, click Deploy > Inbound
Change Sets > Change Set Detail. Under the Deployment History related list, click View Results.

Note: The Monitor Deployments page can be used for checking the status of deployments made through the Metadata
API. However, change sets are not currently supported in the Monitor Deployments page.

See Also:
Deploying a Change Set
Deployment Connections

Upload Outbound Changes

Outbound Change Sets
User Permissions Needed
To create, edit, or upload outbound change sets: “Create and Upload Change Sets”

Watch a Demo: Change Sets Overview (2:30 minutes)

An outbound change set is a change set created in the organization you are logged into and that you want to send to another
organization. Typically, an outbound change set is used for customizations created and tested in a sandbox and then sent to
a production organization.
Sending an outbound change set to another organization doesn't guarantee that the changes will be implemented in that
organization. The change set must be deployed (accepted) by the target organization before the changes take effect.

28
Deploy Enhancements from Sandboxes Change Sets

Note: Change sets are limited to 2,500 components and a total file size of 400 MB.

See Also:
Selecting Components for an Outbound Change Set
Creating an Outbound Change Set
Inbound Change Sets
Change Sets Overview

Selecting Components for an Outbound Change Set

To select the components in an outbound change set:

1. From Setup, click Deploy > Outbound Change Sets.

2. In the Change Sets list, click the name of a change set, or create a new one.
3. Click Add to add components.
4. Choose the type of component and the components you want to add, and then click Add to Change Set.
5. Click Add Profiles to add profile settings to the change set.
6. Optionally, click View/Add Dependencies to add dependent components.

Note: Dependent components rely on the existence of other components. Unless you are certain that the dependent
components exist in every organization this change set will be deployed to, it's a good idea to add dependent
components to the change set.

See Also:
Creating an Outbound Change Set
Viewing and Adding Dependent Components to a Change Set
Components Available in Change Sets

Viewing and Adding Dependent Components to a Change Set

A dependency is a relationship where one or more components must exist for another component to exist. It's a good idea to
add dependent components to a change set, unless you are sure that the dependent components exist in every organization
where this change set will be deployed.
To add dependent components to an outbound change set:

1. From Setup, click Deploy > Outbound Change Sets.

2. In the Change Sets list, click the name of a change set.
3. Click View/Add Dependencies.
4. On the Component Dependencies page, select the dependent components you wish to deploy and click Add to Change
Set.

29
Deploy Enhancements from Sandboxes Change Sets

Warning: If your change set contains more than 2500 dependencies you will only be able to see the first 2500 in the
view dependencies page.

See Also:
Selecting Components for an Outbound Change Set
Uploading an Outbound Change Set
Components Available in Change Sets

Uploading an Outbound Change Set

Once you’ve assembled the components in a change set, you can upload it to another organization. Note that once you upload
a change set, you can't edit it or recall it.

1. From Setup, click Deploy > Outbound Change Sets.

2. Click the name of a change set.
3. Select the organization you want to send the change set to.
4. Click Upload.

Note: Outbound change sets expire six months after upload, at which time the change set is permanently deleted.

See Also:
Uploading Change Sets During Server Upgrades
Creating an Outbound Change Set

Creating an Outbound Change Set

An outbound change set is a change you want to send from the organization you are logged into to another organization. To
view outbound change sets, from Setup, click Deploy > Outbound Change Sets.

• To create a new change set, click New.

• To view the details of an existing change set, click its name.

See Also:
Cloning an Outbound Change Set
Outbound Change Set Validation Errors

Cloning an Outbound Change Set

You can create a copy of an existing change set by cloning it.

1. From Setup, click Deploy > Outbound Change Sets.

2. Click the name of the change set you want to clone.

30
Deploy Enhancements from Sandboxes Special Behavior in Deployments

3. Click Clone.

See Also:
Creating an Outbound Change Set

Deleting an Outbound Change Set

To delete an outbound change set:

1. From Setup, click Deploy > Outbound Change Sets.

2. Click the name of the change set you want to delete.
3. Click Delete.

See Also:
Creating an Outbound Change Set

Outbound Change Set Validation Errors

If you receive an error about cross-version validation, then the organization used to create the outbound change set is running
on a different platform version than the organization receiving the change set. This error typically occurs during upgrades,
because organizations may be upgraded at different times. If you receive this error, you can only deploy those components that
are compatible between versions.

See Also:
Creating an Outbound Change Set
Uploading an Outbound Change Set

Uploading Change Sets During Server Upgrades

During server upgrades, production and sandbox environments may not be running the same version of the platform. Some
components may have new functionality or other changes that will not allow you to deploy that type of component until the
production organization is running the same version as sandbox.
If you upload a change set that has components that can't be deployed because they are incompatible with the older version,
the system detects which components can't be deployed, and gives you the option of uploading the remaining components.

See Also:
Uploading an Outbound Change Set

Special Behavior in Deployments

Important considerations for specific component types and other contents of a deployment.

Available in: Enterprise, Performance, Unlimited, Developer, and Database.com Editions

31
Deploy Enhancements from Sandboxes Special Behavior in Deployments

When deploying changes to an organization, consider how individual components in your deployment behave so you’re
including all the changes you need to be successful. Use the following information to help you determine what to include in
your deployment, and how the changes appear in the destination organization. The behaviors listed in the Metadata API
section apply if you’re using the Force.com Migration Tool or Force.com IDE.

Change Set Components

Approval Processes
• If the approval page fields include any custom fields on standard objects, you need to manually add those custom
fields to outbound change sets. The View/Add Dependencies option for selecting change set components won’t
include these fields.
• If the approval process references any post templates that contain custom fields, then you need to resave those post
templates in the originating organization before adding them to the change set. From Setup, click Create > Workflow
& Approvals > Post Templates. For each post template, click Edit and then Save.
• Change sets don’t include the order of active approval processes from the source organization. You may need to
reorder the approval processes in the destination organization after deployment.
• If you change the Unique Name of an approval process that was previously included in a change set and deployed
in another organization, and you resend the approval process via a change set, a new approval process will be created
upon deployment in the other organization. The previously deployed approval process will not be modified.

Apex Classes and Apex Triggers

Cancel scheduled Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.

Custom Fields
• You cannot change the data type of a field using the Metadata API. You must manually make this change to the
target organization through the user interace.

Custom Object
You cannot change the sharingModel of an object using the Metadata API. You must manually make this change to
the target organization through the user interface.

Flows
• If you plan to deploy a flow using change sets, you must account for limitations in migration support. Make sure
your flows reference only fields and components available in change sets.
• You can only include one version of a flow in a change set.
• If the flow has no active version when you upload the outbound change set, the latest inactive version is used.
• When you view the dependent components for the change set, the Component Dependencies page lists the
dependencies for all versions of the flow. Add all interdependent components for the relevant flow version to the
outbound change set.
• An active flow in a change set will be inactive once deployed to its destination. You must manually activate it after
deployment.
• Deploying or re-deploying a flow using change sets will always create a new version of the flow in the destination
organization.

Permissions
See About Permission Sets and Profile Settings in Change Sets on page 21.

Page Layout
A deployment containing a profile and record type, but not the assigned page layout for that record type, removes the
existing layout assignment from the profile for that record type. Always include all page layouts for all required record
types in the change set.

32
Deploy Enhancements from Sandboxes Special Behavior in Deployments

Metadata API
Apex Classes and Apex Triggers
Cancel scheduled Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.

Approval Processes
• To use approval processes on Salesforce Knowledge articles with the Metadata API, the article type must be deployed.
For article version (_kav) in approval processes, the supported action types are: Knowledge Action, Email Alert, Field
Update, and Outbound Message.
• If the approval process references any post templates that contain custom fields, then you need to resave those post
templates in the originating organization before adding them to the change set. From Setup, click Create > Workflow
& Approvals > Post Templates. For each post template, click Edit and then Save.
• The metadata doesn’t include the order of active approval processes. You may need to reorder the approval processes
in the destination organization after deployment.
• If you change the Unique Name of an approval process that was previously included in a change set and deployed
in another organization, and you resend the approval process via a change set, a new approval process will be created
upon deployment in the other organization. The previously deployed approval process will not be modified.

Custom Fields
• While you can access Lookup and Picklist fields with the Metadata API, other standard fields cannot be accessed,
even though you can customize some of these fields in the UI
• You cannot change the data type of a field using the Metadata API. You must manually make this change to the
target organization through the user interace.

Custom Object
You cannot change the sharingModel of an object using the Metadata API. You must manually make this change to
the target organization through the user interface.

Apex Classes and Apex Triggers

Cancel scheduled Apex jobs before deploying changes to Apex code. Reschedule the jobs after the deployment.

Connected App
• You cannot set the consumerKey in the Metadata API. It is included in a retrieve operation for informational
purposes. If you try to move the connected app to another organization, you must remove the consumerKey from
the .zip file before the deployment to an organization. A new key will be generated in the destination organization.
• Mobile settings of connected apps are not supported in change sets and must be manually migrated.

Page Layout
A deployment containing page layout assignments replaces all existing page layout assignments in the destination
organization with those specified in the .zip file. Existing page layouts in the organization disappear if they’re not included
in the .zip file. Always include all page layouts for all required record types in the .zip file.

See Also:
Deploying a Change Set
Change Sets Overview
Components Available in Change Sets
Working with the Zip File

33
Deploy Enhancements from Sandboxes Monitoring Metadata Deployments

Monitoring Metadata Deployments

Available in: Enterprise, Performance, Unlimited, Developer, and Database.com Editions

User Permissions Needed

To view metadata deployments: “Modify All Data”

You can use the Metadata API to deploy XML file representations of components into an organization. A component is an
instance of a metadata type in the Metadata API. For example, CustomObject is a metadata type for custom objects, and the
MyCustomObject__c component is an instance of a custom object.

The easiest way to access the Metadata API is to use the Force.com IDE or Force.com Migration Tool. These tools are built
on top of the Metadata API and use the standard Eclipse and Ant tools respectively to simplify the task of working with the
Metadata API.
The deploy call in the Metadata API is asynchronous and may take a while to complete. The Force.com IDE and Force.com
Migration Tool use the deploy call to move XML file representations of components into an organization. To track the status
of deployments that are in progress or completed in the last 7 days for these tools or other clients that are deploying metadata,
from Setup, click Deployments or Deploy > Monitor Deployments.
On the Monitoring Deployments page, you can cancel a deployment while it’s in progress. To cancel a deployment, click
Cancel. The deployment then has the status “Cancel Requested” until the deployment is completely canceled.
The Deployments In Progress list contains the following columns.

Column Description
Deployment A unique identifier used to track the deployment.
Id

Created By The name of the user performing the deployment.

Start Time The date and time when the deployment started, not the time the request is in queue. This value is the
time the deployment Status is set to In Progress.
Validate Indicates whether this deployment is being used to check the validity of the deployed files without making
Only any changes in the organization. A validate-only deployment does not deploy any components or change
the organization in any way.
Status The following values are possible:
• Pending—The deployment has not started. It is waiting in a queue.
• In Progress—The deployment process started, but has not finished. See the Components and Tests
counts on the page to track the deployment progress.
• Cancel Requested—The deployment is being rolled back, but is not yet fully canceled.
• Succeeded—All components deployed successfully, and all tests ran successfully.
• Succeeded (partially)—A subset of changes were committed to the organization, but some files were
missing, some components had errors, or some tests failed. You can only receive this status with the
deployment option RollBackOnError = false.
• Canceled—The deployment has been successfully canceled. No changes were committed to the
organization.

34
Deploy Enhancements from Sandboxes Monitoring Metadata Deployments

Column Description
• Failed—No changes were committed to the organization because files were missing, components had
errors, or tests failed.

Components The progress of the deployment. For example, 10 / 15 (3 errors) indicates that ten components
have been processed successfully out of a total of 15. There were errors for three other components processed
so far.
Tests The progress of the Apex tests that have been run. For example, 13 / 20 (2 errors) indicates that
13 tests have been run successfully out of a total of 20. There were errors for two other tests that have run
so far. The value for the total number of tests is not accurate until the test phase of the deployment has
started.

The Completed Deployments Last 7 days list contains the following columns. Completed deployments are removed from the
list 7 days after completion.

Column Description
Deployment A unique identifier used to track the deployment.
Id

Created By The name of the user who performed the deployment.

Start Time The date and time when the deployment started, not the time the request is in queue. This value is the
time the deployment Status is set to In Progress.
End Time The date and time when the deployment completed.
Validate Indicates whether this deployment is being used to check the validity of the deployed files without making
Only any changes in the organization. A validate-only deployment does not deploy any components or change
the organization in any way.
Status The following values are possible:
• Succeeded—All components deployed successfully, and all tests ran successfully.
• Succeeded (partially)—A subset of changes were committed to the organization, but some files were
missing, some components had errors, or some tests failed. You can only receive this status with the
deployment option RollBackOnError = false.
• Canceled—The deployment has been successfully canceled. No changes were committed to the
organization.
• Failed—No changes were committed to the organization because files were missing, components had
errors, or tests failed.

Components The number of components, including those with errors, that were processed in the deployment. For
example, 10 (1 error) indicates that ten components were processed and there was an error for one
component.
Tests The number of Apex tests, including those with errors, that were run. For example, 13 (2 errors)
indicates that 13 tests were run and there were errors for two tests.

See Also:
Inbound Change Sets
Outbound Change Sets

35
 Index

Index
A Deployment
monitoring 28
Ant task for Apex 15–16 Deployment issues 31
Apex Deployment monitoring 34
tools 15
Approval processes
change set restrictions 23 I
Inbound change set 17–18, 26
C
Change sets M
approval process restrictions 23 Metadata API
best practices 25 deployments 34
cloning 30 Metadata components in change sets 21
deleting 31 Monitoring deployment 28
dependent components 29 Monitoring metadata deployments 34
deploying 27
deployment 26
deployment connections 17–19 O
details 27 Organization
implementation tips 24 copy 1
inbound 26 Outbound change set 17–18, 28, 30–31
outbound 28, 30–31 Outbound change sets
permission sets and profiles 21 selecting components 29
permissions 20 version errors 31
selecting components 29
testing before deployment 27
S
version errors 31
Cloning a change set 30 Sandbox
Components in deployments 31 creating 3
Copy implementation tips 9
organization 1 licenses 13
managing 7
D refreshing 3
restrictions 13
Deleting a change set 31 Sandbox data template 6
Dependent components 29
Deploying
using Change Sets 17
T
using SOAP API 16 Test database 6
using the Force.com IDE 15 Tools for Apex 15
using the Force.com Migration Tool 16

36