Force.com Migration Tool Guide

Force.com Migration Tool Overview
Installing the Force.com Migration Tool
Using the Force.com Migration Tool
Entering Salesforce Connection Information
Constructing a Project Manifest
Creating Retrieve Targets
Retrieving Metadata from a Salesforce Organization
Editing Metadata
Deleting Files from an Organization
Deploying Changes to a Salesforce Organization
Deploying Components
Deploying Code
Deploying a Recent Validation
Running Tests in a Deployment
Running a Subset of Tests in a Deployment
Run the Same Tests in Sandbox and Production Deployments
Canceling a Deployment
Checking the Status of a Task
Common Migration Issues
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Deploying Changes to a Salesforce Organization

The build.xml file specifies targets to retrieve and deploy. The following parameters may be set for each deploy target:

Field Description
username Required if sessionId isn’t specified. The Salesforce username for login. The username associated with this connection must have the “Modify All Data” permission. Typically, this is only enabled for System Administrator users.
password Required if sessionId isn’t specified. The password you use to log into the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password.
sessionId Required if username and password aren’t specified. The ID of an active Salesforce session. A session is created after a user logs in to Salesforce successfully with a username and password. Use a session ID for logging into an existing session instead of creating a new session.
serverurl Optional. The Salesforce server URL (if blank, defaults to www.salesforce.com). To connect to a sandbox instance, change this to test.salesforce.com.
pollWaitMillis Optional. Defaults to 10000. The number of milliseconds to wait when polling for results of the deployment. Note that deployment may succeed even if you stop waiting.
checkOnly Optional. Defaults to false. Set to true to check the validity of the deployed files without making any changes in the organization. This will not deploy any components or change the organization in any way.
maxPoll Optional. Defaults to 200. The number of times to poll the server for the results of the deploy request. Note that deployment may succeed even if you stop waiting.
deployRoot Required if zipFile isn't specified. Specifies the root of the directory tree of files to deploy. You must define a value for either zipFile or deployRoot.
zipFile Required if deployRoot isn't specified.. Specifies the path of the metadata zip file to be deployed. You must define a value for either zipFile or deployRoot.
singlePackage Optional. Defaults to false. Declares that the zipFile or deployRoot parameter points to a directory structure with a single package, as opposed to a set of packages.
allowMissingFiles Optional. Defaults to false. Specifies whether a deploy succeeds even if files that are specified in package.xml are not in the zip file. Do not use this parameter for deployment to production organizations.
autoUpdatePackage Optional. Defaults to false. Specifies whether a deploy should continue even if files present in the zip file are not specified in package.xml. Do not use this parameter for deployment to production organizations.
ignoreWarnings Optional. Defaults to false. This setting indicates that a deployment should succeed even if there are warnings (true) or that one or more warnings will cause the deployment to fail and roll back (false). If there are errors, as opposed to warnings, the deployment will always fail and roll back.
logType Optional. The debug logging level for running tests. The default is None. Valid options are:
  • None
  • Debugonly
  • Db
  • Profiling
  • Callout
  • Detail
purgeOnDelete If true, the deleted components in the destructiveChanges.xml manifest file aren't stored in the Recycle Bin. Instead, they become immediately eligible for deletion.This option only works in Developer Edition or sandbox organizations; it doesn't work in production organizations.
rollbackOnError Optional. Defaults to true. Indicates whether any failure causes a complete rollback (true) or not (false). If false, whatever set of actions can be performed without errors are performed, and errors are returned for the remaining actions. This parameter must be set to true if you are deploying to a production organization.

In earlier versions of the Force.com Migration Tool (Spring '14 and earlier), this parameter is ignored in build.xml and Salesforce behaves as if this parameter is set to true.

Note
runAllTests (Deprecated and available only in API version 33.0 and earlier.) This parameter is optional and defaults to false. Set to true to run all Apex tests after deployment, including tests that originate from installed managed packages.
runTest Optional child elements. A list of Apex classes containing tests run after deploy. For more information, see Running a Subset of Tests in a Deployment.

To use this option, set testLevel to RunSpecifiedTests.
testLevel Optional. Specifies which tests are run as part of a deployment. The test level is enforced regardless of the types of components that are present in the deployment package. Valid values are:
  • NoTestRun—No tests are run. This test level applies only to deployments to development environments, such as sandbox, Developer Edition, or trial organizations. This test level is the default for development environments.
  • RunSpecifiedTests—Only the tests that you specify in the runTests option are run. Code coverage requirements differ from the default coverage requirements when using this test level. Each class and trigger in the deployment package must be covered by the executed tests for a minimum of 75% code coverage. This coverage is computed for each class and trigger individually and is different than the overall coverage percentage.
  • RunLocalTests—All tests in your organization are run, except the ones that originate from installed managed packages. This test level is the default for production deployments that include Apex classes or triggers.
  • RunAllTestsInOrg—All tests are run. The tests include all tests in your organization, including tests of managed packages.

If you don’t specify a test level, the default test execution behavior is used. See “Running Tests in a Deployment” in the Metadata API Developer’s Guide.

This field is available in API version 34.0 and later.
trace Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login.

The Force.com Migration Tool ignores any files or folders with a name starting with a period (.) or ending with a tilde (~) when deploying files. Some source control systems, such as Subversion, create files or folders with names starting with a period. These files can cause issues during deployment to Salesforce, so the Force.com Migration Tool ignores them.

Note

The Force.com Migration Tool comes with a sample build.xml file that lists several deployment targets. You will want to create your own custom targets using the sample targets as starting points. A description of the sample targets follows:

  • deployUnpackaged — deploys unpackaged components specified in the target.
  • deployCode — deploys the contents of the codepkg package specified in the target.
  • undeployCode — deletes classes and triggers in the removecodepkg directory specified by the destructiveChanges.xml manifest. This file is similar to package.xml, but lists components to be deleted. For more information, see Deleting Files from an Organization.
  • deployCodeFailingTest — deploys code that fails testing requirements, strictly for demonstration purposes.
  • deployCodeCheckOnly — verifies that deployment will work, but does not deploy any components.