Force.com ANT Migration tool

-
Force.com Migration Tool (ANT) Guide

Force.com Migration Tool (ANT) Guide

Here is the simple guide to setup the Force.com Migration tool (ANT).
--> First step is to download the JAVA JDK and APACHE ANT in your machine.

Step 1:-

-> Now we go to setup the JAVA JDK in our machine. After installing the Java, it should get installed in our C drive Program Files folder.
  • Please find the screenshot for the same,
-> So, we need to observe the installed java version and 'bin' folder.
  • Then we need to setup the environment variables in our machine, for that please open My computer→ Properties→ Advanced System Settings→ Give Yes to the prompted window→ Select “Environment Variables” option
  • Here we need to create a new system variable named JAVA_HOME and its path.
  • Please copy the folder path where our Java JDK got installed and set the variable as 'JAVA_HOME=C:\Program Files\Java\jdk-11.0.1' (it's the path name in my machine)
-> Please see the screenshot for the same,

  • Then we need to set the path for this Java. For that, go to User Variables, you will definitely find the variable named “path”.
  • Edit the path variable and create a new variable by mentioning the path as '%JAVA_HOME%\bin'
-> Please check the screenshot for the same,
  •  Success, we have successfully set the Java in our machine. Now we restart our machine to confirm the changes and check whether it got installed correctly.
  • Now open the command prompt and type “java -version”, it should show you some output as shown in below screenshot.
==> Now it's time to setup Apache ANT and our Salesforce Migration tool in our machine.

Step 2:-

  • After downloading the Apache Ant ZIP file, please unzip the contents and store in any folder as per your wish. So the folder would be the ANT source directory.
  • Now please open the folder where the contents got downloaded and copy the folder path.
  • We need to create a new environment variable as we did earlier and setup its path.
  • Follow the same steps,  open My computer→ Properties→ Advanced System Settings→ Give Yes to the prompted window→ Select “Environment Variables” option
  • Now create a new environment variable named “ANT_HOME” and give the value as the copied folder path. Please check the screenshot as shown below,

  • Now it's time to set the path for this ANT, we can edit the same old path variable and create a new value for it. Please check the screenshot as mentioned,
==> Voila !! We have successfully setup the ANT in our machine. Now we need to download the Force.com Migration tool from the URL, https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool_install.htm

  • Once after downloading the ZIP file, please extract the contents to any folder as per our wish and look for the important file named “ant-salesforce.jar”.
  • We need to copy the file and open the previously installed Apache ANT folder and look for the “lib” folder and copy the jar file into this folder.
  • That's it. We completed the final step. Now, the Force.com migration tool will work based on ANT.
==> Now, we can check if ANT got installed correctly in our machine by opening the command prompt and type “ant -version” then you should get some output.
==> So, we are good to use the ANT migration tool and do deployments using Metadata API.

  • ANT tool will internally work on the JAVA platform, since we are using the JAR file for the same. So ANT basically used XML based tags to perform any tasks. And it's very specific about  the kind of task we are passing via ant commands.
  • We can discuss about them later. So, in our folder where we downloaded the ANT, we are able to see JAR file and Readme.html, this file gives us basic info about the usage and working of this tool.
  • In addition to this, we can have the folder named “sample” and it contains several folders and importantly build.properties and build.xml files.
The files mentioned below are the deciding factors for ANT tool functionality.
  • build.properties:- This file contains the basic set of attributes, namely SF username and password, login URL (we need to choose whether if its a sandbox or Production) and maxpoll(represents no. of connections to our org).            The example file look like this,
  • build.xml:- This XML file contains several set of tasks. Our ANT tool works mainly on these task names. It starts with a project tag, where this project tag contains basic info about the usage of jar file and the properties what we have setup in our earlier step. Then tasks will start with a tag called target.
  • Every target is a separate task for the ANT tool. There are so many tasks predefined in our XML file for deployment, retrieval, deletion etc.. The example file look like this,

Demo to retrieve some components from our Org:-

  • Now we can just do retrieval of all apex classes and triggers from our org.
I need to look for the task in my “build.xml” file and it look like this, 
<target name="retrieveUnpackaged">
      <mkdir dir="retrieveUnpackaged"/>
      <!-- Retrieve the contents into another directory -->
      <sf:retrieve username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" retrieveTarget="retrieveUnpackaged" unpackaged="unpackaged/package.xml"/>
    </target>
  • So, the above task represents, it used our SF username, password, server URL, maxpoll and it creates a new directory named “retrieveUnpackaged” and it will take the required package.xml from the folder path "unpackaged/package.xml" and retrieves everything into the newly created folder. We can modify our package.xml as per our requirement.
  • We need to change the path in our command prompt to the downloaded ANT tool folder where build.properties file exists and can just give our command like “ant <anyTaskName>”
Eg:- ant retrieveUnpackaged
  • The command will look like this,
  • With the above command, it will look into the task retrieveUnpackaged in the build.xml file and it checks the package,xml file and based on package.xml file, it fetches all the apex classes and triggers from my org and writes to the newly created folder “retrieveUnpackaged” in my computer.

The below screenshot shows the newly created folder and it contains all the components,
This demonstrates that we have successfully retrieved all the specified components into a separate folder.

Demo 2:-

==> Now we can deploy some sample apex classes into our Salesforce org.
  • For that, I have created a new folder where my classes and their corresponding package.xml file present.
  • So, the folder name is “Newfolder” and it would be the root folder to deploy.  Then we need to modify the build.xml file like this, 
<target name="deployUnpackaged">
      
 <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" /
 serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="Newfolder" rollbackOnError="true"/>
   
 </target>
  • The above build.xml file represents, SF username, password, server URL, maxpoll, deployroot folder is the one where our classes and package.xml resides and we want the operation to be rolled back if its not successful.
  • Then the command will look like this,
  • We can even run the test classes before deployment. For that, we just need to add testlevel and runtest attributes. So the build.xml file will look like, 
<target name="deployUnpackaged">
     
 <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" /

 serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="Newfolder" /

 testLevel="RunSpecifiedTests" rollbackOnError="true">
 
 <runTest>TestMathCalculator</runTest> 
  
    </sf:deploy>
  
   </target>
  • We just specified the test class that intends to run and the test level would be runspecifiedtests.  Now if we execute the command, it look like,
  • If we wish to run all the test classes in our org, we can modify the build.xml file like this and execute the ant command, 
   <!-- Shows deploying code, running all tests, and running tests (1 of which fails), and logging. -->
    <target name="deployCodeFailingTest">
      <!-- Upload the contents of the "codepkg" package, running all tests -->
      <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="Newfolder" testLevel="RunAllTestsInOrg" rollbackOnError="true" logType="Debugonly"/>
    </target>
  • The ant command would be “ant deployCodeFailingTest”. It will run every test class and at least 75% code coverage is need for this operation to get successful. Then it will give us a detailed debug log with the complete status of the operation.

===> If we wish to see the entire set of metadata types in our org, we can modify our build.xml file like this, 
 
<!-- Retrieve the information on all supported metadata type -->
    <target name="describeMetadata">
      <sf:describeMetadata username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}"/>
    </target>
  • Then the ANT command will look like, “ant describeMetadata”. This will give you a complete list of metadata types available in our org.

