Metadata API Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
CRUD-Based Metadata Development
REST Resources
Deploy Metadata with Apex Testing Using REST
Deploy Metadata with REST API in Salesforce CLI
Error Handling
Reference
Appendices
PDF

REST Resources

Use the REST resource deployRequest to move metadata (XML files) between a Salesforce organization and a local file system.

Data in XML files is formatted using the English (United States) locale. This approach 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.

Metadata deployment is used primarily for the following development scenarios.

  • Development of a custom application (or customization) in a sandbox organization. After development and testing are 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 are completed, you can then distribute the application via Lightning Platform AppExchange.

Working with the Zip File

The deployRequest resource is used to deploy 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 deployed in a .zip file can be unpackaged components that reside in your organization (such as standard objects). The files can also be packaged components that reside within named packages.

You can deploy up to 10,000 files at once. (In API version 43.0 and later, AppExchange packages can contain up to 12,500 files.) The .zip file size limit that applies to SOAP calls doesn’t apply to the deployRequest REST resource. However, the 400-MB limit for components that are uncompressed into an unzipped folder after upload applies to both SOAP and REST deployments.

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 and the API version used for the deployment or retrieval.

The following is a sample package.xml file. 

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>MyCustomObject__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomTab</name>
    </types>
    <types>
        <members>Standard</members>
        <name>Profile</name>
    </types>
    <version>64.0</version>
</Package>

The following elements can be defined in package.xml.

  • <fullName> contains the name of the server-side package. If no <fullName> exists, it’s 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 deployed. You can add multiple <types> elements in a manifest file.
  • <members> contains the fullName of the component, such as MyCustomObject__c. For many metadata types, you can replace the value in members with the wildcard character * (asterisk) instead of listing each member separately. For a list of metadata types that allow the wildcard character, see the “Allows Wildcard (*)?” column in Metadata Types.

    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’s 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 64.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.