What is Ant Migration and what is the use?
The Ant Migration Tool is Java/Ant based command-line utility for moving metadata between the different org and directory
Ant migration is especially useful for
- For multiple setup changes
- For the multistage release process
- For repetitive deployment process
- Deploying with the scripting environment
- For scheduling batched deployments
Salesforce Metadata API
The purpose of this metadata API is during the deployment time it will transfer the metadata between the Salesforce org. It’s used to assist developers in Retrieve, creating, deploying, updating, or deleting customization in information
In this below link, they list the different metadata types that are accessible via Metadata API
Metadata API does not work directly with business data. It does however work through REST/SOAP API where we can create, retrieve, update, or delete records.
Installing the Ant Migration Tool
Before installing the ant migration tool first we have to install Java and Ant in our system.
Java
Java 1.7.x version or later version
If you already installed check the Java version using Java -version command
If not install the Java LTS version go to this link and download and install the Java in your system.
Apache ANT
You should install the Apache ANT. Go to the link below and download the latest version of the ANT.
You can refer to the YouTube video if you’re having trouble with installing Ant in your system.
https://www.youtube.com/watch?v=3eaW81yYIqY&ab_channel=xscourse
You can verify whether Ant has been successfully installed in your system by typing the following command in the CMD.
Ant -version
Note – Don’t forget to set the both(Java & ANT) environment variable in your system
Install the Ant Migration Tool
For the next step, we need to download the Salesforce Migration Tool. It’s available in the Salesforce org. Follow the steps mentioned below to download the tool.
Steps
- Login to your Salesforce org
- In the Quick find type Tools
- Select the Lightning Platform Tools and Tool Kits
- Go and click ANT Migration Tool it will help you to download the latest version.
- Extract and save in any Local Drive
Note – Ant Migration Tool version 51.0 and later requires Java version 11 or later.
After that Go to Salesforce Ant 50 folder then copy the ant-salesforce file and paste it inside the Apache ant folder ➔ lib folder
Salesforce Ant 50 folder
Apache Ant folder
Up to now, we have configured the connectivity between Apache Ant with Salesforce Migration Tool.
The next step is to configure the files to get our environment for migration. For that go to the Salesforce Ant Migration folder ➔ sample folder Inside this, There are two files that are important to us.
- Build. properties – it is the properties of the Salesforce org.
- Build.xml – includes all the migration command methods.
In the build.properties we will provide the login credentials for the desired Salesforce org.
sf.username = [YOUR USERNAME]
sf.password = [YOUR PASSWORD]
If you use any security token enter that at the end of the password.
Next is build.xml – this file contains the information of the build. properties. Here you can see them inside the property tag.
Build. properties will send the credential to build.xml.
Next, let’s see how to retrieve the data from the Salesforce org.
Go to package.xml it’s in the sample ➔ codepkg. Basically, this file tells which function needs to be called and what to do.
My first objective is to retrieve all the apex classes and deploy one apex class
The first step is to go to the package.xml file. Here you can define what data we are going to retrieve from this org.
In this case, I’m going to retrieve all the apex classes. This * means all the apex classes. If you want to retrieve any specific apex classes then we can add them inside the <members> tag
Now open a command prompt and navigate to the sample folder directory and type this below command
Ant retriveCode
Before going to execute this command Let me explain a little bit here
basically this retrieveCode is a function. Defined inside the build.xml file
<target name=”retrieveCode”><sf:retrieve username=”${sf.username}” password=”${sf.password}” sessionId=”${sf.sessionId}” serverurl=”${sf.serverurl}” maxPoll=”${sf.maxPoll}” retrieveTarget=”codepkg” unpackaged=”codepkg/package.xml”/></target>
retrieveCode used call to retrieve apex classes and triggers from the org
The target folder is codepkg. For more details check below image.
Now execute the below command In the CMD
Ant retriveCode
After the process is completed, You can see all the apex classes inside the codepkg > classes
Next, if you want to deploy this data to another org. Again come to your build.xml file and update the target Salesforce org credentials.
after that navigate package.xml file in here define your expected classes for the deployment. In this demo, I’m going to deploy only one Apex class called “BlogDemoClass”
<types> <members>BlogDemoClass</members> <name>ApexClass</name> </types>
In this case, I am going to deploy this class without any test class so we have to use the deployCodeNoTestSpecified.
Open command prompt Navigate to sample folder directory after that type below command
Ant deployCodeNoTestSpecified
After the execution is completed successfully go to your target salesforce org and check the Apex classes it will be deployed successfully.
If you want to check the deployment status
Quick find > Deployment Status
In other cases, if you want to deploy the data with test classes then choose the “ deployCode ” method and add your test classes inside the <runTest> tag.
In here if you want to only validate then you have to add another parameter checkOnly=” true” inside the sf: deploy tag
For Deleting or Undeploying changes
First, we have to prepare the destructiveChanges.xml file.
For that navigate to sample > removecodepkg > destructiveChanges.xml. In there we have to include which are the components we need to un deploy.
To execute this process we are using “Ant undeployCode”.
This undeployCode is in the build.xml file.
Likewise, we can do the migration from one Salesforce org to another org.
Conclusion
The Ant migration tool is a free tool and a Java/Ant-based command-line utility that is provided by Salesforce. This tool defines that all interactions that take place within it are managed via the Command Line Interface (CLI). By now you should be familiar with the basics of how to retrieve, deploy and un deploy content from a Salesforce developer org.
References
https://blog.bessereau.eu/assets/pdfs/salesforce_migration_guide.pdf
Author: Anand Sripathmathasan is an Associate Software Engineer – Salesforce and a Salesforce Certified Administrator at CMS. He blogs at https://medium.com/@anand_19/
