First impression of new Metadata namespace

With the new release of Summer 17, metadata namespace now becomes available in sandboxes. And soon they will be available in Prod orgs. The aim of this change is to enable users to retrieve and deploy metadata via Apex code directly – without having to use Metadata Api.

This is a pretty exciting change! So I took some time to look into it and see how it works. And below is my first impression.

Retrieve a page layout

I used the below code to retrieve the Account page layout:

Metadata.layout attachmentLayout =  new Metadata.layout();
List<String> layoutList = new List<String>{'Account-Account Layout'};

List<Metadata.Metadata> components = Metadata.Operations.retrieve(Metadata.MetadataType.Layout, layoutList);
attachmentLayout = (Metadata.layout)components.get(0);

List<Metadata.RelatedListItem> relatedLists = attachmentLayout.relatedLists;

for(Metadata.RelatedListItem item: relatedLists)

You can try it and run it by yourself.

Some explanation of the code

In current version, when we retrieve or deploy some metadata, we need to use Metadata.Operations.retrieve (or deploy) method. The first parameter of retrieve method of an enum called Metadata.MetadataType. Currently it only has two available values – layout and customMetadata. CustomMetadata generally means custom object.

For CustomMetadata type, we basically can only retrieve values from it – which is a list of CustomMetadataValue objects. And CustomMetadataValue class has only two properties: field and value. We can definitely do a bunch of stuffs with those two fields. But it is definitely not as well supported as in Metadata Api.

Layout is better supported with many properties. So we can probably adjust our end users’ page layout automatically after they install the package – without having to use Metadata API. This is a big change. I have always wanted that feature.

However, as you can see from this, not many metadata types are supported. Many things, like Apex class, are not supported yet. I do believe this is only a beginning of the change. So we can keep a close look at this change.

Subscribe to Sfdcinpractice

Subscribe to get the latest blogs and tutorials of sfdcinpractice. No spam, no trash, only the awesome posts from sfdcinpractice. 


  1. Avrom Roy-Faderman - May 15, 2017 @ 11:12 pm

    Hi Lance,

    I’m curious what you mean by this: “But [custom metadata] is definitely not as well supported as in Metadata Api.” What differences do you see? The API for custom metadata should be exactly the same as in the metadata API except that the “protected” property is instead called “protected_x” (because “protected” is a reserved word in Apex).

    Any other difference is a bug and should be reported as such.

    • LanceShi - May 15, 2017 @ 11:26 pm

      Thank you for the comment Avrom. I do love the new metadata namespace feature Salesforce is providing and many thanks to that. What I mean here is not just the interface, not all the relevant support: documentation, other available types, etc. So from my understanding:

      1. It currently still lacks sufficient documentation. Metadata namespace used to be in Apex developer guide and I just checked it has just been removed.
      2. I believe custom metatadata is custom object. And in Metadata API we do have another metadata type called CustomObject which provides a whole bunch of interface.

      Let me know if it sounds right to you.

  2. Avrom Roy-Faderman - May 15, 2017 @ 11:39 pm

    Hi Lance,

    1. Is it possible that you were previously reviewing the early access/sandbox release of the documentation? The Metadata namespace is only available as of Summer 17, which means that most non-sandbox organizations don’t have it or the relevant documentation yet.

    2. Ah, I think I understand what you mean. You can’t currently load or edit a custom metadata *type* using the metadata namespace. But you can both load and edit records of custom metadata types–both their custom field values (which show up as CustomMetadataValues) and their standard field values (which are appropriately-typed properties on the CustomMetadata object itself).

    In other words, we completely replicate the functionality of the CustomMetadata component type in the MD API, but not CustomObject (including its use to define custom metadata types).

    • LanceShi - May 15, 2017 @ 11:46 pm

      Yes. I am reviewing it in my sandbox environment which has the early access to metadata namespace.

Leave a Reply

Your email address will not be published / Required fields are marked *