When you have more complex custom metadata needs or multiple custom metadata types, the UI requirements for users to manage records may also need to be more sophisticated. For example if you wish to build a setup wizard or type of visual editor. Much like you see with the Flow or Process Builder tools. So if you find you want to build your own UI for custom metadata records what is involved?
The native Apex Metadata API allows for Layout metadata as well as Custom Metadata records to be manipulated directly in Apex, without the traditional need for callouts or elevated permissions. Due to its generic API design, the data types for custom metadata records are represented as generic name/value pairs. Because of this it does require a bit more coding than you might expect to update records. Certainly compared to the SObject and DML oriented experience you get when working with Custom Object records in Apex. There is also the fact that it is async only, requiring careful transfer of results received via callbacks back to the user.
Custom Metadata Services (CMS) is a small library created to wrap the native Apex Metadata API to leverage the native SObject types for custom metadata in a more DML orientated way. It also aims to simplify the handling of the async results when developing clients in Lightning, inspired in this case by Lightning Data Services.
Updating records in Apex
When you create a Custom Metadata Type under the Setup menu, the platform automatically generates a corresponding SObject type you can use within Apex. This so that you can query those records using regular SOQL.
List records =
[select
DeveloperName, Label,
DefaultNotification__c, Alias__c
from
WidgetPreset__mdt];
Using the native SObjectType and the related field references (SObjectField tokens) is preferable to using String literals from a referential integrity perspective and also namespace management for packaged code. So CMS uses these whenever possible. The following code will upsert a Custom Metadata record.
String deployId = CustomMetadata.Operations
.callback(
// Simple callback that outputs to debug
new DebugCallback())
.enqueueUpsertRecords(
// Custom Metadata object type
WidgetPreset__mdt.getSObjectType(),
new List<Map> {
// Custom Metadata record
new Map {
WidgetPreset__mdt.DeveloperName => 'BluetoohToothbrush',
WidgetPreset__mdt.Label => 'Bluetooh Toothbrush',
WidgetPreset__mdt.DefaultNotification__c => 'Good day!',
WidgetPreset__mdt.Alias__c => 'wdbtt' } } )
.deployId;
- The only operation currently supported is an upsert. The use of this terminology reflects the fact that the native Metadata API deploys a list of records that will either insert or update records.
- Because its not possible to assign values directly to __mdt SObject fields, the above code uses an Apex map that references the fields via their SObjectField tokens.
The native Apex Metadata API uses a background job to update the records so the results are not know immediately to the calling code. CMS tailors the DeployCallback interface with its own base class which is more orientated around custom metadata record results. CMS also uses its own callback ID rather than the native one, allowing the client to more easily identify the corresponding callback.
public class DebugCallback extends CustomMetadata.SaveResultCallback {
public override void handleResult(String deployId, List results) {
System.debug('Deploy Id is ' + deployId);
for(SaveRecordResult result : results) {
System.debug('Fullname of custom metadata reocord is ' + result.fullName);
System.debug('Success is ' + result.success);
if(!result.success) {
System.debug('Message is' + result.message);
}
}
}
}
The callback method also supports the ability to send a Platform Event instead. This is preferable in cases where you are building UI’s, since the UI can listen for the callback directly. The Metadata Deployment platform event object is included in the library.
String deployId = CustomMetadata.Operations
.callback(
// Platform event for deploy status
MetadataDeployment__e.getSObjectType(),
MetadataDeployment__e.DeploymentId__c,
MetadataDeployment__e.Result__c)
.enqueueUpsertRecords(
// Custom Metadata object type
WidgetPreset__mdt.getSObjectType(),
new List<Map> {
// Custom Metadata record
new Map {
WidgetPreset__mdt.DeveloperName => 'BluetoohToothbrush',
WidgetPreset__mdt.Label => 'Bluetooh Toothbrush',
WidgetPreset__mdt.DefaultNotification__c => 'Good day!',
WidgetPreset__mdt.Alias__c => 'wdbtt' } } )
.deployId;
Building a Lightning UI
Here is a simple UI built with CMS, to demonstrate loading, saving and error handling.
When building UIs you can utilise the Apex code above from your server side controller logic. Though as an alternative, CMS includes a Lightning component for use within client side controllers. The design of this component follows that of the force:recordData component used for managing Custom Object records. It is currently aimed at single record retrieval and updates. Here is the markup for the above component.
The metadataRecordData component has its own Apex controller leveraging the CMS Apex API above and then listens for the MetadataDeployment__e event (included). This is transparent to the consumers of the component. The controller code interacts with the saveRecord method and metadataRecordDataResult event.
Building a Visualforce UI
It is possible to include Lightning Components in Visualforce pages using Lightning Out and thus reuse the above code in both Classic and Lightning Experience.
However if you still prefer to develop using Visualforce or simply have a number of pages you’d rather continue to develop for a while. You can still utilise the Platform Event mechanism using the client side library called cometd. The sample code for the page below can be found in the GitHub repo.
Summary
I plan on utilizing CMS to update the rollup tools UI in the future and avoid the need for callouts (and related permissions) when using its UI. In full disclosure I would also classify the library as alpha at this stage, its still needs a little more refinement and robustness adding. It is open source, so free to join me in fleshing it out further!
As a self confessed API junkie, each time the new Salesforce platform release notes land. I tend to head straight to anything API related, such as sections on REST API, Metadata, Tooling, Streaming, Apex etc etc. This time 
If you cannot wait to go try out the utility bar at this point, click the Deploy to Salesforce button below and it will deploy a sample application (make sure to use a Winter’17 org). Once deployed go to the App Manager under Setup and assign the Utility Bar Demo application to your profile.
Having just completed some improvements to the 
Doing this manually is a simple matter of dragging a 
Immediately i set about to rectify this! With a mission to allow the 
If you’ve been following my blog, you’ll have already read my earlier 
Fellow Salesforce MVP, 
Creating Records. The user first goes to the page and they see Create new…. in the drop down and the Developer Name field is enabled, hitting Save creates the record, refreshes the page and switches to edit mode. At this stage the Developer Name field is disabled and the drop down shows the recently created record selected by default.
Editing Records. In this mode the Developer Name (Object Name) field is disabled and Delete is enabled, users can either hit Save, Delete or pick another record from the drop down to Edit.
This is a thankfully UI driven process, much as you would any other component. Simply go to your Package Definition and add your Custom Metadata Type, if it has not already been brought in already through your SObject type references in your Visualforce or Apex code. Once added is shown as a Custom Object in the package detail page.
I was pleased and proud to see Salesforce themselves leveraging the 
Andy in the Cloud 