Admins / Developers

Introduction to Custom Metadata Types in Salesforce

By Andreea Doroftei

Before the Summer ’15 release, the Salesforce Developer Community could only create metadata for the objects provided by Salesforce. Whether adding custom fields to one of the standard objects, creating a new custom object altogether, or developing an Apex class, one could only configure applications in ways that Salesforce provides out of the box.

With the introduction of custom metadata types, both admins and developers have the ability to create their own configuration and application metadata, deploy it, and then update it as needed within the custom metadata types.

Steps for Creating Custom Metadata Type

This functionality is recommended by Salesforce for the following use cases:

  • Mappings: Create associations between different objects, such as custom metadata types that assign cities, states, or provinces to particular regions in a country.
  • Business Rules: Combine configuration records with custom functionality. Use custom metadata types along with some Apex code to route payments to the correct endpoint.
  • Master Data: You can create a custom metadata type that defines custom charges, like duties and VAT rates. If you include this type as part of an extension package, subscriber orgs can reference the master data.
  • Whitelists: Manage lists, such as approved donors and pre-approved vendors.
  • Secrets: Store information (like API keys) in your protected custom metadata types within a package.

Before starting on your journey to create a custom metadata type, keep in mind to ensure that you have the right permissions. Realistically speaking, admins should be the users creating these records, hence why either the “Customize Application” or “Author Apex” permissions for programmatic access are needed.

Additionally, other users can and should (in some instances) have the permissions to view these records. This can easily be controlled either through profiles or, even better, through permission sets for each custom metadata type.

Define A Custom Metadata Type Declaratively

Creating is a walk in the park once you decide to go the custom metadata route instead of, for example, creating multiple fields on different objects to store certain information.

After navigating to “Custom Metadata Types” and clicking the “New Custom Metadata Type” button, you will be prompted to fill in the name and description, and decide on the visibility settings.

Create All Custom Fields You Need

Although the creation of the custom metadata type was simple, creating the fields might be tricky depending on what your use case is – just like on any other Salesforce object you’ve worked with in the past.

Since my example of custom metadata type will hold the Country Code for each Country, I decided to create a Country Code custom field – but in this instance, to use the Label as the Country’s name. You will notice that the custom field does have the “__c” suffix, while the custom metadata type itself has the “__mdt” suffix, unlike any other object.

The similarities to a custom or standard Salesforce object don’t end here. You can also create list views, validation rules, as well as page layouts. Following the creation of the new Country Code field, I also edited the layout and marked the field as required.

Not only can you create some of the field types you could on a custom object, such as picklist, number, or even text – but while a master-detail relationship field is not an option, the Metadata Relationship field type is. This can unlock a whole lot of other possibilities through a relationship to another custom metadata type or entity definition.

Get hands-on with metadata relationship fields by going through this dedicated Trailhead module!

Add or Edit Custom Metadata Records Declaratively

Now that you have the basis of the ‘object’, let’s go ahead and create some records! Once again, you will have to search Setup for “Custom Metadata Types”.

However, this time, since the custom metadata type already exists, click “Manage Records” next to the one you wish to modify the records for.

The “Protected Component” checkbox determines whether the record is protected or not. A protected record is only accessible to code in the same namespace as either the record or its associated custom metadata type – the code you create, code in an unmanaged package, and code in the same managed package as either the protected record or its custom metadata type. Once it’s all done, click “Save”.

Mass Insert or Update Custom Metadata

Creating or updating multiple custom metadata records at the same time is certainly a tricky one, considering it can be done declaratively in Setup out of the box. As you can imagine, if you have to modify or create many records manually, it can become a tedious task really fast.

Although the Custom Metadata Loader has been around for a long time now, it is still a very fast way to import multiple records from a CSV file in your Salesforce org.

This is an admin-friendly approach, considering that once deployed, access to this functionality is controlled through a permission set, and custom metadata type records can be created – or, why not, even updated. Admins can update dozens of records in minutes directly in their sandbox.

