Salesforce Deployment Using Ant Migration Tool

Ant Migration Tool

The Ant Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce Org. The Ant Migration Tool is especially useful in the following scenarios.

• Development projects for which you need to populate a test environment with a lot of setup changes
• Multistage release processes—A typical development process requires iterative building, testing, and staging before releasing to a production environment
• Repetitive deployment using the same parameters—You can retrieve all the metadata in your organization, make changes, and deploy a subset of components.
• When migrating from stage to production is done by IT—Anyone that prefers deploying in a scripting environment will find the Ant Migration Tool a familiar process.
• Scheduling batch deployments—You can schedule a deployment for midnight to not disrupt users. Or you can pull down changes to your Developer Edition org every day.

Installing the Ant Migration Tool

Before you install the Ant Migration Tool you will need Java and Ant installed on your local machine. Then you can download the Ant Migration Tool from a Salesforce organization.

Install Java and Ant, as described in Prerequisites for Using the Ant Migration Tool.

Download the Ant Migration Tool, as described in Install the Ant Migration Tool.

Prerequisites for Using the Ant Migration Tool

Before you can use the Ant Migration Tool, Java and Ant must be installed and configured correctly. If you already have Java and Ant on your computer, you don’t need to install them, so first verify the installation from a command prompt.

Java

Java version 1.7.x or later is recommended for better security and for the latest TLS security protocols.

To check the version of Java that’s installed on your system

Open a command prompt.

At the prompt, type java -version and press Enter.

To install and configure Ant:

Download Apache Ant version 1.6 or later to a directory of your choice: http://ant.apache.org/bindownload.cgi.

This directory is known as ANT_HOME. When the files are on your computer, no further installation is required.

Add the bin directory to your path. (Only the bin and lib directories are required to run Ant.)

If you are using a Windows operating system, create an ANT_HOME environment variable and set the value to where you have installed Ant. Also, create a JAVA_HOME environment variable and set the value to the location of your JDK.

Install the Ant Migration Tool

Follow these steps to download and install the Ant Migration Tool.

If you don’t have Ant installed, see Prerequisites for Using the Ant Migration Tool.

Download the .zip file of the Winter ’19 Ant Migration Tool. The download link doesn’t require authentication to Salesforce. If you’re logged in to Salesforce, we recommend you log out before accessing the link in your browser.

Save the .zip file locally and extract the contents to the directory of your choice.

The Ant Migration Tool uses the ant-salesforce.jar file that’s in the distribution .zip file. If you installed a previous version of the tool and copied ant-salesforce.jar to the Ant lib directory, delete the previous jar file. The lib directory is located in the root folder of your Ant installation. You don’t need to copy the new jar file to the Ant lib directory.

If you plan to run the tool from a directory other than its installation directory, modify the build.xml file to indicate the location of the ant-salesforce.jar file. Update the location attribute on <pathelement> in build.xml to point to ant-salesforce.jar in the installation directory.

• A Jar file containing the ant task: ant-salesforce.jar
• A sample folder containing:
• A codepkgclasses folder that contains
  • SampleDeployClass.cls and
  • SampleFailingTestClass.cls
• A codepkgtriggers folder that contains
  • SampleAccountTrigger.trigger
• A mypkgobjects folder that contains the custom objects used in the examples
• A removecodepkg folder that contains XML files for removing the examples from your organization
• 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

Entering Salesforce Connection Information

To retrieve or deploy metadata components, you need to edit build.properties to point to a Salesforce Org.

• Go to the location where you extracted the Ant Migration Tool files and open the sample subdirectory.
• Open build.properties in a text editor and do either of the following.
• To use a username and password for login, substitute a valid Salesforce username and password. If you’re using a security token, paste the 25-digit token value at the end of your password.
• To use an active Salesforce session for login, uncomment the sf.sessionId property and substitute a valid session ID. Also, make sure to comment out the sf.username and sf.password properties.
• To use an OAuth access token for login, uncomment the sf.sessionId property and supply the access token. Also, make sure to comment out the sf.username and sf.password properties.

sf.username : 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. When connecting to a sandbox instance, your sandbox name is appended to your username. For example, if your production username is foo@salesforce.com, and one of your sandboxes is called bar, your sandbox username is foo@salesforce.com.bar.

sf.password: The password you use to log in to the org associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password

sf.serverurl: The salesforce server URL. Use https://login.salesforce.com to connect to a production or Developer Edition org. To connect to a sandbox instance, change this to https://test.salesforce.com

sf.sessionId: The ID of an active Salesforce session or the OAuth access token. A session is created after a user logs in to Salesforce successfully with a username and password. Use a session ID for logging in to an existing session instead of creating a new session. Alternatively, use an access token for OAuth authentication

Constructing a Project Manifest

The package.xml file is a project manifest that lists all the components you want to retrieve or deploy in a single request. You can retrieve or deploy only a single package at a time.

Sample package.xml

Retrieving Metadata from a Salesforce Organization

Open a command prompt.

Run Ant by specifying a target name in build.xml. If this is the first time you are running Ant, use ant retrieveUnpackaged to retrieve unpackaged components specified in package.xml.

Deploying Changes to a Salesforce Org

The build.xml file specifies targets to retrieve and deploy. You can set the following parameters for each deploy target.

Check this page  for parameter information: https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool_deploy.html

