Metadata API Developer Guide

Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
Deploying and Retrieving Metadata with the Zip File
Slow Deployments
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 Relevant Apex Tests in a Deployment (Beta)
Run the Same Tests in Sandbox and Production Deployments
Limit on Enqueued Deployments from Apex
Maintaining User References
CRUD-Based Metadata Development
REST Resources
Error Handling
Metadata API Context MCP Tool (Beta)
Reference
Appendices
PDF

Newer Version Available

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

Deploying and Retrieving Metadata with the Zip File

The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.

A component is an instance of a metadata type. For example, CustomObject is a metadata type for custom objects, and the MyCustomObject__c component is an instance of a custom object.

Note

The files that are retrieved or deployed in a .zip file might be unpackaged components that reside in your org (such as standard objects) or packaged components that reside within named packages.

You can deploy or retrieve up to 10,000 files at once. The maximum size of the deployed or retrieved .zip file is 39 MB. If the files are uncompressed in an unzipped folder, the size limit is 600 MB or 629,145,600 bytes. The size limit in bytes is calculated as 600 x 1024 x 1024.

Managed packages use different limits: First-generation managed packages that have passed AppExchange Security Review can contain up to 35,000 files. Second-generation managed packages can contain up to 10,000 files.

  • Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB, which is the limit for SOAP messages. Base-64 encoding increases the size of the payload, so your compressed payload can't exceed approximately 39 MB before encoding.
  • You can perform a retrieve() call for a big object only if its index is defined. If a big object is created in Setup and doesn’t yet have an index defined, you can’t retrieve it.
  • Limits can change without notice.

Note

Every .zip file contains a project manifest, a file that’s named package.xml, and a set of directories that contain the components. The manifest file defines the components that you're trying to retrieve or deploy in the .zip file. The manifest also defines the API version that's used for the deployment or retrieval.

You can edit the project manifest, but be careful if you modify the list of components it contains. When you deploy or retrieve components, Metadata API references the components listed in the manifest, not the directories in the .zip file.

Note

Note: If you’re retrieving any components that have dependencies by using the rootTypesWithDependencies parameter in the RetrieveRequest object, the dependent metadata components are added to the returned .zip file and package.xml file in the same directory as the root type that’s being retrieved. This directory has a JSON file for each component with dependencies in the format ComponentName.roottype.dependencies-meta.json.

Note

The following is a sample package.xml file. You can retrieve an individual component for a metadata type by specifying its fullName field value in a members element. You can also retrieve all components of a metadata type by using <members>*</members>.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>MyCustomObject__c</members>
5        <name>CustomObject</name>
6    </types>
7    <types>
8        <members>*</members>
9        <name>CustomTab</name>
10    </types>
11    <types>
12        <members>Standard</members>
13        <name>Profile</name>
14    </types>
15    <version>66.0</version>
16</Package>

The following elements can be defined in package.xml.

  • <fullName> contains the name of the server-side package. If no <fullName> exists, the package.xml defines a client-side unpackaged package.
  • <types> contains the name of the metadata type (for example, CustomObject) and the named members (for example, myCustomObject__c) to be retrieved or deployed. You can add multiple <types> elements in a manifest file.
  • <members> contains the fullName of the component, for example MyCustomObject__c. The listMetadata() call is useful for determining the fullName for components of a particular metadata type if you want to retrieve an individual component. For many metadata types, you can replace the value in members with the wildcard character * (asterisk) instead of listing each member separately. See the reference topic for a specific type to determine whether that type supports wildcards.

    You specify Security in the <members> element and Settings in the name element when retrieving the SecuritySettings component type.

    Note

  • <name> contains the metadata type, for example CustomObject or Profile. There is one name defined for each metadata type in the directory. Any metadata type that extends Metadata is a valid value. The name that’s entered must match a metadata type that’s defined in the Metadata API WSDL. See Metadata Types for a list.
  • <version> is the API version number that’s used when the .zip file is deployed or retrieved. Currently the valid value is 66.0.

For more sample package.xml manifest files that show you how to work with different subsets of metadata, see Sample package.xml Manifest Files.

To delete components, see Deleting Components from an Organization.