ANT Series – How do I get started?


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.
  1. 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.
  2. Go to http://ant.apache.org/bindownload.cgi and download the files to your local machine.
  3. 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).
  4. Open up command line (start menu and type cmd or windows + r – cmd).
  5. 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.
    1. Provided you have saved your directory to c:\ant, type “set ANT_HOME=c:\ant”
    2. 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.
    3. Then append this to the PATH variable by typing the following, “set PATH=%PATH%;%ANT_HOME%\bin”
  6. 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:

antversion

 

 

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.

  1. 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.
#
  1. 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.
  2. 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?

  1. 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.
  2. The condition properties for sf.username, sf.password, and sf.sessionId log in to the instance.
  3. The target of bulkRetrieveCustomObject is the command that you will type to retrieve custom objects.
    1. The delete dir command deletes the variable in sf.dir, in this case, the metadata directory specified in the build.properties file.
    2. The mkdir dir comment will recreate it.
      1. 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!
    3. The sf:bulkRetrieve command will retrieve our custom object, place it in the metadata folder.  The two biggest variables that are important here are:
      1. metadataType – the type of the component being retrieved.
      2. 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!)

retrieve

 

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:

  1. ApexClass
  2. ApexComponent
  3. ApexPage
  4. ApexTrigger
  5. ApprovalProcess
  6. CustomApplication
  7. CustomLabels
  8. CustomObject
  9. CustomObjectTranslation
  10. CustomPageWebLink
  11. CustomSite
  12. CustomTab
  13. DataCategoryGroup
  14. FieldSet
  15. Flow
  16. Group
  17. HomePageComponent
  18. HomePageLayout
  19. Layout
  20. Portal
  21. Queue
  22. RecordType
  23. RemoteSiteSetting
  24. ReportType
  25. Role
  26. Workflow
  27. 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.

projContact

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!

Leave a comment

Your email address will not be published. Required fields are marked *