ANT, versus other tools
First of all, what is “ANT” (aka the force.com migration tool)? ANT is a command line utility that allows for you to retrieve metadata or to deploy metadata to your organizations with ease. So, you might be asking yourself, why would I want to use a tool like this when there are good interfaces such as the Force.com IDE or Mavensmate? ANT allows you to retrieve lots of metadata efficiently, allows you to retrieve it in a repeatable way, provides you the benefit of being able to schedule your retrieves and can use windows command line functions to arrange or re-arrange your metadata.
I don’t know about you but the Force.com IDE will not download all of the metadata in my organization and freezes up when doing retrieves. It will not scale and times out on reads frequently. It’s a good tool for newer organizations or if you retrieve your metadata through ANT or workbench and then load it into the IDE. Half of the benefit of using a tool like the Force.com IDE though is the ability to retrieve the components you want in a single interface. Since I can’t do that with how many components I have in my organization, it’s mostly a lost cause.
Mavensmate, in my opinion, scales much better with your organization, looks pretty (and so much more 2016) and takes advantage of sublime text awesome features. It does do quite a bit of API calls to your organization to get all of the metadata though, so if you’re limited in this regard, just be mindful. You may have to disable the usage of the tooling API.
But, all of that aside, ANT allows me to easily retrieve components I want easily with one line. For example, if I want to retrieve ALL custom objects in my organization, I have to write this one B-E-A-U-tiful line:
ant bulkRetrieveCustomObject
That’s it. Why do I do this? It makes it much easier to search metadata components for references or to pipe the metadata into spreadsheets.
How do I get started?!
Make sure that you save these URLs before going any further, they will help you immensely:
- Force.com Migration Tool Guide
- Metadata API Guide – This link has the full guide, but I’ve put in the link to all metadata types on Salesforce. Trust me, you will want this, especially if you aren’t familiar with all of the metadata types in package.xml files.
- If you do not have a version of the Java Development Kit (JDK), download the latest version from http://www.oracle.com/technetwork/java/javase/downloads/index.html. The installation process should take a minute or two.
- Go to http://ant.apache.org/bindownload.cgi and download the files to your local machine.
- Extract the files onto your local machine. I think it’s best to place them in at the c:\ directory in a folder called ANT, c:\ant for the full path name (trust me, this makes your life easier if you’re not working on a windows 10 environment).
- Open up command line (start menu and type cmd or windows + r – cmd).
- Now, we need to setup environment variables. NOTE: If we set them up in the command prompt they are only valid for the session of command prompt that you have open.
- Provided you have saved your directory to c:\ant, type “set ANT_HOME=c:\ant”
- Locate where you have installed the java jdk and type, “set JAVA_HOME=c:\[jdk]”, where jdk is the path that resolves to your local directory.
- Then append this to the PATH variable by typing the following, “set PATH=%PATH%;%ANT_HOME%\bin”
- Now your environment is setup and ready to use ANT!
Before proceeding, run the following to make sure that you’ve setup everything correctly.
ant -version
You should get back something like the following:
If you have administrator rights on your machine or your IT dept will do this for you, they should update the PATH variable (as described above) in the instructions here: https://www.java.com/en/download/help/path.xml. Why is this nice? You don’t have to type the above every single time you want to do an ANT pull (saves a minute or two of your day). Trust me, it’s suppper nice.
Time for some hands on action!
Download the sample ant library under Setup | Develop | Tools. I highly recommend following the samples in the sample file just downloaded with your personal developer org and walking through the commands in the sample to become more familiar with this tool. However, for this post, I will be keeping it simple for just retrieving metadata in bulk. I will walk through other commands throughout the series.
- Create a new file in notepad and enter the following text, add your username next to the sf.username variable, your password + security token combination under sf.password, and change sf.serverurl to test.salesforce.com if you are working in a sandbox (I recommend, if this is your first time with ant, leaving as login.salesforce.com and testing in your own developer org). NOTE: ANT by default will only retrieve 10 components at a time. I have specified this as 2000 (max 4000), because I work in a large org and it would take days to complete if left at 10.
# build.properties # # https://test.salesforce.com for sandbox environments sf.serverurl = https://login.salesforce.com sf.username = sf.password = #Specify the directory to save sf.dir = metadata sf.maxPoll = 20 # Specify number of items to retrieve - I set this high because of a large amount of items sf.batchsize = 2000 # If your network requires an HTTP proxy, see http://ant.apache.org/manual/proxy.html for configuration. #
- Save this file as “build.properties” in a folder called “antTest” on your desktop. This file stores the variables that you reference in the build.xml file that we will be creating shortly.
- Open a new notepad and paste in the below. This will be your build.xml file. I will break down the components after we finish this.
<project name="Sample usage of Salesforce Ant tasks" default="bulkRetrieveCustomObject" basedir="." xmlns:sf="antlib:com.salesforce">
<property file="build.properties"/>
<property environment="env"/>
<!-- Setting default value for username, password and session id properties to empty string
so unset values are treated as empty. Without this, ant expressions such as ${sf.username}
will be treated literally.
-->
<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="bulkRetrieveCustomObject">
<delete dir="${sf.dir}"/>
<mkdir dir="${sf.dir}" />
<sf:bulkRetrieve username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" metadataType="CustomObject" retrieveTarget="${sf.dir}" batchSize="${sf.batchsize}"/>
</target>
</project>
So what’s all that gook up above?
- The project is essentially everything inside of ANT, all of the targets, and properties that you need to use for retrieving metadata. The default action specified is to retrieve custom objects.
- The condition properties for sf.username, sf.password, and sf.sessionId log in to the instance.
- The target of bulkRetrieveCustomObject is the command that you will type to retrieve custom objects.
- The delete dir command deletes the variable in sf.dir, in this case, the metadata directory specified in the build.properties file.
- The mkdir dir comment will recreate it.
- This is essentially to wipe out the previous retrieve. If you don’t want to do that, you can get super fancy and version your retrieves or make folders based on dates. But, that’ll be for a later date!
- The sf:bulkRetrieve command will retrieve our custom object, place it in the metadata folder. The two biggest variables that are important here are:
- metadataType – the type of the component being retrieved.
- batchSize – how many to retrieve in one go. This will be 2000, as specified in build.properties.
Now, change directory in command line to your desktop folder. If you have called it antTest, you can type the following: “cd c:\users\[your username\desktop\antTest”. Last step! Run “ant bulkRetrieveCustomObject”. Your output should look like this. (You’ll notice I have conga and field trip installed. Woot!)
You’ve done it! You’ve got all your custom objects in your org downloaded to your machine. You can then use this to backup your custom object metadata, throw it into git or something else!
Here’s a list of all components that I have a bulkRetrieve for:
- ApexClass
- ApexComponent
- ApexPage
- ApexTrigger
- ApprovalProcess
- CustomApplication
- CustomLabels
- CustomObject
- CustomObjectTranslation
- CustomPageWebLink
- CustomSite
- CustomTab
- DataCategoryGroup
- FieldSet
- Flow
- Group
- HomePageComponent
- HomePageLayout
- Layout
- Portal
- Queue
- RecordType
- RemoteSiteSetting
- ReportType
- Role
- Workflow
- StaticResource – (up the pollWaitMillis to 30000 and maxPoll to 100 since the files are large)
I also have a target command called “bulkRetrieveAll” which gets all of the above components and puts them in my metadata directory. Really great for when you want to search all metadata components for references, with the exception of profiles, permissionsets, reports and dashboards.
Here’s why I find this really useful. Say I want to search for a field “project__c” inside of my organization. I can type findstr /I /N “project__c” “C:\users\[your username]\desktop\antTest\metadata\objects\*” and it will search for project__c in the metadata files just retrieved (all components in the objects directory). You can see that I have two references, one is the project field on the project_contact__c object and the other is displaying that it is a reference to project.
You can do the same thing to search workflow rules that have a reference to your domain for updating in a sandbox environment, for example. Let your imagination run wild!
Thanks for reading and I hope to see you next time for retrieving specific components via ANT!