I introduced the Apex Metadata API by showing that the top reason developers want this feature is to build custom setup wizards. Given the importance of that use case, it probably deserves a closer look, don’t you think? Let’s walk through a great example of how StepOrange did this. 

Converse is a fundraising and donor management app for European nonprofit organizations (NPOs). It was built by ISV StepOrange and recently acquired by Salesforce partner ABSI.

Converse has a SegmentScience feature that enables nonprofits to create a profile of each of their contacts according to the NPO’s donor segmentation strategy. The image on the right shows a contact with the standard, out-of-the box Finance radar/spider chart (chart with more than 2 axes). This gives the NPO a simple but powerful view of the contact’s financial engagement with the organization: how much the person gives, how often they gave last year, how many times they’ve given so far this year, and how recently they made their last gift.

Let’s customize the app

As with any sophisticated app, Converse is intended to be tailored to each organization’s needs.

Let’s say I want to extend the “Finance” category to track the amount of each donor’s most recent gift. I’ll need to add an attribute to the four that StepOrange provided, which will show up as a new axis on the chart and require a new set of thresholds for the metric. (A $1,000 gift might correspond to a 3 and a $10,000 gift a 5, for example.)

If I also want to track each donor’s social influence, I’ll need an additional chart. After it’s customized to my organization’s needs, the app should show me something like this: 

Because all these extensions of SegmentScience are metadata driven, I can create all the new components in Salesforce setup. However, to create the Influence graph shown above, I need 36 custom metadata records across 3 different custom metadata types, and I need 6 custom fields on the Contact object. All these must be created in a specific order and linked to the right metadata records, objects, and fields. 

Disclaimer: until the Apex Metadata API supports custom fields, this wizard still requires admins to create custom fields on the Contact object manually.

To guide consultants and administrators through this process, StepOrange needs to provide a substantial amount of documentation. And even then the process can be error prone. What if I accidentally link one of my custom metadata records to “Contract” rather than “Contact”? Now my app doesn’t work properly, and it can be difficult to figure out why.

For professional services teams that do this regularly, this is tedious but not difficult. But for many admins, this can be overwhelming.

Welcome to a brave new world of seamless customization

With the ability to read, create, and update metadata now available natively in Apex, StepOrange created a setup wizard for SegmentScience. It makes app customization much easier for professional services and usable by most admins. Here’s how it streamlines customization:

• The three-page wizard guides admins through the process. They no longer need a set of instructions that points them to different places in the Salesforce setup UI.
• It eliminates three quarters of the clicks and input compared to using the Salesforce setup UI, which saves time and reduces the chance of error.
• The UI refers only to relevant objects (Contact and Account) rather than all objects in the app, enhancing ease of use and further reducing the opportunity for error.
• And finally, the flow of the wizard corresponds to the end-user experience the admin is trying to create, making it easy to navigate.

Rather than creating a set of records, objects, and fields that are only meaningful to the technical implementation of the package, the screens shown here guide an admin through creation of exactly what they intend end users to see: a chart, some axes, and thresholds on those axes. 

This wizard makes life easier and reduces costs for StepOrange and their customers alike, in the many ways I describe in a previous blog.

The wizard deploys its metadata asynchronously

Behind the scenes, the Converse setup wizard creates a deployment container and populates it with new metadata and metadata updates. Converse then deploys the container asynchronously, just like any other Metadata API deployment.

Because developers know how to use asynchronous deploys and some already leverage them in their code, it’s easy to learn this new API. It’s also easy to migrate from a Metadata API wrapper your app may be using. Just ask Andy in the Cloud!

For the most part, the deployment works just as you expect if you’re familiar with metadata deploys. One useful exception is that it’s Apex-driven, so any edition that can execute Apex can use this. Professional and Group Edition orgs cannot execute Apex or use the Metadata API on their own. However, they can execute Apex in an installed ISV package. Therefore, metadata deploys via Apex in ISV packages will work in Professional and Group Edition orgs, ensuring ISVs don’t have to build different versions of their app for different editions.

The following chart summarizes these scenarios. 

How to test your code

As you write tests for your new setup UI, be sure to test your metadata container and your call back. But note that you cannot build automation to test whether the org looks as it should after the deploy. Refer to the documentation for more details on testing.

The Apex Metadata API was not built for testing other code. Some developers have expressed a desire to use the Apex Metadata API to toggle features on and off for unit testing. However, because the Apex Metadata API relies on an asynchronous deploy it is not compatible with Apex’s synchronous tests.

Show us what you build and tell us what you want

Now that you’ve seen how one ISV built a sleek, simple setup experience for their customers, we’d love to see what you build. Please join the Apex Metadata API Chatter group in the Success Community and let us know.

And while you’re there, let us know what other metadata types you want supported and why. Be specific about the “why”! We look forward to bringing you support for more types and want your help to identify the most important ones.

For more info, check out my previous blog posts for an overview of the new Apex Metadata API and a detailed look at its security model. In my final post in this series I will do a deep dive into the post install script use case.

Finally, if you were waiting for the ability to create and update custom metadata types programmatically before adopting that feature, wait no more. To learn about custom metadata types, check out the Custom Metadata Types badge on Trailhead.

About the author

Aaron Slettehaugh is senior director of product management for the Salesforce platform. He has launched several products beloved by Salesforce developers, including custom metadata types and now the Apex Metadata API.

Before joining Salesforce, Aaron helped launch the global operations of an African NGO, led the product team at IaaS provider Joyent, and started a company and led it to acquisition by Citrix. He has an MBA from Stanford University and a bachelor in engineering.