Ant Migration Tool – Full guide

What is an Ant Migration Tool?

Ant Migration is a tool provided by Salesforce. It’s used to migrating metadata between local files and Salesforce environment (org).

Ant Migration Tool can be useful in the following scenarios:

  • Quick test environment configuration
  • Retrieve and deployments of components
  • Quick and efficient changes in a few components at the same time
  • Metadata migration between many different environments
  • Metadata migration to prod environment

How to Install Ant Migration Tool?

Downloads

#1
Ant migration tool requires to download and install Java JDK.
You can click here to download Java SE Development Kit 8u221.
Please select proper operation system, accept license agreement and download.

#2
The next necessary element is an Apache Ant.
You can click here to download Apache Ant.

Configuration

> Windows Search
> Control Panel
> Advanced system settings

Find View advanced system settings

> Advanced
> Environment Variables

JAVA_HOME

> System variables section
> New
> Variable name

JAVA_HOME

> Variable value > Browse Directory… > Path to bin/java.exe (Usually C:/Program Files/Java)
> OK

This image has an empty alt attribute; its file name is 2019-03-10_12h26_16-1.png

> User variables for ….. section
> Select Path and click Edit...
> Click New
> Add

%JAVA_HOME%\bin

> OK

ANT_HOME

> Unpack apatch-ant.zip in a selected place. (recommended /documents)

> System variables section
> New
> Variable name

ANT_HOME

> Variable value > Browse Directory… > Path to bin/ant.bat) (e.g C:/Documents/appache-ant-x)
> OK

> User variables for ….. section
> Select Path and click Edit...
> Click New
> Add

%ANT_HOME%\bin

> OK

TEST

Go to Windows Search > Command Prompt.
Add code of line and click enter.

java -version
ant -version

Ready custom package – Just download!

My package contains validate, deploy and retrieve commands.
The only thing you need to do is just download it here.

Package structure:

Unpack zip file in the selected folder. (recommended /Documents)

Please update build.properties and package.xml. Detail instruction below.
After that, you should be able to use ant migration tool.

Windows Search > Command Prompt

cd Documents
cd Project
cd src
ant retrieve

Salesforce package

You can download salesforce package from here.
Unpack it in the selected folder.
Configure the package.

The whole configuration described below.

Configuration

package.xml

package.xml file contains a list of components, which we want deploy to org or retrieve from salesforce environment (org).

Partially list of components (metadata type) we can use in package.xml:

  • ApexClass
  • ApexTrigger
  • ApprovalProcess
  • AssignmentRules
  • AuraDefinitionBundle
  • CustomField
  • CustomLabels
  • CustomObject
  • Layout
  • PermissionSet

Whole list you can find here. (List on the left side)

package.xml file has a specified structure.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>Metadata Type</name>
    </types>
    <version>46.0</version>
</Package>

If you want to deploy/retrieve a new metadata type, you need to add the following line of code between <types></types> markers.

<types>
   <members>API_Name or *</members>
   <name>Metadata Type</name>
</types>

Metadata Type – is one metadata type from metadata types list.
API_Name or * – API_Name restrict components only to selected. * allows you to deploy/retrieve all metadata of selected type.

Example

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Account</members>
        <members>Case</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>MyClass__c</members>
        <members>MyClass2__c</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>*</members>
        <name>ApexTrigger</name>
    </types>
    <version>46.0</version>
</Package>

build.properties

build.properties file contains salesforce credentials and another variables which can be used in build.xml file.

Remember: sf.password should contain password and security token.

sf.username = <Insert your Salesforce username here>
sf.password = <Insert your Salesforce password here and security token>
#sf.sessionId = <Insert your Salesforce session id here.  Use this or username/password above.  Cannot use both>
#sf.pkgName = <Insert comma separated package names to be retrieved>
#sf.zipFile = <Insert path of the zipfile to be retrieved>
#sf.metadataType = <Insert metadata type name for which listMetadata or bulkRetrieve operations are to be performed>

# Use 'https://login.salesforce.com' for production or developer edition (the default if not specified).
# Use 'https://login.salesforce.com for sandbox.
sf.serverurl = https://test.salesforce.com

