Migration tool to deploy meta data between Organizations

Migration tool is used to deploy the Metadata from one organization to other organization. By using this tool first we will get the code to our local from source organization and we will deploy from local to target instance. It is very easy process to deploy the large number of components from source to target instance.

Force.com migration tool is a java/Ant based command line utility for moving the Meta data between local directory and a Salesforce organization. The Force.com Migration Tool is especially useful in the following scenarios:

  1. Development projects where you need to populate a test environment with large amounts of setup changes — making these changes using a Web interface could take a long time.
  2. Multistage release processes — a typical development process requires iterative building, testing, and staging before releasing to a production environment. Scripted retrieval and deployment of components can make this process much more efficient.
  3. Repetitive deployment using the same parameters — you can retrieve all the metadata in your organization, make changes, and deploy a subset of components. If you need to repeat this process, it’s as simple as calling the same deployment target again.
  4. When migrating from stage to production is done by IT — anyone that prefers deploying in a scripting environment will find the Force.com Migration Tool a familiar process.

Installing Force.com migration tool

  • Install Java on your local machine

Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html. And get the latest version of the Java JDK and install it on your machine.

  • Install ANT in your local machine.

Go to http://ant.apache.org/bindownload.cgi and get these files to your local. Once these files are on your computer, there is no further installation required.

  • After installation of java and ANT, create following environment variable to set the path.
Variable NamePath
ANT_HOMEHere give Ant location on your machine. For example in my machine I have stored ant in “C:\Ant\apache-ant-1.8.4” location
PathC:\Program Files\Java\jdk1.6.0\bin;%ANT_HOME%\bin

If you are working under proxy network you need to create one more additional environmental variable to specify proxy settings.

  •  Download Salesforce.jar file and add that file to your ant installation’s lib directory.

To download this Go to setup->Develop-> click on Tools -> and click on Force.com migration tool to download this. Refer following screen.

Migration tool

After downloading extract the downloaded ZIP file and copy the ant-salesforce.jar file and paste it in Ant lib directory in your ant installation file.

  • Now Force.com migration tool installation is completed.

To verify java installation open command prompt ant type “Java –version” you will get the following message based on the java version. 

java version “1.6.0_37”

Java(TM) SE Runtime Environment (build 1.6.0_37-b06)

Java HotSpot(TM) Client VM (build 20.12-b01, mixed mode, sharing)

To verify ANT installation type ant –version in command prompt, you will get following message based on the ANT version.

Apache Ant(TM) version 1.9.1 compiled on May 15 2013

How to use Migration tool to deploy components in Salesforce?

To deploy metadata by using this migration tool we need prepare below mentioned three important files.

  • Build.properties file: This file contains your organization’s credentials in order to run the tasks in build.xml file.

Parameters used in build.properties file

usernameHere you need to mention your organization user name like below users.For example testuser@tut.com  in production, testuser@tut.com.devbox in sandboxThis users must have “modify all data” permission to deploy components.
passwordYou have to specify your password along with security token(Password + Security token)
serverurlFor production it is https://login.salesforce.comFor sandbox it is https://test.salesforce.com 
  •  Build.xml file: This file specifies a series of commands to be executed by Ant. Within the build.xml file are named targets that process a series of commands when you run Ant with a target name. below image describes sample build.xml


  • Package.xml: This 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. Below image describes sample package.xml file

migration tool - Package.xml

You can get these sample(build.xml and build.properties) files from migration tool zip file downloaded earlier as part of installation.

After creating these three files Place these files in a folder, place package.xml file in separate folder inside this folder, see the following image for reference.

Migration tool

Place the package.xml file in codepkg folder.

Once you have done with this setup, you can run this script in Command prompt.

How to run this script in command prompt

  • Open command prompt and enter file path of your build.xml file.

For example I have placed my build.xml file in “C:\Build”. Enter this command in command prompt “cd C:\Build”.

  • Now retrieve the code your local from source organization. To retrieve the components mentioned in your package.xml run the command “ant retrieveCode” which is mentioned in your build.xml.
  • Once you have done with retrieving components to your local, now you can deploy those components to your target organization. To deploy your components run the command “ant deployCode”, which is mentioned in your build.xml file.

If your deployment is success, you will get a successful message. In case of failure you will get the list of errors.

How to run specified tests during Salesforce cloud deployment

Quick deployment in Salesforce