The Ant Migration Tool comes with a sample build.xml file that lists several deployment targets. You want to create your own custom targets using the sample targets as starting points.

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 the deployment works, but doesn’t deploy any components.

Deploying Components

You can deploy any set of components as a package or into your organization directly in the unpackaged package. The package used is not determined by the build.xml target, but by the

project manifest (package.xml). A sample deployment target follows:

[code language=”HTML”]

<target name=”deployUnpackaged”>
<sf:deploy    username=”${sf.username}”    password=”${sf.password}”sessionId=”${sf.sessionId}”   serverurl=”${sf.serverurl}” deployroot=”projectFolder”/>
</target>

[/code]

Deploying a Recent Validation

Deploying a validation helps you shorten your deployment time because tests aren’t rerun. If you have a recent successful validation, you can deploy the validated components without running tests. You can deploy a recent validation with the <sf:deployRecentValidation> task.

A validation doesn’t save any components in the organization. You use a validation only to check the success or failure messages that you would receive with an actual deployment. To validate your components, add the checkOnly=”true” parameter in your

[code language=”HTML”]
<sf:deployRecentValidation> task.
[/code]

Before deploying a recent validation, ensure that the following requirements are met.

The components have been validated successfully for the target environment within the last 10 days.

As part of the validation, Apex tests in the target org have passed. Code coverage requirements are met.

If all tests in the org or all local tests are run, overall code coverage is at least 75%, and Apex triggers have some coverage.

If specific tests are run with the RunSpecifiedTests test level, each class and trigger that was deployed is covered by at least 75% individually.

Running a Subset of Tests in a Deployment

Test levels enable you to have more control over which tests are run in a deployment. To shorten deployment time to production, run a subset of tests when deploying Apex components. The default test execution behavior in production has also changed. By default, if no test level is specified, no tests are executed, unless your deployment package contains Apex classes or triggers.

If the code coverage of an Apex component in the deployment is less than 75%, the deployment fails. If one of the specified tests fails, the deployment also fails. We recommend that you test your deployment in the sandbox first to ensure that the specified tests cover each component sufficiently. Even if your organization’s overall code coverage is 75% or more, the individual coverage of the Apex components being deployed can be less. If the code coverage requirement isn’t met, write more tests and include them in the deployment.

To run a subset of tests, add the testLevel=”RunSpecifiedTests” parameter to the deploy target. Specify each test class to run for a deploy target in a <runTest> </runTest> child element within the sf:deploy element. Add the test class name within the <runTest> </runTest> tags. Add as many runTest tags as you need, one for each test class.

This deploy target example shows three test classes. Salesforce runs these test classes when deploying this package.

[code language=”HTML”]

<target name=”deployCode”>
<sf:deploy username=”${sf.username}” password=”${sf.password}”
sessionId=”${sf.sessionId}” serverurl=”${sf.serverurl}” deployroot=”codepkg”            testLevel=”RunSpecifiedTests”>
<runTest>TestClass1</runTest>
<runTest>TestClass2</runTest>
<runTest>TestClass3</runTest>
</sf:deploy>
</target>
[/code]

The test class name can include a namespace prefix. Add a namespace prefix if your organization has a namespace defined or if the test class belongs to a managed package. For example, if the namespace is MyNamespace, specify the test class as MyNamespace.TestClass1.

If you don’t specify a test class to run in the target, the default deployment behavior applies when deploying to production. The default is all tests in your organization run on deployment except the tests that originate from installed managed packages. The default code coverage requirements are also enforced. The requirements are a minimum overall percentage of 75% for all classes and triggers, and no trigger can have 0% coverage.

Run the Same Tests in Sandbox and Production Deployments

Starting in API version 34.0, you can choose which tests to run in your development environment, such as only local tests, to match the tests run in production. In earlier versions, if you enabled tests in your sandbox deployment, you couldn’t exclude managed package tests.

By default, no tests are run in a deployment to a non-production organization, such as a sandbox or a Developer Edition organization. To specify tests to run in your development environment, set a testLevel deployment option. For example, to run local tests in a deployment and to exclude managed package tests, add the testLevel=”RunLocalTests” parameter to the deploy target as shown in this example.

[code language=”HTML”]

<target name=”deployCode”>
<sf:deploy username=”${sf.username}” password=”${sf.password}” sessionId=”${sf.sessionId}” serverurl=”${sf.serverurl}” deployroot=”codepkg” testLevel=”RunLocalTests”></sf:deploy>
</target>

[/code]

Cancelling a Deployment

You can cancel a deployment that’s in progress or queued with the <sf:cancelDeploy> task.

[code language=”HTML”]

<target name=”cancel”>
<sf:cancelDeploy username=”${sf.username}” password=”${sf.password}” sessionId=”${sf.sessionId}” serverurl=”${sf.serverurl}” maxPoll=”${sf.maxPoll}
requestId=”${sf.deployRequestId}”/>
</target>
[/code]

Common Migration Issues

There are a number of common issues you may run into when migrating metadata and deploying changes. These issues can be grouped into three categories:

• Metadata — Special considerations for dealing with certain metadata components
• Connectivity — Problems connecting to an organization or polling for results
• Testing and Code Coverage — Testing Apex before deployment

For more information Migration Issues

https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/commondeploymentissues.html