Salesforce Custom Metadata Types Explained

In the world of Salesforce development and administration, managing configuration data effectively is crucial. From storing business rules to defining app behavior, developers need a reliable way to store and deploy metadata-driven settings. Salesforce Custom Metadata Types (CMDT) provide a powerful, scalable, and deployment-friendly solution for this purpose.

This comprehensive guide explores what Custom Metadata Types are, how they differ from Custom Settings, their key benefits, and how to implement them effectively in your Salesforce environment.

What Are Custom Metadata Types?

Custom Metadata Types (CMDT) are custom-defined metadata objects that allow you to create, manage, and deploy configuration records just like standard metadata (such as objects, fields, and workflows). Instead of storing runtime data, Custom Metadata Types store application-level configuration and logic that you can use across environments.

For example, you might define a CMDT to store tax rates by region, feature toggles, or integration settings that remain consistent across orgs.

Unlike Custom Settings or Custom Objects, CMDT data can be packaged, version-controlled, and deployed using tools like Change Sets or Salesforce CLI (SFDX).

Why Custom Metadata Types Matter

In traditional Salesforce setups, developers relied on Custom Settings or Custom Objects to store configuration data. However, these options had limitations:

• Custom Settings could not easily be deployed with data.

• Custom Objects required manual data migration between environments.

Custom Metadata Types solve both problems. They allow you to define configuration schemas and deploy both the structure and data between orgs seamlessly.

Key Use Cases

• Storing business rules or mapping logic.

• Managing integration configurations (like API keys or endpoints).

• Defining field validation rules or dynamic picklist values.

• Implementing feature flags for conditional behavior.

• Managing dynamic UI visibility or process triggers.

Custom Metadata vs. Custom Settings vs. Custom Objects

To understand CMDT’s power, it’s important to compare it with other Salesforce data storage types.

From this comparison, it’s clear that Custom Metadata Types combine the best of both Custom Settings and Custom Objects, making them the preferred choice for configuration-driven logic.

Components of Custom Metadata Types

A Custom Metadata Type is made up of two primary parts:

1. Metadata Type Definition: The schema that defines the fields (like an object).

2. Metadata Records: The individual configuration records created under the type.

For example, you can create a CMDT called Payment_Config__mdt with fields like:

• Payment_Method__c

• Gateway_URL__c

• Is_Active__c

Then, create records such as PayPal Config or Stripe Config, which define values for these fields.

How to Create a Custom Metadata Type

Let’s go step-by-step on how to create and configure a CMDT in Salesforce.

Step 1: Create the Metadata Type

1. Go to Setup → Custom Metadata Types.

2. Click New Custom Metadata Type.

3. Enter:

   • Label: Payment Configurations

   • Object Name: Payment_Config

   • Description: Stores settings for payment gateway integrations.

4. Save the record.

Step 2: Add Custom Fields

1. Under Custom Fields, click New.

2. Create fields like:

   • Payment Gateway URL (Text)

   • API Key (Text)

   • Active (Checkbox)

3. Save your fields.

Step 3: Create Metadata Records

1. Go to Setup → Custom Metadata Types → Manage Records next to your type.

2. Click New Record and fill out your configuration values.

3. Create multiple entries for different configurations as needed.

Step 4: Access Custom Metadata in Apex

You can query Custom Metadata just like any other SObject, or access it using built-in methods.

Example: Using SOQL

List<Payment_Config__mdt> configs = [SELECT MasterLabel, Payment_Method__c, Gateway_URL__c, Is_Active__c FROM Payment_Config__mdt];

Example: Using getAll()

Map<String, Payment_Config__mdt> paymentMap = Payment_Config__mdt.getAll();
Payment_Config__mdt paypalConfig = paymentMap.get('PayPal_Config');
System.debug(paypalConfig.Gateway_URL__c);

The getAll() method retrieves all CMDT records without the need for SOQL queries, improving performance and avoiding governor limits.

Benefits of Using Custom Metadata Types

1. Easy Deployment

CMDTs can be deployed between orgs using metadata deployment tools, ensuring configuration consistency across environments.

2. Version Control Friendly

Since CMDT records are treated as metadata, they can be stored in version control systems like Git.

3. Performance Optimization

Unlike Custom Objects, CMDTs don’t consume data storage and can be accessed without query limits.

4. Secure and Configurable

CMDTs can be referenced in formulas, flows, and Apex without exposing sensitive information to end users.

5. Great for Managed Packages

ISVs (Independent Software Vendors) can package CMDTs with their apps to ensure out-of-the-box configuration deployment.

Using Custom Metadata in Automation

Custom Metadata Types can be leveraged not just in Apex but also in declarative tools.

In Flow

You can use CMDT records directly in Flow Builder using the “Get Records” element to dynamically drive decisions.

In Validation Rules and Formulas

CMDTs can be referenced in formulas, making your logic flexible and easier to maintain without hardcoding values.

Example formula:

IF( Account.Industry = $CustomMetadata.Industry_Mapping__mdt.Finance__c.Industry_Name__c, true, false)

This ensures that logic changes can be made without editing formulas every time.

CMDT Deployment Best Practices

1. Use Meaningful Names: Make sure your metadata type and record names are self-explanatory.

2. Version Control: Always track CMDT records in Git to maintain history and rollback options.

3. Limit Data Volume: CMDTs are not meant for storing large datasets—keep records minimal.

4. Avoid Hardcoding: Use CMDTs for dynamic logic instead of hardcoding values in Apex or Flow.

5. Test in Sandboxes: Always deploy CMDTs first in a sandbox to ensure they work correctly before pushing to production.

CMDT vs. Custom Labels

Although Custom Labels can store configurable text or keys, CMDTs provide more flexibility because they can store multiple fields and records with structured data.

Use Custom Labels for translatable UI text, and Custom Metadata Types for structured configuration data.

Real-World Example: Feature Toggle Management

Imagine you have multiple features in your Salesforce app, and you want to enable or disable them dynamically.

Step 1: Create CMDT

Create a Custom Metadata Type named Feature_Toggle__mdt with fields:

• Feature_Name__c (Text)

• Is_Enabled__c (Checkbox)

Step 2: Create Records

• Feature: Email Notifications → Enabled

• Feature: Auto Assignment → Disabled

Step 3: Reference in Apex

Feature_Toggle__mdt feature = Feature_Toggle__mdt.getInstance('Email_Notifications');
if (feature.Is_Enabled__c) {
    sendEmailNotification();
}

This setup allows you to enable or disable features without modifying code or redeploying packages.

Limitations of Custom Metadata Types

While CMDTs are powerful, they have a few constraints:

• You cannot create them dynamically via Apex at runtime.

• Limited record size (up to 1 MB total metadata size per org).

• Cannot be modified by end users through standard UI pages (requires Setup access).

Conclusion

Salesforce Custom Metadata Types represent a major leap in how configuration data is handled across environments. They offer the flexibility of Custom Objects, the deployability of metadata, and the efficiency of system-level storage.

By using CMDTs, developers and admins can manage reusable configurations, simplify deployments, and ensure consistency across sandboxes and production. Whether you’re managing feature flags, integrations, or business logic, CMDTs are an indispensable tool in your Salesforce toolkit.

In essence, Custom Metadata Types help you build smarter, maintain cleaner, and deploy faster—making your Salesforce applications more scalable and future-proof.