..

Using the Force.com Migration Tool and Git

For those junior Salesforce Developers/Administrators out there that are not using Source Control, you are doing yourself a diservice! There are a lot of Salesforce Orgs out there in the wild that are not using Source Control even Orgs with IT departments. Many of the excuses you will hear from leadership in IT why were not using source control is:

  • Were a small IT team
  • We don’t deploy code often
  • It’s too expensive
  • It’s overkill and creates too much overhead

Do not accept these reasons, these really just ring lazyness in all honesty and as a young developer you should strive to follow best practices.

Why should you usen the Source Control?

This tool alone will save your ass and quite possibly your job. Here is a list of reasons you should use this tool:

  • Collaboration with other developers on the same piece of code at the same time
  • Making changes to code, and being able to undo
  • Being able to lookup what, where, and when certain people made changes to code
  • See differences in versions of a file
  • Assistance in troubleshooting bugs
  • Prove your changes didn’t introduce a bug aka saving your ass
  • Not losing an entire mornings amount of work when someone updated their old version of a file aka saving your ass
  • Additional backup aka saving your ass

Okay you get the point now. These are just the highlights of why you should be adopting Source Control. If you are working for a company that is not using Source Control, do you and your company a favor and champion this idea.

If you are with me so far you are probably asking yourself How do I use Source Control with Salesforce? One of the most powerful tools a Salesforce developer/Administrator can utilize to deploy code and configure salesforce.com is the Force.com Migration Tool, which in part allows for you to store in any source code management system.

What is the Force.com Migration Tool?

The Force.com Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a salesforce organization.

Installing the Force.com Migration Tool

All you need is two things to use this tool Java and Ant. Once you have Java and Ant installed on your local machine, you can download the Force.com Migration Tool from a Salesforce org.

Installation is easy as 1, 2, 3

  1. Log into a Salesforce org.
  2. From Setup, Click Develop > Tools, and then click Force.com Migration Tool.
  3. Save the zip file locally and extract the contents to the directory of your choice.

Using the Force.com Migration Tool

From here the general procedure you would follow is:

  1. Enter your credentials and connection information for source Salesforce organization in build.properties
  2. Create or use the default retrieve targets in build.xml
  3. Construct your project manifest in package.xml
  4. Run the Force.com Migration Tool to retrieve metadata files from Salesforce.
  5. Enter credentials and connection information for destination Salesforce organization in build.properties
  6. run the Force.com Migration Tool to deploy metadata files or even deletions to Salesforce.

This is an example of a “build.properties” file:

# build.properties
#

# Specify the login credentials for the desired Salesforce organization
sf.username = <Insert your Salesforce username here>
sf.password = <Insert your Salesforce password here>
#sf.sessionId = <Insert your Salesforce session id here.  Use this or username/password above.  Cannot use both>
#sf.pkgName = <Insert comma separated package names to be retrieved>
#sf.zipFile = <Insert path of the zipfile to be retrieved>
#sf.metadataType = <Insert metadata type name for which listMetadata or bulkRetrieve operations are to be performed>

# Use 'https://login.salesforce.com' for production or developer edition (the default if not specified).
# Use 'https://test.salesforce.com for sandbox.
sf.serverurl = https://login.salesforce.com

sf.maxPoll = 20
# If your network requires an HTTP proxy, see http://ant.apache.org/manual/proxy.html for configuration.
#

This is an example of “build.xml” file (Abbreviated for brevity):

project name="Sample usage of Salesforce Ant tasks" default="test" basedir="." xmlns:sf="antlib:com.salesforce">

    <property file="build.properties"/>
    <property environment="env"/>

    <!-- Shows retrieving code; only succeeds if done after deployCode -->
    <target name="retrieveCode">
      <!-- Retrieve the contents listed in the file codepkg/package.xml into the codepkg directory -->
      <sf:retrieve username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" retrieveTarget="codepkg" unpackaged="codepkg/package.xml"/>
    </target>

    <!-- Shows deploying code & running tests for code in directory -->
    <target name="deployCode">
      <!-- Upload the contents of the "codepkg" directory, running the tests for just 1 class -->
      <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="codepkg" testLevel="RunSpecifiedTests" rollbackOnError="true">
      	 <runTest>SampleDeployClass</runTest>
      </sf:deploy>
    </target>
</project>

This is an example of the “package.xml” file:

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

Retrieving Metadata from a Salesforce org

In command prompt, simply type ant retrieveCode to retrieve the classes and trigger mentioned in package.xml

Deploying Code

In command prompt, simply type ant deployCode to deploy the contents of the codepkg package and runs the tests for one class.

Conclusion

This is a high level overview of what this tool is capable of doing and I would implore those interesting in heading over to Developer.salesforce.com and reading up on the official documentation for the Force.com Migration Tool. Using the Force.com Migration tool in conjuction with a popular source control system such Github or Bitbucket will overall give you that sense of security for both you and your company.

That’s it for now. Happy Coding,

-Korben