Documentation Version
Winter '16 (API version 35.0)
  • Winter '16 (API version 35.0) 35.0
  • Summer '15 (API version 34.0) 34.0
  • Spring '15 (API version 33.0) 33.0
  • Winter '15 (API version 32.0) 32.0
  • Summer '14 (API version 31.0) 31.0
  • Spring '14 (API version 30.0) 30.0
  • Winter '14 (API version 29.0) 29.0
  • English
  • Japanese Migration Tool Overview

The Migration Tool is a Java/Ant-based command-line utility for moving metadata between a local directory and a Salesforce organization. The Migration Tool is especially useful in the following scenarios:
  • 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.

Understanding Metadata API

Metadata API contains a set of objects that manage setup and customization information (metadata) for your organizations, and the SOAP calls that manipulate those objects. With Metadata API you can:

  • Work with setup configuration as XML metadata files
  • Migrate configuration changes between organizations
  • Create your own tools for managing organization and application metadata

Though you could write your own client applications for using Metadata API SOAP calls, Salesforce provides the Migration Tool to retrieve and deploy Apex and metadata.

Understanding Package and Directory Structure

Metadata API functions in a package-centric manner. Components may be in one or more packages, or in no package at all. Packages may be local (created in your Salesforce organization) or installed from AppExchange. Whenever the Migration Tool retrieves a set of components, that set will be limited to what’s in a single package or what’s in no package at all. There are three kinds of packages:
  • Unpackaged—Components that live natively in your organization, such as standard objects, go in the unpackaged package.
  • Unmanaged package—Unmanaged packages are typically used to distribute open-source projects or application templates to provide developers with the basic building blocks for an application. Once the components are installed from an unmanaged package, the components can be edited in the organization they are installed in. The developer who created and uploaded the unmanaged package has no control over the installed components, and can't change or upgrade them. Unmanaged packages should not be used to migrate components from a sandbox to production organization. Instead, use Change Sets.
  • Managed package—A collection of application components that is posted as a unit on the AppExchange and associated with a namespace and possibly a License Management Organization. To support upgrades, a package must be managed. An organization can create a single managed package that can be downloaded and installed by many different organizations. Managed packages differ from unmanaged packages by having some locked components, allowing the managed package to be upgraded later. Unmanaged packages do not include locked components and cannot be upgraded. In addition, managed packages obfuscate certain components (like Apex) on subscribing organizations to protect the intellectual property of the developer.