Skip to main content

Use Metadata Relationship Fields

Learning Objectives

After completing this unit, you’ll be able to:

  • Use metadata type relationship fields when needed.
  • Declaratively define a custom metadata type with a relationship field that references another custom metadata type, the entity definition, or a field definition.
  • Add records to custom metadata types that have relationship fields.



This unit assumes that you understand the fundamentals of Custom Metadata Types and have completed Custom Metadata Types Basics. This module builds on the concepts and examples in the Custom Metadata Types Basics module.

As you already learned in Custom Metadata Types Basics, the flexibility and declarative options of the custom metadata types feature save you time. Now let’s see how we can use metadata relationship fields to look up records of other custom metadata types, entity definitions, or field definitions.

Metadata relationship fields work like relationship fields for standard or custom objects. But because they are custom metadata types, they have the same benefits of application configuration data—the best of both worlds, which is nice because our customers like flexibility. Let’s check it out.

Our Use Case

In the previous module, we created a custom metadata type to store configurations for different support tiers, such as minimum spending required to qualify for a specified tier and a default discount that is provided for each tier. We also created a picklist field on Account to indicate what support level a particular account qualifies for. This solution can work for a smaller organization, but what if you have a larger company with more complicated requirements? For example, if the support tier names in the picklist field on Account are different from the support tier names in the custom metadata type records, then we can't map the picklist values to the custom metadata type records. And if we include another object with support tiers, it becomes even more complicated.

Acme Services recently started offering more support products, such as a dedicated phone number for premium customers. They want to tie it to the existing support tier configuration. This is where custom metadata type relationships help. Custom metadata types support three types of relationships:

  • Relationship to another custom metadata type
  • Relationship to an EntityDefinition (such as a custom or a standard object definition)
  • Relationship to a FieldDefinition (for both custom and standard fields)

Let’s see how these different types of relationships can help us manage Acme Services support information more easily.

The Big Picture

Let’s set up the data model for the support product.


What we’ll do

Store information about available support products.

Create a custom object called Support Product.*

Map support tier configurations to support product requirements.

Create a custom metadata type called Support Level Mapping, with three metadata relationship fields.

*Why create a Support Product custom object rather than a custom metadata type? Different orgs have different products; specific products are not app configuration data, and they shouldn’t be migrated as part of a package update or installation.

Create a Custom Object and Fields

Let’s create the custom object and fields that use metadata relationships. For a refresher on custom object and field creation, go to the Data Modeling module.

  1. In Setup, create a custom object called Support Product.
    1. Scroll down to the bottom of the creation page and select Launch New Custom Tab Wizard after saving this custom object, then click Save.
    2. Select a tab style and click Next.
    3. Make sure that the tab visibility is set to Default On for all profiles and click Next, then click Save.
  1. In Setup, customize the Support Product object and add a custom picklist field called Support Level.
  2. Define three values for the picklist field: Free, Premium, and VIP.
  3. Add support product records. Make sure to enter data in the Support Product name and the Support Level fields.

Support Product

Support Level

Dedicated Phone Line


Online Chat


Email Support


Now let’s see how we can map the Support Product custom object’s Support Level field to our existing support tiers.

Create a Custom Metadata Type with Relationship Fields

Create a custom metadata type named Support Level Mapping and add four fields.

  1. From the Support Level Mapping detail page, scroll to the Custom Fields section and click New.
  2. Choose Metadata Relationship for the field type and click Next.
  3. In the Related To dropdown list, select Entity Definition and click Next.
  4. Enter Support Tier Object for the field label and Support_Tier_Object for the field name.
  5. Click Next and then Save.

Woohoo! You just created your first metadata relationship field! Now let’s create three more fields so that you have the following four fields.

Field Label

Field Name

Field Type

Other Options

Support Tier Object


Metadata Relationship

Related To: Entity Definition

Support Tier Field


Metadata Relationship

Related To: Field Definition.

Controlling Field: Support Tier Object

Support Tier


Metadata Relationship

Related To: Support Tier (custom metadata type)

Support Tier Name



You now have the Support Level Mapping custom metadata type. Custom metadata types without records aren’t useful, though. Let’s add some data.

Create Custom Metadata Type Records

Add a record to the Support Level Mapping custom metadata type.

  1. In the Support Level Mapping detail page, click Manage Support Level Mappings.
  2. Click New.
  3. Label your record Free - Support Product.
  4. For Support Tier Object, select Support Product.
  5. For Support Tier Field, enter Support Level.
  6. For Support Tier, select Bronze.
  7. For Support Tier Name, enter Free.
  8. Click Save.

The Free - Support Product record maps the Free value (in the Support Level picklist on the Support Product custom object) to the Bronze support tier.

Add mappings for the Premium and VIP tier products.

Now the relationships can be used within your Apex code to provide an even more enhanced user experience for Acme Services.


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities