Free tools Windows power users keep installed
One-click scans. No signup required.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Salesforce Custom Metadata Types let you store deployable configuration records separately from Apex code, then have Apex, formulas, or other supported consumers read those records to guide behavior. They work well for stable mappings and rules that should travel with an application; they are not a general-purpose runtime database or a safe place for secrets in every packaging context.
What Custom Metadata Types do
A Custom Metadata Type defines the fields for configuration records. Application logic reads those records and uses their values instead of embedding every changeable value as a literal in Apex. Salesforce describes custom metadata as “customizable, deployable, packageable, and upgradeable application metadata.” Salesforce Help: What are Custom Metadata Types?
The distinction is useful: the type is the schema, its records are the configuration, and Apex or another consumer interprets the records. Updating a mapping or threshold can then be a metadata change rather than a code edit, provided the application was designed to read that value.
When configuration records are a good fit
Salesforce’s examples include mappings, business rules, primary data, and allowlists. Typical patterns include:
#1 Best Overall
- Mappings: Map cities or provinces to regions, or connect an application key to a configured value.
- Routing: Store payment endpoint selection data in configuration while Apex performs the routing behavior.
- Business rules: Store charges such as duties or VAT, or thresholds that reusable logic evaluates.
- Allowlists: Maintain the permitted values or entities that application logic checks.
Use the type to centralize values that are stable enough to deploy and package. It is not automatically the right home for every setting: decide based on whether values need to travel as metadata, who must change them, whether code must mutate them at runtime, and whether they contain sensitive information.
How to create, populate, and deploy a type
Salesforce supports managing custom metadata types and records in Setup or through the Metadata API. Records can move with application metadata through packages or Metadata API deployment, and Salesforce also documents change-set deployment. Apex can query accessible records using SOQL. Salesforce Help: Create, Edit, and Delete Custom Metadata Types and Records
- Define the Custom Metadata Type and its fields in Setup, or create them through your Metadata API workflow.
- Create records for the values the application needs. Keep record names and field meanings clear so admins and developers can identify the intended configuration.
- Update the Apex, formula, Flow, or other consumer to read the records and apply the values; do not assume that creating metadata changes existing hard-coded logic.
- Deploy the type and its records using the application’s established metadata process, package, Metadata API deployment, or a supported change set.
- Verify the consuming code or interface can see the records in its actual execution and package context.
Read records from Apex and formulas
Apex
Apex can query accessible custom metadata records with SOQL. Salesforce documents programmatic access and the conditions under which Apex can read or update subscriber-controlled records visible within the code’s namespace. Salesforce Help: Access Custom Metadata Records Programmatically
Recommended Free Tools
Do not design ordinary runtime DML around these records. Apex cannot delete custom metadata records, and DML operations on custom metadata are not allowed in Partner or Enterprise APIs. Plan changes through metadata workflows rather than treating the records as mutable transactional data.
Formulas
Salesforce formula fields can reference a record using the pattern $CustomMetadata.CustomMetadataTypeAPIName.RecordAPIName.FieldAPIName. For example, a formula can read a minimum or maximum value from a metadata record instead of repeating a threshold in multiple formulas. Long text area fields are not supported in formula references. Salesforce Help: Custom Metadata Types and Advanced Formula Fields
Use relationships and validation where they help
Custom metadata relationships can reference other metadata entities and definitions. When a direct reference fits the model, Salesforce recommends relationships over storing the reference as plain text; relationships can simplify Apex and provide referential integrity in packaging. Custom metadata types also support validation rules. Salesforce Help: Custom Metadata Types
Visibility, packaging, and privacy
Salesforce documents Public, Protected, and PackageProtected visibility. Public types can be accessed by Apex, formulas, and Flows; API access is subject to the relevant permissions. Protected types in managed packages restrict access to code in the same namespace. PackageProtected types in second-generation managed packaging restrict access to code in the same package. Check the exact access rules for the packaging model and consumer involved. Salesforce Help: Protection and Privacy Options for Custom Metadata Types and Salesforce Help: Access Rules When Packaging Custom Metadata Types and Records
An unpackaged protected type is not a secrecy boundary: Salesforce says protected custom metadata types behave like public types outside a managed package. Do not store secrets, personally identifying information, or other private data in public or unpackaged protected records. Salesforce identifies protected custom metadata in a managed package as an option for certain secrets; outside that context, its guidance points to named credentials or encrypted custom fields for confidential values.
Best Value
Setup counts and records visible through an API or consuming interface may differ because visibility and user permissions affect what is returned. Salesforce also distinguishes system-mode Apex from user-mode surfaces. Check the execution context of the actual consumer rather than assuming one access rule applies everywhere.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Understand query limits and runtime behavior
Custom metadata SOQL supports a subset of query syntax. Salesforce documents restrictions involving compound OR filters, relationship ordering, and multiple FROM objects. The limitations documentation says Apex queries against custom metadata do not count toward standard SOQL row limits as described there; Salesforce’s allocations guidance says custom metadata queries in Flows count toward Apex governor limits. These details are not a general guarantee of speed or unlimited scale. Salesforce Help: Custom Metadata Types Limitations and Salesforce Help: Custom Metadata Allocations and Usage Calculations
Quick Recap
Decide whether a value belongs in custom metadata
- Choose it when the records should be deployable or packageable with the application and the consuming logic can read them.
- Check whether subscribers or administrators need to change values independently after deployment.
- Use another approach if the application requires ordinary runtime creation, deletion, or transactional updates to the values.
- Confirm whether package protection is needed and whether the type’s visibility actually provides it in the deployment context.
- Keep confidential or personally identifying data out unless the specific protected managed-package approach is appropriate.
- Validate access and query behavior for each consumer—Apex, formulas, Flow, or APIs—rather than assuming they share identical permissions and limits.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors
