Salesforce.com Ant Migration Tool

Ant: Your Configuration Migration Tool for Salesforce

Ant (Another Neat Tool) is a Java tool that performs tasks based on XML instructions. It serves as a great configuration migration tool for Salesforce. You give it an XML configuration file with the details of the possible tasks to perform. Then tell it the task you’d like to run. Tasks can be made dependent on each other based on XML properties.

The main file containing all the possible tasks to perform is an xml file named build.xml. It will contain tasks that we might want Ant to perform for our project, in a specific format.

When you give Ant a command, it will read the build.xml configuration file. It searches for the target matching that name and once it finds it, it will execute it. You can look at the XML in the build.xml as basically a Domain-Specific Language (DSL).

The Salesforce Ant Migration Tool is an Ant extension (antlib) that adds Salesforce-specific tasks to Ant. When you add the extension, Ant cn understand additional commands that refer to actions performed against a Salesforce environment. This is a crucial step in your Salesforce migration.

Once you have the Ant Migration Tool installed you can use it to do things like deploying your code to a Salesforce org and running all tests. It’s faster than if you try to do it from the Force.com IDE. You can also run the tool from the command line, which makes it perfect for integrating it with other systems.

In this article, we will share how to use Salesforce’s Ant Migration Tool from the Force.com IDE. We’ll also demonstrate how to integrate it with Jenkins for Continuous Integration in a Team Development Environment.

Configuration of the Migration Tool in Salesforce

First of all, you need the Salesforce antlib. This is just a jar file that you have to place in Ant’s library folder.

After installing Java and Ant, follow these steps to start using the Ant Migration tool:

1. Download the Migration Tool from your org (any org): Go to Your Name > Setup > Develop > Tools
2. Click the “Force.com Migration Tool” link to download a zip file. Inside this zip file, you can find the ant-salesforce.jar file and some sample configuration files.
3. Install the Ant Migration Tool:
   1. If you want to run it from the command line: copy the ant-salesforce.jar file from the unzipped file into the ant lib directory (usually /usr/share/ant/lib)
   2. If you want to run it from IDE (as below): Go to Force.com IDE Preferences > Ant > Runtime > Ant Home Entries > Add external Jar > select the ant-salesforce.jar you just downloaded
4. Now you have to set up the Ant configuration. You can either create your build.xml and build.properties from scratch, or you can use the examples provided. You could actually hardcode the org credentials directly into build.xml and not have a build.properties file, but it’s a best practice to keep them separate. Let’s keep them separate then, and use the examples provided to start:
   1. Import the files build.properties (this is where you will put your connection information) and build.xml (this file will contain your custom Ant tasks) into the project (right-click > Import > General > File System)
5. Enter your Dev Org credentials in build.properties (don’t forget to append the security token to the password)
6. In build.xml search for “deployCode” and change deployRoot=”codepkg” to deployRoot=”src”
7. Optionally, search for “retrieveCode” and change retrieveTarget=”codepkg” unpackaged=”codepkg/package.xml” to retrieveTarget=”src” unpackaged=”src/package.xml”

Renaming Targets

You can also rename the targets, if you’d like. I’m going to rename mine deployCodeToPackaging and undeployCodeFromPackaging, because I’m going to use the migration tool to deploy to more than one environment (more details below).

That’s it, you are all set now for your Salesforce migration. Your configuration files should look something similar to this:

build.properties

build.xml

(*I have a few more targets than deployCode and undeployCode just because I’m using the migration tool to deploy to different environments, and I’m also doing a few more things with it. But those would be the basic ones. You can always customize and extend at will.)

How to Use it From Eclipse

1. Click on Window > Show View > Other > Ant
2. From the Ant view in the IDE click on “Add build files” (the Ant with a plus sign on the top icon) and select the build.xml from your project
3. From the Ant view select the task to run, for example, “deployCodeToPackaging”, and click the arrow on the green circle icon to execute it

*The task in blue is the default one, which will be run by Ant if you do not specify any when running it. It is mandatory to declare a default task in the build.xml configuration.

How to Use it From Jenkins – Role in CI

You can, for example, use the Ant Migration Tool to automatically deploy to your test environment and run all tests there using a Continuous Integration (CI) server. This is process for a Salesforce migration is commonly done on a Team Development setting. To do that, you need to drop the ant-salesforce.jar file in the Ant library folder in the machine where the Continuous Integration server is running, as described in step 3.a. Java and Ant need to already be installed in that machine, and Ant needs to be made accessible to the CI server.

Let’s say that you are using Jenkins, and that you have a task named deployCodeToPackaging configured in your build.xml file. To run this task after your code has checked out, you need to add an Invoke Ant build step in the configuration for your project, and give it a deployCodeToPackaging target:

Testing to Prepare for Your Salesforce Migration

Now Ant will run that Salesforce-specific target after your code has been checked out by the CI server. You can use it to deploy to your test org and run all tests to prepare for your Salesforce migration. If the deployment fails the build will fail, and you can configure Jenkins to alert your team by email. You can also configure the build to fail if any of the tests do not pass. Just set the runAllTests parameter equal to true for the specified target in the configuration file.

The Ant Migration Tool is a very versatile tool, based on proven technologies (Java & Ant). These can significantly help, especially if you plan to automate your deployment process in the context of Continuous Integration. It is also easy to use and easy to configure, especially if you are already familiar with Ant. If you are not, the learning curve is gentle, thanks to examples from Salesforce and posts like this one.

Start Your Salesforce Migration

If you find yourself needing assistance, feel free to contact our team of Salesforce and architects developers. We’ve helped dozens of clients move to the platform. We can help you plan and execute on a streamlined and flawless process. We leverage tools like Ant, this configuration migration tool for Salesforce to launch custom platform implementations. Talk to a consultant to get started.