Declarative (File-Based) Metadata API Calls. salesforce Metadata API

Metadata API is a powerful tool for managing customizations in Salesforce organizations. It allows you to retrieve, deploy, create, update, or delete metadata components such as custom objects, page layouts, and Apex code.

PDF

Document

USING METADATA API

CHAPTER 3 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.

Note:

The Force.com IDE and the Force.com Migration Tool use 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.

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 Force.com AppExchange.

Working 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.

Note: 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.

The files that are retrieved or deployed in a .zip file might be unpackaged components that reside in your organization (such as standard

objects) or packaged components that reside within named packages.

Note:

You can deploy or retrieve up to 10,000 files at once and the maximum size of the deployed or retrieved .zip file is 39 MB.

Note the following:

•

If using the Force.com Migration Tool to deploy an unzipped folder, all files in the folder are compressed first. The maximum size of uncompressed components in an unzipped folder is 400 MB or less depending on the compression ratio. If the files have a high compression ratio, you can migrate a total of approximately 400 MB because the compressed size would be under

39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 400 MB.

Deploying and Retrieving Metadata Working with the Zip File

•

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.

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

The following is a sample package.xml

file. Note that you can retrieve an individual component for a metadata type by specifying its fullName

field value in a members

element, or you can also retrieve all components of a metadata type by using

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >MyCustomObject__c </members >

<name >CustomObject </name >

</types >

<name >CustomTab </name >

</types >

<members >Standard </members >

<name >Profile </name >

</types >

<version >39.0

</version >

</Package >

The following elements can be defined in package.xml

•

contains the name of the server-side package. If no

exists, this is a client-side unpackaged package.

•

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

elements in a manifest file.

•

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. For a list of metadata types that allow the wildcard character, see the “Allows Wildcard (*)?” column

in Metadata Types .

Note: You specify Security in the

element and Settings in the name element when retrieving the SecuritySettings component type.

•

<name >

contains the metadata type, for example

CustomObject

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.

•

is the API version number that’s used when the .zip file is deployed or retrieved. Currently the valid value is

39.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 .

Deploying and Retrieving Metadata Sample package.xml Manifest Files

To delete components, see

Deleting Components from an Organization

Sample

package.xml

Manifest Files

This section includes sample package.xml

manifest files that show you how to work with different subsets of metadata. A manifest file can include multiple

elements so you could combine the individual samples into one package.xml

manifest file if you want to work with all the metadata in one batch. For more information about the structure of a manifest file, see

Working with the

Zip File . The following samples are listed:

•

Standard Objects

•

All Custom Objects

•

Standard Picklist Fields

•

Custom and Standard Fields

•

List Views for Standard Objects

•

Packages

•

Security Settings

•

Assignment Rules, Auto-response Rules, Escalation Rules

•

Sharing Rules

•

Managed Component Access

Standard Objects

This sample package.xml

manifest file illustrates how to work with the standard Account object. Retrieving or deploying a standard object includes all custom and standard fields except for standard fields that aren’t customizable. All custom fields are supported. Only standard fields that you can customize are supported, that is, standard fields to which you can add help text or enable history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as

CreatedById

LastModifiedDate

) and autonumber fields.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Account </members >

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

Note how you work with the standard Account object by specifying it as a member of a CustomObject type. However, you cannot use an asterisk wildcard to work with all standard objects; each standard object must be specified by name.

Deploying and Retrieving Metadata Sample package.xml Manifest Files

All Custom Objects

This sample package.xml

manifest file illustrates how to work with all custom objects.

<?xml

version= "1.0" encoding= "UTF-8"?>

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

This manifest file can be used to retrieve or deploy all custom objects. This does not include all standard objects.

Standard Picklist Fields

In API version 38.0 and later, the StandardValueSet type represents standard picklists. Picklists are no longer represented by fields as in earlier versions. This sample package.xml

represents the

Industry

standard picklist as a StandardValueSet type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Industry </members >

<name >StandardValueSet </name >

</types >

<version >39.0

</version >

</Package >

Note: The name of a standard value set is case-sensitive.

The

Industry

standard value set corresponds to the

Account.Industry

Lead.Industry

field in API version 37.0 and earlier. This example shows a package.xml

sample for the

Account.Industry

picklist.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Account.Industry

</members >

<name >CustomField </name >

</types >

<version >37.0

</version >

</Package >

Note:

The name of a picklist field is case-sensitive.

Note the

objectName.picklistField

syntax in the

field where

objectName

is the name of the object, such as

Account

, and

picklistField

is the name of the standard picklist field, such as

Industry

This next package.xml

sample represents opportunity team roles in API version 38.0 and later. Specify opportunity team roles as a

SalesTeamRole