===========================================================================

I would even suggest you to please go through the below documentation where you can gain more info about the different operations that we can perform using ANT tool,
https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool.htm

This doc would just give you a brief understanding about the usage of Force.com Migration tool, but if you face any difficulty while accessing the same, SFDX CLI tool would be a better option for deployments.


Comments

Post a Comment

Popular posts from this blog

Apex Code Character Limit (Part I)

-
Image
Apex Code Character Limit What is Apex Code Character Limit? As we know, Salesforce works on a multi-tenant environment. So it provides common resources to every org. If we speak in terms of writing Apex code in our Org, due to multi-tenant architecture design, we do have a limit on code characters for every org.  That means, Salesforce literally counts each and every character that we use to write any code. This limit is called Apex Code Character Limit. The code character limit is almost the same for every org. As of now (after Summer'18 release), the code character limit would be 6 Million. This indicates that any developer can write and develop code in their org up to 6 Million characters. For suppose, if a developer has exhausted the provided code character limit, then an error would be thrown stating that " The total size of apex code in this application after removing comments exceeds the maximum character size of 6000000 ". So we cannot write
Read more

SFDX Developer Guide

-
Image
SFDX Developer Guide SFDX Developer Guide SFDX - Salesforce Developer Experience This doc explains the SFDX concepts in detail and it's solely based on my analysis and understanding. - Rajesh Babu Yanamala How to install SFDX on my machine? For Mac OS -  https://sfdc.co/sfdx_cli_osx For Windows 32-bit -  https://sfdc.co/sfdx_cli_win For Windows 64-bit -  https://sfdc.co/sfdx_cli_win64 Select the defaults, then install it in your machine. Once it's installed in our machine, then we need to verify whether it has been installed correctly. For that, we need to open the Command Prompt from our machine and type the command “ sfdx ” In order to check the version of the CLI, you can use the following command, sfdx --version -To see the installed plugins for SFDX CLI, then type this command, sfdx plugins To know the Salesforce version that's used in our CLI which you have installed, type this, sfdx force --version =
Read more

Deployment in Salesforce using Change sets

-
Image
Deployments in Salesforce Deployments in Salesforce Deployment is the migration of metadata changes between one Salesforce org to another Salesforce org. There are many tools available for Deployment in Salesforce. In this post, we will discuss about Changesets. To use the changesets feature, we need to enable the deployment connection in our org. This would specify the Inbound and Outbound changesets on the Deployment connections page. In Production org, Go to Setup → Type Deployment Settings → Then it will take us to the Deployment Settings page where, it will show the orgs that were connected to this Production org for deployment purpose. By the same way, if we check the Sandbox org “sfdemo1” also, we can be able to see the connected org for deployment as shown below, Sandbox org “sfdemo1” Now, we are going to deploy the things from Sandbox to Production. That means, we are developing the things in Sandbox and going to deploy the same in the Production org. So
Read more

Apex Code Character Limit (Part II)

-
Increase Apex Code Character Limit We all know about Salesforce Apex Code Character limit and how to check the limit that we exhausted in our org.  USE CASE :- For suppose, if I reached the maximum code character limit in my org and I would like to code further, but the system is not allowing me to do so. In this situation, can I reach out to Salesforce Support to get this limit increased for me? The answer is YES. But conditions apply. Increasing the Apex Code Character Limit is not an easy task for Salesforce support. We need to ensure that we followed all best practices and need to check for any anti-patterns, Invalid test practices and Invalid classes. After performing all these checks from our end, then we are good to raise a case with Salesforce to increase the code character limit for my org. Points to Note:- The Code character limit count includes the spaces, tabs and other formatting characters inside the code. The code comes with any managed package
Read more