Salesforce is a unique development environment. With its declarative nature, many customizations require no code at all (e.g. creating custom objects, fields, formulas, workflows, reports, etc.). But it also supports programmatic customizations too, such as apex classes, triggers, controllers, and visualforce pages.

If you’re coming to the Force.com platform with background as a traditional programmer then you’re likely accustomed to geeking out some code on your local machine then committing to a source control repository, such as git or cvs, then deploying to a server. You maintain a backup of your code in the source code repository where you can version it and rollback to if necessary. (if not, get started today!)

But after working on the Force.com platform for a while you quickly realize, as a cloud service, anytime you make an apex code change or workflow tweak or create a formula field, that change has occurred instantaneously to that Salesforce org. There is no commit to source code repository and there isn’t any deployment from your local machine into Salesforce. It’s just there. And if you’re not careful, it’s also very easy for other developers to accidentally overwrite those customizations and no native way to rollback.

So how do we apply the software development best practices of source control, or at least a versioned backup of our customizations, to the Force.com environment? The answer is the Force.com Migration Tool!

There are plenty of resources online about how to setup continuous integration with Salesforce, but those assume you are doing work in one org and wanting changes synced to other orgs. That is a valid use case, but what I want to share with you is how to setup a very simple ant script to retrieve all the metadata from your Salesforce instance then commit the metadata to git source control so that you can begin scheduling routine backups of all your customizations.

This automation greatly frees up you and your team to work in the Force.com platform, make declarative and programmatic changes directly in your sandbox or production instance, and have peace of mind that behind the scenes all the metadata is being backed up to source control!

Getting Setup

  1. To use the Ant Migration Tool, you’ll need to have Java and Ant installed on the computer/server that will be performing the metadata backup and commit to source control
  2. Create a new git project in your source code repository then check it out to the machine you’ll be using to perform the metadata backup
  3. Download the ant-salesforce.jar from Salesforce. Go to Setup | Develop | Tools then click Force.com Migration Tool link. This will download a zip file; extract the ant-salesforce.jar to the project folder from step 2 (e.g. /yourProject/lib/ant-salesforce.jar)

    salesforce_download_forcecom_migration_tool

    extract_ant_salesforce_jar

  4. Next you’ll need 3 files which you can get from this gist: build.properties, build.xml, and package.xml. Save these directly in your project folder from step 2.

    salesforce_metadata_project_folder_1

  5. Update build.properties with the system administrator credentials for the salesforce instance whose metadata you want to backup
  6. Review package.xml to ensure it lists all the metadata types you are interested in backing up. Note that Email Templates must be specified explicitily by name individually, this metadata type does not support the wildcard * operator.
  7. Open a command prompt in your project folder then type ant. Assuming ant is installed and ANT_HOME added to your path, this will invoke the build.xml script to login to salesforce and retrieve all the desired metadata from package.xml and put it in a new folder called src

    salesforce_metadata_console_output

    salesforce_metadata_project_folder_2

  8. Now you can commit to source control. If you’re using git as in this example, you might issue these commands to add and commit the changes to local git repository then push it to remote:
git add .
git commit -am "auto-sync metadata"
git push -v -u https://<git_username>:<git_password>@<git_url>/<git_project_path>
  1. The last step is to automate! Schedule a script to issue the ant and git commands on a periodic basis. I do hourly snapshots, but you can do it more or less frequently.

References