standard value set. Opportunity team roles have the same picklist values as the account team roles.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >SalesTeamRole </members >

Deploying and Retrieving Metadata Sample package.xml Manifest Files

<name >StandardValueSet </name >

</types >

<version >39.0

</version >

</Package >

The

SalesTeamRole

standard value set corresponds to one of these field names in API version 37.0 and earlier:

OpportunityTeamMember.TeamMemberRole

UserAccountTeamMember.TeamMemberRole

UserTeamMember.TeamMemberRole

, and

AccountTeamMember.TeamMemberRole

. Opportunity team roles are represented in this sample package.xml

as the

OpportunityTeamMember.TeamMemberRole

field.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >OpportunityTeamMember.TeamMemberRole

</members >

<name >CustomField </name >

</types >

<version >37.0

</version >

</Package >

To learn about the names of standard value sets and how they map to picklist field names, see StandardValueSet Names and Standard

Picklist Fields .

Custom and Standard Fields

This sample package.xml

manifest file illustrates how to work with custom fields in custom and standard objects and standard fields in a standard object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >MyCustomObject__c.MyCustomField__c

</members >

<name >CustomField </name >

</types >

<members >Account.SLA__c

</members >

<members >Account.Phone

</members >

<name >CustomField </name >

</types >

<version >39.0

</version >

</Package >

Note the

objectName.field

syntax in the

field where

objectName

is the name of the object, such as Account, and

field

is the name of the custom or standard field, such as an

SLA

picklist field representing a service-level agreement option.

The

MyCustomField

custom field in the MyCustomObject custom object is uniquely identified by its full name,

MyCustomObject__c.MyCustomField__c

. Similarly, the

Phone

standard field in the Account standard object is uniquely identified by its full name,

Account.Phone

All custom fields are supported. Only standard fields that you can customize are supported, that is, standard fields to which you can add help text or enable history tracking or Chatter feed tracking. Other standard fields aren't supported, including system fields (such as

CreatedById

LastModifiedDate

) and autonumber fields.

Deploying and Retrieving Metadata Sample package.xml Manifest Files

List Views for Standard Objects

The easiest way to retrieve list views for a standard object is to retrieve the object. The list views are included in the retrieved component.

See Standard Objects on page 17.

You can also work with individual list views if you do not want to retrieve all the details for the object. This sample package.xml

manifest file illustrates how to work with a list view for the standard Account object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Account.AccountTeam

</members >

<name >ListView </name >

</types >

<version >39.0

</version >

</Package >

Note the

objectName.listViewUniqueName

syntax in the

field where

objectName

is the name of the object, such as Account, and

listViewUniqueName

is the

View Unique Name

for the list view. If you retrieve this list view, the component is stored in objects/Account.object

Packages

To retrieve a package, set the name of the package in the packageNames

field in

RetrieveRequest

when you call retrieve()

The package.xml

manifest file is automatically populated in the retrieved

.zip

file. The

element in package.xml

contains the name of the retrieved package.

If you use an asterisk wildcard in a

element to retrieve all the components of a particular metadata type, the retrieved contents do not include components in managed packages. For more information about managed packages, see the ISVforce Guide .

The easiest way to retrieve a component in a managed package is to retrieve the complete package by setting the name of the package in the

packageNames

field in RetrieveRequest

, as described above. The following sample package.xml

manifest file illustrates an alternative to retrieve an individual component in a package.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >myns__MyCustomObject__c </members >

<name >CustomObject </name >

</types >

<version >39.0

</version >

</Package >

Note the

namespacePrefix

objectName

syntax in the

field where

namespacePrefix

is the namespace prefix of the package and

objectName

is the name of the object. A namespace prefix is a 1 to 15-character alphanumeric identifier that distinguishes your package and its contents from other publishers’ packages. For more information, see “Register a Namespace

Prefix” in the Salesforce Help.

Deploying and Retrieving Metadata Sample package.xml Manifest Files

Security Settings

This sample package.xml

manifest file illustrates how to work with an organization’s security settings. You specify Security in the

element and Settings in the name element when retrieving the SecuritySettings component type.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Security </members >

<name >Settings </name >

</types >

<version >39.0

</version >

</Package >

Assignment Rules, Auto-response Rules, Escalation Rules

Assignment rules, auto-response rules and escalation rules use different package.xml

type names to access sets of rules or individual rules for object types. For example, the following sample package.xml

manifest file illustrates how to access an organization’s assignment rules for just Cases and Leads.

<?xml

version= "1.0" encoding= "UTF-8"?>

<name >AssignmentRules </name >

</types >

<version >39.0

</version >

</Package >

The following sample package.xml

manifest file illustrates how to access just the “samplerule” Case assignment rule and the

“newrule” Lead assignment rule. Notice that the type name is

