Part 1: An Introduction to the Salesforce Migration Tools



Before we look at how we can take advantage of the tools and techniques discussed in the Dreamforce session, there are some basics that need to be covered.  The first and most important tool that needs to be used and understood is the Migration Tool.  This blog post will give a very brief tutorial to get you started with this tool and its main applications.  If you have used the Migration Tools before and have the tools configured and working you can skip this blog post and move on to Part 2 – Preparing Developer Orgs (when it is published).


Firstly we need to make sure that you have the requirements for using the Migration Tools, please ensure you have the following:

Once you have all of the above you can proceed to setting up and using the Migration Tools.

Although any recent version of the Migration Tools should be suitable for this tutorial, it should be noted that the version of the Migration Tools we are using for the tutorial is 32.0.  There may be slight differences between different version that should be covered in the documentation provided by Salesforce.

Retrieve Content from an Org

The Salesforce Migration Tool can be used to retrieve source code and metadata from an org in simple file formats.  The metadata is typically retrieved in files containing XML.  The content can be retrieved by following the steps below.

  1. Create a directory where you want keep the files related to this tutorial.  I am going to refer to this as the project directory from now on.

  2. Create another directory called lib in your project directory.

  3. Download the Salesforce jar into the lib directory:

    • Login to your Salesforce developer org

    • Click "Setup" on the top right of the page

    • In the text input field "Search All Setup…" type tools and you should see the following:Migration_Tools_link

    • Click " Migration Tool" link and it will download a zip file.

    • Extract the file called ant-salesforce.jar from the zip file and put it in the lib directory

  4. Use your text editor to create a new file called in your project directory with the following content (replace the <<tokens>> with your username and password, if you have not previously added your IP address to the Network Access for your org you should append the Security Token to your password):

  5. Create a directory called src and within this directory create a file called package.xml with the following content:
  6. Create another file called build.xml in the project directory with the following content: 

  7. Navigate to your project directory in a terminal or command prompt and run the command ant retrieve

  8. When the script has completed it should give the message BUILD SUCCESSFUL if everything worked correctly.  If you look in the src directory you should see there is a new directory called objects and within this there is a file called Opporunity.object.  This is the content that was retrieved from the org by the Migration Tool.  In this case we specified in the package.xml file that we wanted to retrieve the custom field with API name Opportunity.OrderNumber__c and we can see the metadata for this field in the file Opportunity.object.  The Order_Number__c field is a custom field that Salesforce includes in all new developer orgs for sample purposes.  The metadata for the field looks like:

  9. You can play with the package.xml file to retrieve other types of metadata as almost all Salesforce org content be retrieve using this approach with different package.xml configurations

Deploying (Adding / Updating) Content to an Org

You can modify or update the source code or metadata in your developer org with the Migration Tools.  The settings in your local metadata files will be applied to your org when you deploy the content using the tool.  The following instructions illustrate how to update the label on a custom field.  The process works by creating a zip file, containing your metadata files and the the package.xml corresponding to the files to update / add, which is then deployed to your Salesforce developer org.

  1. Use your editor to modify the Opportunity.object file you retrieved in the previous steps and modify the label value, for example:

  2. Now we need to update our build.xml file to add a target to deploy the content to the org.  Add the following to your build.xml immediately after the retrieve target:

  3. From your terminal or command prompt run ant deploy

  4. Now if you login to you Salesforce org and Navigate to the Opportunity fields from Setup you will see the field label has been updated:deployed_field_name

  5. Again you can play with the metadata files and the package.xml to update or add the content in your developer org

Undeploying (Deleting) Content from an Org

Warning: These steps will permanently delete content from your developer org.  Please proceed with caution and we strongly recommend these steps are done in a developer org created solely for this tutorial.  This tutorial is only intended as a guide and we can accept no responsibility any loss of code, metadata or data.

In addition to retrieving, updating and adding content to your developer org you can also delete content (at The TAS Group we refer to this as undeploying rather than deleting so I may alternate between both terms in the blog).  Deleting content is similar to the process for deploying but instead of deploying a zip file with metadata files and a package.xml, the zip file that is deployed contains an empty package.xml and a file called destructiveChanges.xml that is the same format as the package.xml used to retrieve content but everything specified in the file will be deleted permanently.  Please note that the examples provided here perform a "hard delete" and do not put items in the recycle bin, the items are deleted permanently and cannot be retrieved from the recycle bin.

  1. Add a new target to your build.xml:

  2. Create a new directory called undeploy in your project directory

  3. In the undeploy directory create a new file called package.xml with the following xml:

  4. Then create a new file called destructiveChanges.xml in the undeploy directory with the the content below (please note that in this example we are going to the custom field Order_Number__c on the Opportunity object):

  5. From the terminal or command prompt run the command ant undeploy

  6. Now if you check in the saleforce developer org you will see the field is gone.



By now you should be familiar with the basics of how to retrieve, deploy and undeploy content from a Salesforce developer org.   These functions are basis for all the Salesforce processes we will discuss in the future blog posts so it is worth while becoming very familiar with the Migration Tool and becoming comfortable using different functions.  In part 2 we will look at how to configure a developer org so that it can be easily used with all the tools and techniques we use 


Comments 4

  1. kamal 08/13/2016
  2. Sathya 10/05/2016
  3. Patrick 11/09/2016

Leave a Reply