Announcing Migration Tool Guide. Jumping Ants!

How to Deploy Apex Code and Migrate Organization Settings Using the Migration Tool. [Terminal access to the platform!]

cta_img80_FdC_NL_JUL_Migr.gifOkay, the ants aren’t jumping, but they’re crossing a bridge. This is an apt description of the 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.


The platform holds much of your application as metadata on the platform, and you have access to this metadata. This is how the 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:

ant retrieveUnpackaged

This connected to the 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:

trigger MileageTrigger on Mileage__c (before insert, before update) {
MileageUtil.areMilesAllowed(; //jon was here

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 🙂 ):

ant deployUnpackaged

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

<target name="deployUnpackaged">
<sf:deploy username="${sf.username}" password="${sf.password}" serverurl="
${sf.serverurl}" deployRoot="retrieveUnpackaged"/>

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 Migration Tool a familiar process.

Get it

So it’s all really about “How to Deploy Apex Code and Migrate Organization Settings Using the 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.

July 24, 2008

Leave your comments...

Announcing Migration Tool Guide. Jumping Ants!