Custom Metadata
Two custom metadata types switch handlers off for the whole org, without code changes. For a trigger that calls runFromMetadata(), they also register its handlers. Create the records in Setup under Custom Metadata Types → Manage Records, or deploy them. In Setup, the Trigger Handler page layout groups the seven context fields in a Contexts section.
TriggerObject__mdt
One record per object.
| Field | Holds |
|---|---|
ObjectAPIName__c | the object's API name, such as Account or Invoice__c; case does not matter |
Bypass__c | checked: every handler on the object is off, in every context |
- The whole run is skipped. No handler, parent query or provider runs, and no Logger method is called.
- Also the parent of handler records. Their context field names it, so create it even with
Bypass__cunchecked. - Keep one record per object. With several, only one applies, and the handler records that name the others are ignored.
TriggerHandler__mdt
One record is one handler class in one context on one object. It names the class and, in exactly one of the seven context fields, the object.
| Field | Holds |
|---|---|
ApexClassName__c | the handler's class name |
BeforeInsert__c, AfterInsert__c, BeforeUpdate__c, AfterUpdate__c, BeforeDelete__c, AfterDelete__c, AfterUndelete__c | exactly one of them: the TriggerObject__mdt record of the object, in the record's context; the other six stay blank |
Bypass__c | checked: this class is off on that object, in that context |
Order__c | required; the run order within the context under runFromMetadata(), lowest first, ties by class name |
Description__c | free text for admins; the library never reads it |
- Two roles. Under
runFromMetadata(), a record runs its class in its context, unlessBypass__cis checked. Underrun(orchestrator), it only switches its class off in that context, andOrder__cis ignored, though it is still required. Deleting a record switches nothing off. - Exactly one context. The validation rule
OneContextRequiredrejects a record with no context field filled, or with more than one, in Setup and in a deployment. A record withBeforeInsert__cfilled neither runs nor switches off its class in after insert. - One record per context. A class that runs in several contexts has a record for each, with its own
Order__c. Name them<ClassName>_<Context>, such asAccountRatingPopulator_BeforeInsertandAccountRatingPopulator_BeforeUpdate, and shorten the class name when the result is longer than 40 characters, the limit of a record name. To switch the class off everywhere, checkBypass__con each. - One object per record. The context field names one object, so a class used on Account and on Contact needs a record for each.
ApexClassName__c Format
For a bypass, the value is matched against the class name without its outer class. Case does not matter.
| Handler class | Values that match |
|---|---|
top-level AccountRatingPopulator | AccountRatingPopulator |
inner AccountRules.RatingPopulator | RatingPopulator or AccountRules.RatingPopulator |
runFromMetadata()needs the full name, such asAccountRules.RatingPopulator, orns.AccountRatingPopulatorfor a class in another namespace. It throws on a name it cannot find.- A misspelled name in a bypass matches nothing, and nothing warns you.
- Inner classes with the same name can clash.
SalesRules.RatingPopulatorandServiceRules.RatingPopulatorshare the bypass keyRatingPopulator, so one record can switch off both.
When They Are Read
- Once per transaction. The first
run,runFromMetadataorbypass()call runs two queries: one for theTriggerObject__mdtrecords, then one for theTriggerHandler__mdtrecords, ordered byOrder__cand thenApexClassName__c. Each handler record is attached to the object record its context field names. Changes apply from the next transaction. - No SOQL limit cost. Custom metadata queries do not count toward the limit.
- Tests see the org's records. Tests that run the orchestrator can mock the queries.
Deploy Records
The file name is <Type>.<DeveloperName>.md-meta.xml, for example in force-app/main/default/customMetadata/. A handler record is named <ClassName>_<Context>.
Example
<?xml version="1.0" encoding="UTF-8"?>
<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<label>Account</label>
<protected>false</protected>
<values>
<field>ObjectAPIName__c</field>
<value xsi:type="xsd:string">Account</value>
</values>
<values>
<field>Bypass__c</field>
<value xsi:type="xsd:boolean">false</value>
</values>
</CustomMetadata><?xml version="1.0" encoding="UTF-8"?>
<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<label>AccountRatingPopulator Before Insert</label>
<protected>false</protected>
<values>
<field>ApexClassName__c</field>
<value xsi:type="xsd:string">AccountRatingPopulator</value>
</values>
<values>
<field>BeforeInsert__c</field>
<value xsi:type="xsd:string">Account</value>
</values>
<values>
<field>Bypass__c</field>
<value xsi:type="xsd:boolean">false</value>
</values>
<values>
<field>Order__c</field>
<value xsi:type="xsd:double">10</value>
</values>
</CustomMetadata>- Declare
xmlns:xsd. Without it, the deployment fails with anUNKNOWN_EXCEPTIONthat names no component. - The context field holds the DeveloperName alone, such as
Account, notTriggerObject.Account. Leave out the<values>blocks of the other six context fields. A second context is a second file, such asTriggerHandler.AccountRatingPopulator_BeforeUpdate.md-meta.xml. Order__cis a requiredxsd:double. A record without it fails to deploy.
