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
> 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
> 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 -versionant -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 retrieveSalesforce 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>
<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>
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
- You should have set environment variables.
- You should have prepared package.xml file.
- You should have defined credentials to source org in build.properties file.
- 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 actionNamemyProject – 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
- https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/meta_development.htm
- https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_types_list.htm
- https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy.htm
- https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_deploying_ant_retrieveCode.htm
Was it helpful? Check out our other great articles here.
