Metadata API Developer Guide

Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
Deploying and Retrieving Metadata with the Zip File
Does a Retrieve Job Have a Status of Pending?
Sample package.xml Manifest Files
Running Tests in a Deployment
Running a Subset of Tests in a Deployment
Run the Same Tests in Sandbox and Production Deployments
Maintaining User References
CRUD-Based Metadata Development
REST Resources
Error Handling
Reference
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Deploying and Retrieving Metadata

Use the deploy() and retrieve() calls to move metadata (XML files) between a Salesforce organization and a local file system. Once you retrieve your XML files into a file system, you can manage changes in a source-code control system, copy and paste code or setup configurations, diff changes to components, and perform many other file-based development operations. At any time you can deploy those changes to another Salesforce organization.

The Ant Migration Tool uses the deploy() and retrieve() calls to move metadata. If you use these tools, interaction with Metadata API is seamless and invisible. Therefore, most developers will find it much easier to use these tools than write code that calls deploy() and retrieve() directly.

Note

Data in XML files is formatted using the English (United States) locale. This ensures that fields that depend on locale, such as date fields, are interpreted consistently during data migrations between organizations using different languages. Organizations can support multiple languages for presentation to their users.

The deploy() and retrieve() calls are used primarily for the following development scenarios:

  • Development of a custom application (or customization) in a sandbox organization. After development and testing is completed, the application or customization is then deployed into a production organization using Metadata API.
  • Team development of an application in a Developer Edition organization. After development and testing is completed, you can then distribute the application via Lightning Platform AppExchange.

You receive an API notification each time you retrieve 90% or more of the maximum number of custom fields that you can deploy at once with Metadata API. The maximum custom fields for one deployment is 45,000. The custom fields retrieved in one package.xml file are: 1) the sum of the fields on each object in the CustomObjects section of package.xml and 2) the sum of the custom fields in the CustomFields section of package.xml.

You can still retrieve above the deployable maximum up to the limit on total size of retrieved files. But you must use more than one deployment to deploy all of the custom fields.

Example

Warning: You have retrieved 47000 instances of CustomField. You will not be able to redeploy all these instances at the same time; the maximum is 45000.