You can get the Custom Metadata Loader along with the instructions here.

As of Summer ’20, CLI commands became generally available to manipulate custom metadata type records, making it much easier for developers to create new records or fields. Additionally, records can also be directly created from a CSV file, hence removing the need to do so unless only a couple of new ones are needed. Make sure to check all commands, as well as examples, here.

Deploy Custom Metadata Types

One of the advantages of custom metadata types is the fact that they are fully deployable and packageable. You can easily deploy them with change sets if that is a functionality you are still actively using for admins to move components between environments, or you could directly retrieve and deploy to the desired org using Metadata API.

Let’s see how the records we just created look like as XML files when exploring them using the brand new Code Builder.

Note: If needed, just as you would in VSCode, you can edit the files, save your changes, or when it makes sense – overwrite them with the metadata in your org.

READ MORE: Salesforce Code Builder – The Developer Productivity Tool

Advantages of Custom Metadata Types

Now that you’ve seen exactly how you could potentially work custom metadata types and how you would manage them, let’s go through some of the advantages of actually using this functionality.

Supports Complex Data Types

As I mentioned above, and as I can’t stress the importance of this possibility enough – you can go as simple or as complex as you’d like since you can create fields to store your data directly on the custom metadata type. Admins can manage the records, while users can also access it if needed.

The following field types can be created:

  • Metadata Relationship
  • Checkbox
  • Date and Date/Time
  • Email and Phone
  • Number
  • Percent
  • Picklist
  • Text and Text Area
  • URL

Can Be Referenced in Formula Fields, Validation Rules, Apex, and Flows

As you may already know, or perhaps would have guessed so far – all this information stored within the custom metadata type can be further used within processes across your entire Salesforce org. Be it declarative functionality, such as validation rules or Apex classes – the records are there, ready to be used.

In the example below, the custom metadata type “Sales Engineers” was created as users were manually added to Account Teams from an Excel spreadsheet.

At the moment, there is one sales engineer defined per Industry, and every Industry will have a sales engineer assigned – however, more criteria might appear in the future. As we already know, an additional custom field can be created if needed.

For now, we will leverage the information we have – the Industry, to assign the sales engineer to the account whenever an account is created and the Industry is not blank. Since every organization and requirement is different, you may use a different approach and entry criteria, as well as other custom field(s) on the custom metadata type.

Note: The tutorials we showcase are built in Developer Edition orgs with limited data and only a few custom automations. Ensure you evaluate your existing processes properly before building new ones, including both declarative automations and custom Apex. For Flow specifically, consider the recommended best practices when it comes to the number of record-triggered flows per object.

Make Changes in One Place

Here we are, leaving the best for last! The fact that you don’t have to maintain data across multiple Salesforce objects and not have to hard-code Ids is a win! On top of that, you can have information that may have been stored outside of Salesforce created in a simple and organized manner directly within Salesforce.

Additionally, regardless of the process or use case for which you will leverage custom metadata types – since they are deployable, it also means that the entire functionality can be properly deployed and tested, without spending time recreating the records in each Salesforce org.

Considerations of Using Custom Metadata

  • You can create up to 200 custom metadata types per Salesforce org.
  • You can create up to 100 custom fields for each custom metadata type object.
  • Custom metadata types are not supported in muting permission set (this is something I was interested in, but sadly it is not yet available).
  • Don’t forget to take a look at all the other limitations before leveraging the custom metadata types.


If I had to explain, in only one word, what custom metadata types help with – it would be scalability. Especially in complex organizations, when delivering robust implementations (be it as a package or as part of a custom solution built for a specific business need), this Salesforce functionality can help you save time and customize process behavior declaratively while ensuring governance over key data points.

What will you be using custom metadata types for? Don’t forget to share your thoughts in the comments below!

The Author

Andreea Doroftei

Andreea is a Salesforce Technical Instructor at Salesforce Ben. She is an 18x certified Salesforce Professional with a passion for User Experience and Automation. 

Leave a Reply