Home » Development » Salesforce Ant Migration Tool Tutorial

Salesforce Ant Migration Tool Tutorial

I recently used the Ant Migration Tool for deployment and loved it compared to the slow Change Sets. The Ant Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce org. You can use it to deploy from any org to any other org, related or not, and it’s way faster than Change Sets.

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

If you don’t have Java JDK installed, follow these steps:

         

  • Click on JDK and note the installation path during the installation. My path was C:\Program Files\Java\jdk1.8.0_201
  • After installing JDK, verify the version by typing this command: java -version

If you don’t have Ant installed, follow these steps:

     

  • Extract the downloaded Zip to a directory that will be used as the Ant home. I extracted the Zip to D:\ANT_HOME

After installing both JDK and Ant, make sure you have these Environment Variables set: 

  • Add ANT_HOME and JAVA_HOME variables::
  • Right-click “This PC” – Properties – Advanced System Setting
  • Click Environment Variables

         

  • Add 2 new Variables called ANT_HOME pointing to your Ant installation folder D:\ANT_HOME, and JAVA_HOME pointing to the JDK installation folder C:\Program Files\Java\jdk1.8.0_201. Also, add these 2 folders to the Path variables as shown in the second screenshot.

        

It’s time to install the Ant Migration Tool itself:

           

  • And the sample Folder contains: 

          

  • The files build.properties and build.xml are 2 critical files. We will see about these in a while.

Let’s prepare the Ant Migration Tool!

  • To start using the Ant Migration Tool, we should first decide about the Source org, which will be used to get the metadata from, and the Destination org, which will be used to deploy the metadata to, from the Source org. 
  • The Source / Destination orgs can be of any edition (Developer, Production, Sandbox…), and they can indeed be not related at all 
  • Once you know the Source org, go to this tool https://packagebuilder.herokuapp.com/ to retrieve the manifest file package.xml. This file is an XML file that defines the metadata of the org. 
  • Specify the org type (Production or Sandbox), then click on LOGIN TO SALESFORCE WITH OAUTH, then enter your username and password.
  • In my case, the Source org is a Developer org with this username below: 

  • Click on Allow access to give access to the Package Builder tool for it to get the Metadata manifest package.xml file
  • Now choose the components you want, in my case, I will get all the components, excluding the managed ones, Then click on GET COMPONENTS 

  • Once you have the xml file displayed in the browser, select all its content, and copy it… then save it in a file named package.xml. If I can’t save an xml file directly from the browser, I save it as a txt file, then rename it using the “ren” windows command: ren package.xml.txt package.xml. This will rename the file from a txt extension to an xml one. 
  • Open the package.xml file using your preferred editor (I use VS Code to open my xml files), and go through it. You will notice that it is simply an XML file that contains tags corresponding to the different metadata components, just like when you choose components in a Change Set, but this is actually much faster! There is UI, and no need to wait 10 mins for the page to load!
  • The type of the component is inside the name tag, for example
    CustomApplication represents the list of all custom Apps components. MatchingRule represents the list of all Matching Rules components. You can choose to exclude all of the components of type MatchingRule by deleting the whole tag between <type>…</type> , including the corresponding opening and closing tags<type> and </type>. Also, you can delete individual components by deleting members tags instead and keeping the type and the name tags.

Here is the MatchingRule set of components between the <types> tag:

<types>
    <members>Account.Standard_Account_Match_Rule_v1_0</members>
    <members>Contact.Standard_Contact_Match_Rule_v1_1</members>
    <members>Lead.Standard_Lead_Match_Rule_v1_0</members>
    <name>MatchingRule</name>
