Salesforce Migration Migration Tools

The Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce organization. The migration tool is useful for migrating large scale or repetitive changes between environments.

Migration tools scenarios

  • Development projects where we need to populate a test environment with large amounts of setup changes—making changes with an automated script is far faster than entering them by hand.
  • Deployments where we need to change the contents of files between organizations.
  • Multi-stage release processes—a typical development process requires iterative building, testing, and staging before releasing to a production environment. We can retrieve metadata from the source environment, make changes, and deploy our changes to the destination environment. If we need to repeat this process, it is as simple as calling the same deployment target again.


Prerequisites for using Migration Tool:

Before using Migration Tool, Java and Ant must be installed correctly.


Installing Java: In a Web browser, navigate to and install the latest version of the Java JDK.

Verify Java Installation: To see if we have Java installed: In the command prompt, type java -version and press Enter. The output should look something like the following:

java version "1.5.0_01" Java(TM) SE Runtime Environment (build 1.5.0_01-b06) Java HotSpot(TM) Client VM (build 1.5.0_01-b06, mixed mode)

Ant Installation: Download Apache Ant . This directory will be known as ANT_HOME.  Add the bin directory to your path. (Only the bin and lib directories are required to run Ant.) If we are using a Windows operation system, create an ANT_HOME environment variable and set the value to where we have installed Ant. Also create a JAVA_HOME environment variable and set the value to the location of your JDK.

Verify Ant Installation

  • %In the command prompt, type 2+ and press Enter.
  • The output should look something like the following:
  • Apache Ant version 1.8.2 compiled on December 13 2006

Installing the Migration Tool: 

To download and install the Migration Tool:

  • Log into a Salesforce organization on your deployment machine. Click  and then click % .
  • Save the .zip file locally and extract the contents to the directory of your choice.
  • Copy ant-salesforce.jar and paste into your Ant installation's lib directory. The lib directory is located in the root folder of your Ant installation.
  • Go to control panel and click on System In System properties window, go to Advanced tab and click on Environment variables.

Create the following two environment variables if they are not existing.

  • ANT_HOME – value is (your apache-ant-1.8.2 installed path)
  • JAVA_HOME – value is (your jre1.6.0_02 installed path)


GeneralSteps The general procedure we will follow when using the Migration Tool to copy metadata from one Salesforce organization to another is:

  • Enter credentials and connection information for source Salesforce organization in
  • Create retrieve targets in build.xml
  • Construct a project manifest in package.xml
  • Run the Migration Tool to retrieve metadata files from Salesforce
  • Enter credentials and connection information for destination Salesforce organization in
  • Run the Migration Tool to deploy metadata files or deletions to Salesforce Fetching Data

Inclined to build a profession as SalesForce Developer? Then here is the blog post on, explore SalesForce Training

To fetch the data from the source environment Create a folder say some “Migration folder” and create the following in it.

  • build.xml
  • Create a new folder with the name says “retrieve source”.
  • In the retrieved source folder, create an XML file with the name “package.xml”. file should look like this Give user id, password, server URL like below username = user@gehc.amer.sprintdev

password = password12jSZQVS7erefdUMfjcoFSgr7Mqx server URL =

Build.xml file should have the following

<!--Retrieve the contents from the source environment-->

<target name="retrieve">

<mkdir dir="retrieveMetadata"/>

<setproxy proxyport="80" proxyHost = your proxy proxyuser =

'username' proxypassword = 'password' />

<sf:retrieve username="${sf.username}" password="${sf.password}"

serverurl="${sf.serverurl}" retrieveTarget="retrieveMetadata"

unpackaged="retrieveSource/package.xml" pollWaitMillis="10000"



<!-- Deploy the changes into destination environment -->

<target name="deploy">

<setproxy proxyport="80" proxyHost = your proxy proxyuser =

'username' proxypassword = 'password' />

<sf:deploy username="${sf.username}" password="${sf.password}"

serverurl="${sf.serverurl}" deployRoot="retrieveMetadata" />


<!-- Delete the changes made to the description environment-->

<target name="remove">

<setproxy proxyport="80" proxyHost = your proxy proxyuser =

'username' proxypassword = 'password' />

<sf:deploy username="${sf.username}" password="${sf.password}"

serverurl="${sf.serverurl}" deployRoot="remove" />


Finally, the build.xml file should look like below.


3)Package.xml file should contain all the metadata information like objects, classes, triggers etc that needs to be migrated or retrieved. In the source environment, just create a new field or class or trigger to verify the migration is successfully taken place in the destination environment. In the below example, the following are created in the source environment

  • MigrationTest_Field --- a text field in the account object
  • MigrationTestClass --- a new class
  • Top_X_Designation__c --- custom object

Keep all the data that needs to be retrieved from source environment in <types> like this.





To retrieve all the triggers or classes, put *. Like this





Finally, the package.xml file should look like this


We need to go to the command prompt and type the commands to do the following

  • Retrieve – to retrieve the data from the source environment
  • Deploy – to deploy the data into the destination environment

Go to folder directory in the command prompt where the “Migration folder” is created. Type the following command Type the command[ +$to fetch the data from the source environment into the folder. After executing the above command, the below details are visible in the command prompt.

 Learn SalesforceOnline With Free Tutorials

Go to the source folder and verify whether all the data mentioned in the package.xml is fetched from the source environment. We will find a folder called retrieve Metadata that contains all the retrieved data from the source environment. Now, give the credentials of the destination environment in the file. And type the following command. Deploying Data

To deploy the data into the destination environment

Type “Ant deploy” in the command prompt Now after the files are deployed, we will get the following info in the command prompt. migration

Now go to the UI and check whether all the files are migrated to the destination environment. With this example, we can see all the above-provided data will be migrated and available in the destination environment.

Integrating with Subversion

Using the Subclipse IDE we can log in to SVN repository and checkout the branch which we have latest code and metadata into a local directory. As mentioned in the Fetching data section we can run deploy command to deploy the contents which are mentioned in the package.xml will get deployed to the destination environment.


For in-depth understanding on Salesforce click on