sf.maxPoll = 20

Example

sf.username = testUser@test.com
sf.password = testpasswordf2d34asdf346as346d453d4
sf.serverurl = https://test.salesforce.com
sf.maxPoll = 20

build.xml

build.xml contains scripts, which can be used in console. Each script has specified syntax.

<target name="actionName">
   <!-- code -->
</target>

Few most common actions:

sf:deploy with checkOnly (validation)

<target name="validate">
    <sf:deploy 
        username="${sf.username}" 
        password="${sf.password}"
        sessionId="${sf.sessionId}" 
        serverurl="${sf.serverurl}" 
        maxPoll="${sf.maxPoll}" 
        deployRoot="projectDirectory" 
        rollbackOnError="true" 
        checkOnly="true" />
</target>

sf:deploy

<target name="deploy">
     <sf:deploy 
         username="${sf.username}" 
         password="${sf.password}"
         sessionId="${sf.sessionId}" 
         serverurl="${sf.serverurl}" 
         maxPoll="${sf.maxPoll}" 
         deployRoot="projectDirectory" 
         rollbackOnError="true" />
</target>

sf:retrieve

<target name="retrieve">
    <mkdir dir="destinationFolder" />
    <sf:retrieve 
        username="${sf.username}" 
        password="${sf.password}" 
        sessionId="${sf.sessionId}" 
        serverurl="${sf.serverurl}" 
        maxPoll="${sf.maxPoll}" 
        retrieveTarget="destinationFolder"
        unpackaged="unpackaged/package.xml"
     />
</target>

Example

<project name="Sample usage of Salesforce Ant tasks" default="test" basedir="." xmlns:sf="antlib:com.salesforce">

    <property file="build.properties"/>
    <property environment="env"/>

    <condition property="sf.username" value=""> <not> <isset property="sf.username"/> </not> </condition>
    <condition property="sf.password" value=""> <not> <isset property="sf.password"/> </not> </condition>
    <condition property="sf.sessionId" value=""> <not> <isset property="sf.sessionId"/> </not> </condition>


    <taskdef resource="com/salesforce/antlib.xml" uri="antlib:com.salesforce">
        <classpath>
            <pathelement location="../ant-salesforce.jar" />        	
        </classpath>
    </taskdef>

    <target name="validate">
       <sf:deploy 
           username="${sf.username}" 
           password="${sf.password}"
           sessionId="${sf.sessionId}" 
           serverurl="${sf.serverurl}" 
           maxPoll="${sf.maxPoll}" 
           deployRoot="projectDirectory" 
           rollbackOnError="true" 
           checkOnly="true" />
   </target>

   <target name="deploy">
       <sf:deploy 
           username="${sf.username}" 
           password="${sf.password}"
           sessionId="${sf.sessionId}" 
           serverurl="${sf.serverurl}" 
           maxPoll="${sf.maxPoll}" 
           deployRoot="projectDirectory" 
           rollbackOnError="true" />
  </target>

  <target name="retrieve">    
      <mkdir dir="destinationFolder" />
      <sf:retrieve 
          username="${sf.username}" 
          password="${sf.password}" 
          sessionId="${sf.sessionId}" 
          serverurl="${sf.serverurl}" 
          maxPoll="${sf.maxPoll}" 
          retrieveTarget="destinationFolder"
          unpackaged="unpackaged/package.xml" 
     />
 </target>

Fire Ant Migration Tool

  1. You should have set environment variables.
  2. You should have prepared package.xml file.
  3. You should have defined credentials to source org in build.properties file.
  4. You should have defined ant scripts in build.xml

Open Windows Console (Windows Search > Command Prompt)

Go to the directory with package.xml, build.xml and build.properties files. (Use cd command)

e.g

cd Documents
cd myProject
cd src
ant actionName

myProject – directory with package.xml, build.xml and build.properties files.
actionName – it could be validate, deploy, retrieve or each action you defined earlier in build.xml

ant validation

ant deploy

ant retrieve

Resource

Was it helpful? Check out our other great articles here.

4.7 3 votes
Article Rating
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
Close Menu
0
Would love your thoughts, please comment.x
()
x