AssignmentRule

and not

AssignmentRules

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Case.samplerule

</members >

<members >Lead.newrule

</members >

<name >AssignmentRule </name >

</types >

<version >39.0

</version >

</Package >

Similarly, for accessing individual auto-response rules and escalation rules, use

AutoResponseRule

and

EscalationRule instead of

AutoResponseRules

and

EscalationRules

Sharing Rules

In API version 33.0 and later, you can retrieve and deploy sharing rules for all standard and custom objects. This sample package.xml

manifest file illustrates how to work with an organization’s sharing rules, which includes retrieving a specific criteria-based sharing rule

Deploying and Retrieving Metadata Sample package.xml Manifest Files for the lead object, retrieving all ownership-based sharing rules for all objects, and retrieving all territory-based sharing rules for the account object.

<?xml

version= "1.0" encoding= "UTF-8"?>

<members >Lead.testShareRule

</members >

<name >SharingCriteriaRule </name >

</types >

<name >SharingOwnerRule </name >

</types >

<members >Account.* </members >

<name >SharingTerritoryRule </name >

</types >

<version >33.0

</version >

</Package >

Managed Component Access

In API version 29.0 and later, you can retrieve and deploy access settings for the following managed components in profiles and permission sets:

•

Apex classes

•

Apps

•

Custom field permissions

•

Custom object permissions

•

Custom tab settings

•

External data sources

•

Record types

•

Visualforce pages

When retrieving and deploying managed component permissions, specify the namespace followed by two underscores. Wildcards are not supported.

For example, let’s say you install a managed package with the namespace

MyNamespace

and the custom object

JobRequest__c

To set object permissions for

JobRequest__c

in the package to the custom profile MyProfile, you would add the following to the

.profile

file.

To deploy:

<viewAllRecords >false </viewAllRecords >

<modifyAllRecords >false </modifyAllRecords >

</objectPermissions >

Deploying and Retrieving Metadata Running Tests in a Deployment

To retrieve:

<members >MyNamespace__JobRequest__c </members >

<name >CustomObject </name >

</types >

<members >MyProfile </members >

<name >Profile </name >

</types >

When retrieving permission sets and profiles, make sure that you also retrieve any components that are related to the permissions and settings. For example, when retrieving app visibilities, you must also retrieve the associated app, and when retrieving object or field permissions, you must also retrieve the associated object.

Running Tests in a Deployment

Default Test Execution in Production

When no test level is specified in the deployment options, the default test execution behavior depends on the contents of your deployment package. When deploying to production, all tests, except those that originate from managed packages, are executed if your deployment package contains Apex classes or triggers. If your package doesn’t contain Apex components, no tests are run by default.

In API version 33.0 and earlier, tests were run for components that required tests, such as custom objects, and not only for Apex components. For example, if your package contains a custom object, all tests are run in API version 33.0 and earlier. In contrast, starting with API version 34.0, no tests are run for this package. The API version corresponds to the version of your API client or the version of the tool you’re using (Force.com Migration Tool).

You can run tests for a deployment of non-Apex components. You can override the default test execution behavior by setting the test level in your deployment options. Test levels are enforced regardless of the types of components present in your deployment package.

We recommend that you run all local tests in your development environment, such as sandbox, before deploying to production. Running tests in your development environment reduces the number of tests needed to run in a production deployment.

Default Test Execution in Production for API Version 33.0 and Earlier

For deployment to a production organization, all local tests in your organization are run by default. Tests that originate from installed managed packages aren’t run by default. If any test fails, the entire deployment is rolled back.

If the deployment includes components for the following metadata types, all local tests are run.

•

ApexClass

•

ApexComponent

•

ApexPage

•

ApexTrigger

•

ArticleType

•

BaseSharingRule

•

CriteriaBasedSharingRule

•

CustomDataType

•

CustomField

•

CustomObject

Deploying and Retrieving Metadata Running a Subset of Tests in a Deployment

•

DataCategoryGroup

•

Flow

•

InstalledPackage

•

NamedFilter

•

OwnerSharingRule

•

PermissionSet

•

Profile

•

Queue

•

RecordType

•

RemoteSiteSetting

•

Role

•

SharingReason

•

Territory

•

Validation Rules

•

Workflow

For example, no tests are run for the following deployments:

•

1 CustomApplication component

•

100 Report components and 40 Dashboard components

All tests are run for the following deployments:

•

1 CustomField component

•

1 ApexComponent component and 1 ApexClass component

•

5 CustomField components and 1 ApexPage component

•

100 Report components, 40 Dashboard components, and 1 CustomField component

Running a Subset of Tests in a Deployment

