Learn MOAR with Winter ’21: Migrate sObjects to Custom Metadata Types Using CLI

Follow and complete a Learn MOAR Winter ’21 trailmix for Admins or Developers by October 30 to earn a special community badge and enter for a chance to win one $200 USD Trailhead Cert voucher.

Join us and discover the new Winter ‘21 Release features for Admins and Developers. We know each release brings with it lots of amazing, new functionality and there can be a lot to digest. With Learn MOAR, we’re packaging the release and bringing it to you in an easy-to-digest format.

Learn MOAR

It’s easy to get started. First, dive into the Trailhead trailmixes with key release highlights for Admins, Developers, or both! (Don’t forget to hit Follow.)

Then, check in over the next few days to read our favorite Winter ’21 Release features on both the Salesforce Admin and Salesforce Developer blogs.

Be sure to follow and complete the trailmixes by October 30, 2020 to earn a special community badge and enter to win one of five cert vouchers.

Migrate sObjects to custom metadata types using CLI

The wait is over! We are excited to share that with the Salesforce CLI release v49, you can now take advantage of the CLI for custom metadata types. We’ve released five shiny new commands in the force:cmdt plugin, that will allow you to create custom metadata types and insert records into them via the Salesforce client.

SFDX CLI provides developers with a unified experience when going through the Salesforce development lifecycle. By adding the force:cmdt plugin, you can now leverage the CLI tool when working with custom metadata for your packages and orgs.

What are custom metadata types anyway, and why should I use them?

Custom settings and custom objects can be used to create custom sets of data or to create and associate custom data for an org, profile, or user. This custom data can store configurations, mappings, or secrets. But what happens when you want to migrate these packages between orgs? The configurations are lost. This is because custom settings store that information as data, which can’t be moved between environments or orgs. The data needs to be downloaded from the source org and uploaded to the new org as a post-deploy operation.

Custom metadata types allow you to create customizable, deployable, package-able, and upgradeable application metadata so that you can store the custom data as metadata rather than data. They are a powerful tool for defining application configurations that need to be migrated from one environment to the other, or packaged and installed, just like any other standard Salesforce metadata. You can use custom metadata types to store application mappings, business rules, secrets, allowed lists and so on. With Winter ‘21, you can now move them smoothly between orgs in a single step.

There are even more advantages of using custom metadata over custom settings:

  • Metadata Relationships to other custom metadata types, Entity Definition, Field Definition and Entity Particles
  • Custom metadata types support Picklist fields, long text areas, page layouts, and validation rules
  • Apex tests can see the records of custom metadata even with “SeeAllData=False”

But I have packages already built using custom objects and/or custom settings! How do I migrate now with the least effort?

We have the perfect solution for you! You can effortlessly migrate your existing sObject (custom object or custom setting) to a custom metadata type by using the following command:

  • sfdx force:cmdt:generate
    The default directory is force/app/main/default/customMetadata.

And by using this command, you don’t just preserve the shape of the type, but also the data/records of the sObject. Yes, you read it right! Migrating to custom metadata is a straightforward process to move the shape of the sObject AND its records to the new custom metadata type.

Check out this example. I just migrated a custom object with all of its records into a custom metadata type in a single step.

NOTE Custom settings of type hierarchy are not supported.

In addition to migration, you can bulk insert records to custom metadata types, up to 10,000 records in one go with the following command.

  • sfdx force:cmdt:record:insert
    Insert new custom metadata type records from a CSV file.

For example, let’s say I have this CSV file with records that should be inserted into a custom metadata type with the API name MyNewCmdt.

Instead of entering the values one by one, I can use the command to bulk insert the records at once.

sfdx force:cmdt:record:insert -f ~/Downloads/RecordsCMT.csv -t MyNewCmdt 

Once inserted, I will push the records to my scratch org.

sfdx force:source:push

And now this is how my org looks with all the new records.

Historically, you might have used a custom metadata loader to insert records into custom metadata types in your org. Well, now you can do that from the Salesforce client itself without having to integrate a third party tool. Since each record of a custom metadata type is stored as its own file (it’s metadata, remember?), you can insert up to 10,000 records in a single execution of the command. This is a big level up from the 200 record limit of the loader. Since the command uses synchronous metadata deploy underneath, it follows the same limits as that of metadata deploy.

Wait, there’s more …

While the above commands let you swiftly move over from sObjects to custom metadata types, here are some others that help you to create brand new ones, create fields and add records to them.

  • sfdx force:cmdt:create
    Create a custom metadata type.
  • sfdx force:cmdt:field:create
    Generate a custom metadata field based on the specified field type.
  • sfdx force:cmdt:record:create
    Create a record for a specified custom metadata type.

You can check out all the commands for parameters and usage information, by using the help flag. For example, sfdx force:cmdt:record:insert -h lists down the description and parameters for the insert command.

Wrapping up

And while you’ve been getting things done with custom settings, you can experience the true power of the platform by using custom metadata. It allows you to do everything with its records that can be done with standard Salesforce metadata.
Additionally, the custom metadata loader is not a supported or maintained tool, and Salesforce does not guarantee its functionality or performance. Therefore —if you haven’t already— this is the right time to get on the CLI bandwagon and start using the Salesforce CLI to make the move!

#LearnMOAR and share

Share what you love about the Winter ’21 Release with the #LearnMOAR hashtag. Also, don’t forget to sign up for Release Readiness Live happening on September 18, 2020.

About the author

Neha Ahlawat is a Product Manager at Salesforce focused on Custom Metadata Types, Source Tracking and Metadata Coverage. You can follow her on Twitter @ahlawat_neha

Additional resources

Salesforce DX Setup Guide
Salesforce Help: Create and Manage Custom Metadata Types Using CLI Commands
Salesforce CLI Command Reference: cmdt Commands
Salesforce Help: Custom Metadata Types
Custom Metadata Types Basics Trailhead
Programmatic Development with Custom Metadata Types Trailhead

No purchase necessary. Void where prohibited. Sweepstakes runs from September 14, 2020 12:00 PM PT to October 30, 2020 11:59 PM PT. Open to legal residents of the U.S. (incl. D.C.), Austria, Canada (excluding Quebec), Cyprus, France, Germany, Greece, Hungary, India, Ireland, Japan, Lithuania, Latvia, Luxembourg, Netherlands, New Zealand, Norway, Spain, Switzerland, Ukraine, and the U.K. Must be 18+ (20+ in Japan). See Official Rules.