Introducing the Apex Metadata API

I am pleased to announce the debut of the Apex Metadata API for Force.com.

Our developer community–and partners in particular–pushed hard for this feature. As apps built on Salesforce become increasingly sophisticated, developers need to build equally sophisticated setup experiences that reflect the uniqueness of their products. Developers also want to build more powerful post-install and upgrade scripts. The new Apex Metadata API is the tool to do all this.

The value of this feature is demonstrated by the demand we see in various channels:

• In IdeaExchange, Andy Fawcett’s Idea for this feature has well over 7,000 points—a remarkable figure for a largely ISV-oriented developer feature.
• In GitHub, the Apex Metadata API wrapper Andy created to help developers build their own solution stands out among the nearly 800 Apex language repos. It has three times the forks and more stars than the next repo, and it dominates most others.

This inaugural release of the Force.com native Apex Metadata API begins to address this demand.

What all the fuss is about

As we’ve learned from many of you through your contributions to the IdeaExchange, the three key use cases for the Apex Metadata API are:

• Self-configuring apps
• Upgrade scripts
• Custom setup UIs

These three use cases fall into two major categories: setup UIs and automation scripts.

Build custom setup UIs

ISVs’ desire to build custom setup UIs for their apps drives nearly half the demand for the Apex Metadata API.

Setup wizards are intended to guide an administrator through a series of steps that are logically consistent with what the admin intends to build or customize. For example, if I want to add a custom field to an object in Salesforce I can go to setup, find an object such as Account in the Object Manager, navigate to Fields & Relationships, click New, and follow the rest of the steps in the wizard. My setup experience reflects the change I expect to see in my app.

For an ISV app, however, adding a single component can involve creating multiple customizations to Salesforce. And the places I need to make those changes may not logically map to the end result I intend to achieve.

Developers want to provide admins with setup experiences specific to the app they are configuring. With the Apex Metadata API, now they can build setup UIs that guide admins through whatever process or flow makes the most sense for their apps. This UI will use Apex to make configuration changes through the Metadata API that previously would have been done manually in Salesforce setup.

Automate configuration changes

Demand is also driven by the need for tools to automate configuration changes. Much of this demand stems from a desire to have post-upgrade scripts make changes to an installed app. If a package upgrade includes a new field, for example, the Apex Metadata API can be used to add that field to page layouts.

Demand is further driven by the desire to automate some of the customization after an app is installed. Post-install scripts can look at the configuration of a subscriber org and configure the installed package based on how the org is set up. Along with custom setup UIs, this drastically reduces and simplifies the work an admin needs to do.

Why ISVs will love this

If you are a developer at an ISV, creating setup UIs specific to your apps and automating configuration changes can provide a big boost to your business. It can help you:

• Save money for you and your customers by making the setup experience faster and easier for non-experts.
• 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.
• Eliminate reliance on remote site settings, reducing the complexity of your code and simplifying customers’ setup.

Why enterprises will love this

While demand for this feature is heavily driven by ISVs, the use cases are not limited to partner apps. Enterprises want to build tools that automatically make config changes when changes are made elsewhere. These can be manual changes made by an admin that trigger updates to other metadata—easily achieved with a simple wizard. Or they can be changes to systems integrated with Salesforce that then update Salesforce metadata.

Looking ahead

What’s coming in the Summer ’17 release

We built the Apex Metadata API because we agree “this will be revolutionary for app developers.” Building custom setup wizards, self-configuring apps, and post-install scripts that can update metadata provides ISVs and enterprise developers tremendous new power to simplify app configuration. You and your admins can save time and money, reduce errors, and create new business opportunities.

Here’s what you can do in this debut release:

• Access two metadata types: page layouts and records of custom metadata types
• Retrieve their metadata synchronously
• Create and update their metadata via asynchronous deploy
• Setup a callback on completion
• Trust your apps: installed packages must be “ApexCertified” or the subscriber org must turn on a setting to allow an Apex metadata deploy
• Track the namespace that initiated a deploy in the setup audit trail

Current limitations

However, like all first release features, this one has some limitations. Here are the key ones:

• In this release we support two metadata types: page layouts and the records of custom metadata types.
• Read, create, and update are supported. Delete is not supported.
• We don’t yet have a deploy status API (though we do have a callback upon completion of the deploy).
• This is not intended for unit tests. The Apex Metadata API uses an asynchronous deploy, which is not compatible with Apex’s synchronous tests.

You can help us close the first gap. Join the Apex Metadata API group in the Success Community. Tell us what metadata types you need supported and why. The more specific you make your use cases the better.

And while you’re there, tell us how you’re planning to use the current features.

Finally, keep an eye out for a Trailhead module with a lot more detail on this powerful new capability.

Thank you

I’d like to thank some of the people who made this new API possible.

Thank you Andy Fawcett for posting the idea in IdeaExchange, for developing the GitHub library that helped demonstrate the use cases and demand, and for being such a visible and vocal advocate for this feature.

Thank you Bas Visser, Jorrit Droogsma, and the entire StepOrange team for providing such great use cases. These often helped me explain the value of this product and drive requirements discussions.

Thank you to the Force.com engineering team that delivered this feature! I laid out a very ambitious goal and you knocked it out of the park, delivering both the basic requirements and much more in a single release. You are all amazing.

About the author

Aaron Slettehaugh is senior director of product management for the Salesforce platform. He has launched several products beloved by Salesforce developers, including custom metadata types and now the Apex Metadata API.

Before joining Salesforce, Aaron helped launch the global operations of an African NGO, led the product team at IaaS provider Joyent, and started a company and led it to acquisition by Citrix. He has an MBA from Stanford University and a bachelor in engineering.