Test levels enable you to have more control over which tests are run in a deployment. To shorten deployment time to production, run a subset of tests when deploying Apex components. The default test execution behavior in production has also changed. By default, if no test level is specified, no tests are executed, unless your deployment package contains Apex classes or triggers.

If the code coverage of an Apex component in the deployment is less than 75%, the deployment fails. If one of the specified tests fails, the deployment also fails. We recommend that you test your deployment in sandbox first to ensure that the specified tests cover each component sufficiently. Even if your organization’s overall code coverage is 75% or more, the individual coverage of the Apex components being deployed can be less. If the code coverage requirement isn’t met, write more tests and include them in the deployment.

To run a subset of tests, set the

RunSpecifiedTests

test level on the

DeployOptions

object. Next, specify each test class to run in

DeployOptions

. Finally, pass

DeployOptions

as an argument to the deploy()

call. The following example performs those steps to run only the specified test classes.

// Create the DeployOptions object.

DeployOptions deployOptions = new DeployOptions();

Deploying and Retrieving Metadata Run the Same Tests in Sandbox and Production Deployments

// Set the appropriate test level.

deployOptions.setTestLevel(TestLevel.RunSpecifiedTests);

// Specify the test classes to run.

// String array contains test class names.

String[] tests = { "TestClass1" , "TestClass2" , "TestClass3" };

// Add the test class names array to the deployment options.

deployOptions.setRunTests(tests);

// Call deploy() by passing the deployment options object as an argument.

AsyncResult asyncResult = metadatabinding.deploy(zipBytes,deployOptions);

Notes About Running Specific Tests

•

You can specify only test classes. You can’t specify individual test methods.

•

We recommend that you refactor test classes to include the minimum number of tests that meet code coverage requirements.

Refactoring your test classes can contribute to shorter test execution times, and as a result, shorter deployment times.

•

You can deactivate a trigger in the target organization by deploying it with an inactive state. However, the trigger must have been previously deployed with an active state.

Run the Same Tests in Sandbox and Production Deployments

Starting in API version 34.0, you can choose which tests to run in your development environment, such as only local tests, to match the tests run in production. In earlier versions, if you enabled tests in your sandbox deployment, you couldn’t exclude managed package tests.

By default, no tests are run in a deployment to a non-production organization, such as a sandbox or a Developer Edition organization.

To specify tests to run in your development environment, set a

testLevel

deployment option . For example, to run local tests in a

deployment and to exclude managed package tests, set testLevel

on the

DeployOptions

object to

TestLevel.RunLocalTests

. Next, pass this object as an argument to the deploy()

call as follows.

// Create the DeployOptions object.

DeployOptions deployOptions = new DeployOptions();

// Set the appropriate test level.

deployOptions.setTestLevel(TestLevel.RunLocalTests);

// Call deploy() by passing the deployment options object as an argument.

AsyncResult asyncResult = metadatabinding.deploy(zipBytes,deployOptions);

Note: The

RunLocalTests

test level is enforced regardless of the contents of the deployment package. In contrast, tests are executed by default in production only if your deployment package contains Apex classes or triggers. You can use

RunLocalTests

for sandbox and production deployments.

Maintaining User References

User fields are preserved during a metadata deployment.

Deploying and Retrieving Metadata Maintaining User References

When a component in your deployment refers to a specific user, such as a recipient of a workflow email notification or a dashboard running user, then Salesforce attempts to locate a matching user in the destination organization by comparing usernames during the deployment.

For example, when you copy data to a sandbox, the fields containing usernames from the production organization are altered to include the sandbox name. In a sandbox named test

, the username [email protected]

becomes [email protected]

. When you deploy the metadata in the sandbox to another organization, the test

in the username is ignored.

For user references in deployments, Salesforce performs the following sequence:

1. Salesforce compares usernames in the source environment to the destination environment and adapts the organization domain name.

2. If two or more usernames match, Salesforce lists the matching names and requests one of the users in the source environment be renamed.

3. If a username in the source environment doesn’t exist in the destination environment, Salesforce displays an error, and the deployment stops until the usernames are removed or resolved to users in the destination environment.

Key features

Retrieve metadata from your org
Deploy metadata to your org
Create new metadata components
Update existing metadata components
Delete metadata components from your org
Supports both file-based and CRUD-based development
Complies with industry standards for web services
Provides comprehensive error handling

Frequently asked questions

Metadata API is supported in Enterprise, Unlimited, Performance, and Developer Editions. It is recommended to use a sandbox for testing changes before deploying to production.

File-based development involves deploying and retrieving metadata as a zip file containing XML files. CRUD-based development uses synchronous API calls similar to the enterprise WSDL.

You can use the Force.com IDE or Force.com Migration Tool, or directly interact with the API using SOAP calls. This documentation provides examples and guidance for both approaches.