</types>

  • Now, specify what metadata you want to keep – for example, in my case, I just want to deploy a custom App with its related metadata.
  • So, here is my final package.xml file that only includes what  I want to retrieve

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>CourseRegistrationHelper</members>
        <members>CourseRegistrationHelperTest</members>
        <members>CourseRegistrationTriggerHandler</members>
        <members>FlowClass</members>
        <members>FlowClassTest</members>
        <members>StudentHandler</members>
        <members>StudentHelper</members>
        <members>StudentHelperTest</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>CourseRegistrationTrigger</members>
        <members>StudentTrigger</members>
        <name>ApexTrigger</name>
    </types>
    <types>
        <members>LOGO</members>
        <name>ContentAsset</name>
    </types>
    <types>
        <members>College_Cloud</members>
        <name>CustomApplication</name>
    </types>
    <types>
        <members>Building__c.Description__c</members>
        <members>Classroom__c.Building__c</members>
        <members>Contact.Languages__c</members>
        <members>Contact.Level__c</members>
        <members>Course_Registration__c.Course__c</members>
        <members>Course_Registration__c.Student__c</members>
        <members>Course__c.Classroom__c</members>
        <members>Course__c.Name__c</members>
        <members>Course__c.Number_of_Students__c</members>
        <members>Student__c.Active__c</members>
        <members>Student__c.Date_of_Birth__c</members>
        <members>Student__c.Email__c</members>
        <members>Student__c.First_Last_Email__c</members>
        <members>Student__c.First_Name__c</members>
        <members>Student__c.Gender__c</members>
        <members>Student__c.Last_Name__c</members>
        <members>Student__c.Mailing_City__c</members>
        <members>Student__c.Mailing_Country__c</members>
        <members>Student__c.Mailing_Postal_Code__c</members>
        <members>Student__c.Mailing_Province__c</members>
        <members>Student__c.Mailing_Street_2__c</members>
        <members>Student__c.Mailing_Street__c</members>
        <members>Student__c.Phone__c</members>
        <members>Student__c.Summary__c</members>
        <name>CustomField</name>
    </types>
    <types>
        <members>Building__c</members>
        <members>Classroom__c</members>
        <members>Course_Registration__c</members>
        <members>Course__c</members>
        <members>Student__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>Building__c</members>
        <members>Classroom__c</members>
        <members>Course_Registration__c</members>
        <members>Course__c</members>
        <members>Student__c</members>
        <name>CustomTab</name>
    </types>
    <types>
        <members>College_Cloud_UtilityBar</members>
        <name>FlexiPage</name>
    </types>
    <types>
        <members>Building_Flow_calling_Apex_Class-1</members>
        <members>Building_Flow_calling_Apex_Class-2</members>
        <members>Building_Flow_calling_Apex_Class-3</members>
        <name>Flow</name>
    </types>
    <types>
        <members>Building_Flow_calling_Apex_Class</members>
        <name>FlowDefinition</name>
    </types>
    <types>
        <members>Building__c-Building Layout</members>
        <members>Classroom__c-Classroom Layout</members>
        <members>Course_Registration__c-Course Registration Layout</members>
        <members>Course__c-Course Layout</members>
        <members>Student__c-Student Layout</members>
        <name>Layout</name>
    </types>
    <types>
        <members>Building__c.All</members>
        <members>Classroom__c.All</members>
        <members>Course_Registration__c.All</members>
        <members>Course__c.All</members>
        <members>Student__c.All</members>
        <name>ListView</name>
    </types>
    <types>
        <members>Building__c.Flow_calling_Apes</members>
        <name>QuickAction</name>
    </types>
    <version>43.0</version>
</Package>

  • Create a folder that clearly specifies the project in the D:\AND_MIG_Tool folder. In my case, I created a folder called PD2__Shark. This folder will be used to retrieve metadata from the PD2 org, and deploy to another org called Shark – which is a Trailhead Playground org 😀  
  • Inside this Folder, create another Folder called codepkg
  • Copy the package.xml file in this folder D:\ANT_MIG_Tool\PD2__Shark\codepkg
  • Copy the 2 files build.properties and build.xml from the sample Folder to the Folder D:\ANT_MIG_Tool\PD2__Shark. We will rely on when retrieving and deploying the metadata
  • Open the build.properties file, and replace as per the below:
  • sf.username is the username of the Source org, sf.password is the password followed by the Token, and sf.serverurl depends on whether the Source is a Production (or Developer) edition or a Sandbox. 

Let’s use the Ant Migration Tool!

  • Now, everything is set to retrieve the actual metadata from the source org:
    • package.xml is ready
    • build.properties is modified with the source org credentials 
    • The folder structure is built
  • Open Command Prompt, and go to the project folder D:\ANT_MIG_Tool\PD2__Shark
  • Issue the command

ant retrieveCode

 

 

  • This will fetch the metadata from the source org, and add  them to the folder D:\ANT_MIG_Tool\PD2__Shark\codepkg
  • Now, to deploy this metadata to the Destination org, we need to change the credentials in the build.properties file. We need to replace the username / password+token and server URL with the right Destination values
  • Issue the command: ant deployCodeCheckOnly

 

ant deployCodeCheckOnly

 

  • This will Validate the deployment without actually deploying it on the Destination org. Just like your standard Change Set validation. In fact, you can see the validation result on the Destination org as well on the Command Prompt 
  • Finally, to deploy the components, we will issue the command: 

 

ant deployCode

 

Here is a list of all commands that can be used with Ant:

Command Description
ant bulkRetrieve
Retrieve all the items of a particular metadata type
ant retrieveUnpackaged
Retrieve an unpackaged set of metadata from your org
ant retrievePkg
Retrieve metadata for all the packages specified under packageNames
ant deployUnpackaged
Deploy the unpackaged set of metadata retrieved with retrieveUnpackaged and run tests in this organization’s namespace only
ant deployZip
Deploy a zip of metadata files to the org
ant deployCode
Upload the contents of the “codepkg” directory, running the tests for just 1 class
ant deployCodeNoTestLevelSpecified
Shows deploying code with no TestLevel sepcified
ant deployCodeRunLocalTests
Shows deploying code and running tests only within the org namespace
ant undeployCode
Shows removing code
ant retrieveCode
Retrieve the contents listed in the file codepkg/package.xml into the codepkg directory
ant deployCodeCheckOnly
Shows check only; never actually saves to the server
ant quickDeploy
Shows quick deployment of recent validation.
ant cancelDeploy
Shows cancel deployment of deploy request either pending or in progress
ant listMetadata
Retrieve the information of all items of a particular metadata type
ant describeMetadata
Retrieve the information on all supported metadata type

 

Finally, here is the Ant Migration Tool implementation Guide from Salesforce. 

https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/meta_development.htm

 

Cheers!

Walid


3 Comments

Leave a comment

Your email address will not be published.