Okay, the ants aren’t jumping, but they’re crossing a bridge. This is an apt description of the Force.com Migration Tool – it’s an Ant library that lets you migrate metadata – code and settings. Well, it’s a little more than that – it’s more like migrate/move/create/push/deploy. Let me explain.

Metadata

The Force.com platform holds much of your application as metadata on the platform, and you have access to this metadata. This is how the Force.com IDE works – it uses the metadata to grab your code, your packages, your triggers and so on and edit them locally. Every time you edit an Apex page, it sends the code back to the server where it’s compiled. So this metadata is powerful stuff, it’s the essence of your org.

Using the Migration Tool

I’ve been playing around with the migration tool for the past hour. The guide docs show how to retrieve and install it. The guide actually comes with a sample directory that includes a build.xml script, which is a great start. Using this, I executed the following commands:

This connected to the Force.com platform, grabbed all the metadata associated with my unpackaged objects, and hauled them into a local directory called retrieveUnpackaged. This resulted in three sub-directories:

classes contained all of the classes I’ve defined (the actual Apex and other metadata), and triggers the triggers. For example, here is one item, MileageTrigger.trigger:

As you can see these are plain text files (the XML are XML package deployment descriptors, documented in the Metadata API Developer’s Guide). So you can modify the setup of your org in the descriptors, change code, and of course upload the changes. Here’s how I deployed my changed trigger (I just changed the comment 🙂 ):

Delving into the build file, I see that the target is a thin veneer around the tool:

Some of the other targets include:

There isn’t a way to list packages, except through the web interface.

What’s it good for?

As you can see, this tool gives you raw access to your metadata, and I can imagine many uses for this:

• Deploying client-side-machine-generated code!
• Migrating data! I can retrieve from one organization, and deploy to another.
• Testing a set of changes, by deploying different code iterations from your client.

The docs add to this:

• Development projects – where you need to populate a test environment with large amounts of setup changes – Making these changes using a Web interface could take a long time.
• Multistage release processes – A typical development process requires iterative building, testing, and staging before releasing to a production environment. Scripted retrieval and deployment of components can make this process much more efficient.
• Repetitive deployment using the same parameters – You can retrieve all the metadata in your organization, make changes, and deploy a subset of components. If you need to repeat this process, it’s as simple as calling the same deployment target again.
• When migrating from stage to production is done by IT – Anyone that prefers deploying in a scripting environment will find the Force.com Migration Tool a familiar process.

Get it

So it’s all really about “How to Deploy Apex Code and Migrate Organization Settings Using the Force.com Migration Tool” – and you can find all these details in the Migration Guide. It’s also referenced from the main Tools page on the wiki.

Have fun, and let me know if you find some other novel ways in which you can use this tool.