Wednesday, February 20, 2013

Getting Started with Salesforce Ant Migration with Force.com IDE

I've been using the Force.com IDE for years.  As mentioned in previous posts I found that the time to deploy got really long. Then at Dreamforce 2011 I learned to make smaller projects and this really helped.   But recently, I have found deployment time to be excessive (30 to 60 minutes).  Thanks to the folks who post comments on salesforce.stackoverflow.com!  I love the stackoverflow communities.  This post described my experience and one suggestion is to use the Force.com Ant Migration Tool.


As some folks did remark in the post using a command line tool can be a learning curve that we might not have time for.   The following are my steps to use this tool on my Force.com IDE projects.  These steps are mainly about how to adapt the tool to work within the Force.com IDE file structure and to even use and edit it inside the IDE.

Get the Migration Tool

Get the tool via the Salesforce UI under Settings ... Develop ... Tools.  Download the zip file and unpack it.  Open and read the Readme.html.

My system is a Mac 10.6 so I have Java and Ant installed.  Getting these is not hard and the documentation provides the instructions.

Let's assume our IDE workspace is located
~/Documents/salesforce/workspace
. In here are a number of projects. For example, TestMini, TestFull, ProdMini, ProdFull. The Test project are for developing on a sandbox and the Prod project are for Production. The Mini projects hold just the classes, triggers, etc that I need for the current work. The Full projects contain everything. I do not use these for any development. Instead they are a full copy of all the classes, etc that I can use to check into a source control program.


For this discussion I will do everything in
~/Documents/salesforce/workspace/ProdMini  
and call it ProdMini   for short.  All Force.com IDE projects have a subdirectory called "src". In here you will find a package.xml file and subdirectories like classes.  All you really need at this point is the package.xml file. More on this file later.

Setup Ant in the workspace

Copy  ant-salesforce.jar, build.xml, build.properties  to ProdMini. Edit the build.properties and adjust the user name and password (append your token). Next edit the sample build.xml and make these small adjustments. Locate the retrieveUnpackaged section

<target name="retrieveUnpackaged">
<mkdir dir="retrieveUnpackaged"/>
<!-- Retrieve the contents into another directory -->
<sf:retrieve username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" retrieveTarget="retrieveUnpackaged" unpackaged="unpackaged/package.xml"/>
</target>
change
 retrieveTarget="retrieveUnpackaged" unpackaged="unpackaged/package.xml"
to
retrieveTarget="src" unpackaged="src/package.xml"
This sets up the download from Production to your project of anything contained in the package.xml file. Here is what this file looks like:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>OpportunityUtilities</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>OpportunityUpsertTrigger</members>
        <name>ApexTrigger</name>
    </types>
    <version>26.0</version>
</Package>

The version number depends on the version of ant tool and Force.com IDE.  I don't know what happens if these are not in sync.  So update the Force.com IDE and get the latest Migration Tool.

My project has one Apex class and one trigger.  See my early post about opportunities

Download from the server

Ready to download the files from the server.    From the command prompt and after changing directory to get to ProdMini run this:
$ ant -v -lib . retrieveUnpackaged

The -v shows everything that happens. It is optional but helps you understand what is going on.   The "-lib ." says to include the jar file located in this directory.  Then retrieveUnpackaged
tells Ant to run the contents of that section of the ant file.  The result is a download of the contents in the package.  

Deploy a code change

Next make some small change to the class. For example, add a comment.  The new normal with any change like this, for me, is a 30 to 40 minute hurry up and wait when I deploy it to production.  I am going to see what happens now.

Also make one more edit in the build.xml file.  Locate the deployUnpackaged section
<target name="deployUnpackaged">
      <sf:deploy username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" deployRoot="src"/>
    </target>


Notice that I have changed deployRoot to src
 
Now run the ant tool but this time with the deployUnpackaged target  ant -v -lib . deployUnpackaged

It runs a lot quicker that using the Force.com IDE.   This strongly suggests there is a problem with the IDE.

By using the -v flag I get to see all the tests that run. Interesting information.  The deploy might be faster without this flag.

Next: how to use the Ant tool from within Force.com IDE

Return to the Force.com IDE and selection the Production project. Right click and refresh.  Notice the build.xml etc files are listed (if you have no filters).  Click on the external tools button in the top.
  1. First select the build.xml file.  
  2. Then select the External Tools Configurations...  


  1. Select Ant Build and 
  2. Then press the New button







 
  1. Rename the configuration to Retrieve.  
  2. Select the Targets tab and 
    1. unselect the default and 
    2. select retrieveUnpacked (same as we did above on the command line).  
  3. Press Run to save. (this will fail ...)



Yes, the above fails because the ant-salesforce.jar is not on the classpath.
The Force.com IDE console will suggest where you can place the ant-salesforce.jar file. Or fiddle with the Classpath tab in the external tool configuration.








Repeat the above and create a second external tool configuration. This time name it deploy and select the deployUnpackaged target.

No comments:

Post a Comment