Get Started with Apex Metadata API

Learning Objectives

After completing this unit, you’ll be able to:
  • Identify use cases for Apex Metadata API.
  • List the main features and limitations of Apex Metadata API.

Get Started with Apex Metadata API

Say you’re a Salesforce developer or ISV, and you’ve created a cool new customization for your app that includes some metadata changes. To roll out this feature to the orgs you support, you write a set of instructions for your admins so they can make the updates. The instructions walk them through the changes to make in various places in the Salesforce Setup UI. Does this sound all too familiar? Unless you really love technical writing (like we do at Salesforce), wouldn’t it be nice to have an easier way to make your updates?

The good news is that you can improve this process by using Apex Metadata API. The API lets you make metadata changes directly from Apex. So, you can use all the handy features of Apex to build custom setup UIs that update metadata behind the scenes. You can also automate configuration changes this way. Let’s look in-depth at some examples using Apex Metadata API.

What Can This API Do for Me?

Let’s say that you support multiple orgs, and you’ve created a custom field. You want to add your new field to the page layouts in all your orgs. This type of configuration information is stored in metadata types and components in your org.

You can create a script that uses Apex Metadata API to add your new field to the page layouts in all your orgs directly from Apex. The metadata in the orgs is updated behind the scenes, so that your admins don’t have to make manual changes in each org.

Image showing change in one org being rolled out to other orgs.

Apex Metadata API also enables you to build custom setup experiences for your features. For example, let’s say you’ve created custom metadata types to support a new feature. The records of your custom metadata types must be configured differently for different countries. You can use Apex Metadata API to build a setup wizard that guides admins through a series of steps to configure the records. This automation saves your admins from having to make manual changes in the Setup UI.

Image of a generic wizard.

Work with Metadata Directly from Apex

To work with metadata from within Apex code, use classes in the Metadata namespace. You can access two top-level metadata types: page layouts and records of custom metadata types, which gives you the ability to handle much of the customization and configuration for your org.

So, what kinds of things can you do with the Apex Metadata API? You can retrieve metadata from an org synchronously. Then you can inspect this metadata and update it, and you can also create metadata. It’s easy to deploy your updated metadata to your orgs, using asynchronous deployment. To be notified when your deployment completes, you can implement a callback.

Let’s take a sneak peek at a little Apex code to see what Apex Metadata API can do. The following snippet uses the Metadata.CustomMetadata class to create a record of a custom metadata type. We can deploy this new record to an org directly from Apex, as we see later in this module.

Metadata.CustomMetadata customMetadata =  new Metadata.CustomMetadata();
customMetadata.fullName = 'MyNamespace__MetadataTypeName.MetadataRecordName';
Metadata.CustomMetadataValue customField = new Metadata.CustomMetadataValue();
customField.field = 'customField__c';
customField.value = 'New value';

Although there’s a lot you can do with Apex Metadata API, there are some limitations to keep in mind.

  • In the current release, we support only two metadata types: page layouts and the records of custom metadata types.
  • Reading, creating, and updating metadata are supported, but deleting metadata is not supported.
  • We don’t have an API that lets you track the status of a deployment. However, you can set up a callback that is called when the deployment completes.

What About Security?

Metadata is powerful stuff. So perhaps you’re concerned about security. Don’t worry! Trust is our number one value at Salesforce, and Apex Metadata API is built to be a trusted interface. Installed packages must be Apex-certified, or the subscriber org must turn on a setting to allow an Apex metadata deployment. You can track the namespace that initiated a deployment in the Setup audit trail.

We talk about security in more detail in an upcoming unit, after you’ve had a chance to see what Apex Metadata API can do.

A Note for ISVs

Although the examples in this module focus on enterprises, Apex Metadata API can also be useful if you’re a developer at an ISV. Creating setup UIs specific to your apps and automating configuration changes can provide a boost to your business. With Apex Metadata API you can:

  • Save money for you and your customers by making the setup experience faster and easier for nonexperts.
  • Eliminate some setup steps entirely by automating them.
  • Provide admins the capability to change configuration on the fly by giving them a tool they can use without professional services expertise.
  • Increase product adoption by lowering the barrier for customers to try your app.
  • Protect your intellectual property. The ability to update protected metadata in your app means you can hide more of your configuration from customers.
  • Eliminate reliance on remote site settings, reducing the complexity of your code and simplifying customers’ setup.


Trailhead: Custom Metadata Types

Salesforce Developers Blog: Introducing the Apex Metadata API

Salesforce Documentation: Apex Developer Guide

Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities