Custom metadata types deployen zonder subscribers te breken

Kort antwoord: Bepaal vóór de eerste release wie elk veld bezit, want die keuze is moeilijk terug te draaien. Maak waarden die klanten willen aanpassen subscriber editable, houd waarden waar je code van afhangt upgradeable, behandel picklistwaarden en namen van beschermde records als permanent, en test elke upgrade tegen een org die al klantwijzigingen bevat.

Wat betekent "subscribers breken" bij custom metadata?

Een custom metadata-upgrade breekt een subscriber op een van drie manieren:

• Hij overschrijft een waarde die de klant heeft aangepast. Hun configuratie wordt bij de upgrade stilletjes teruggezet.
• Hij faalt bij installatie of upload. Het platform weigert een wijziging, zoals een verwijderde picklistwaarde.
• Hij verwijdert iets dat nog in gebruik is. Een record waar jouw code of hun configuratie op leunt, wordt deprecated of verwijderd.

Alle drie zijn terug te voeren op packagingkeuzes van vóór de eerste release, niet op het deploycommando. De veilige route begint dus bij de typedefinitie.

Welke field manageability-instelling kies je?

Elk veld op een verpakte custom metadata type heeft een van drie instellingen, zoals de Trailhead-unit over het beschermen van custom metadata van Salesforce uitlegt:

• Upgradeable (door de developer beheerd): je kunt de waarde via package-upgrades wijzigen. Subscribers kunnen hem niet bewerken.
• Subscriber editable: de subscriber kan de waarde na installatie bewerken, en package-upgrades overschrijven die wijzigingen niet.
• Locked: na de release kunnen jij noch de subscriber het veld bewerken.

Vuistregel: als een klant de waarde ooit wil aanpassen, maak hem subscriber editable en accepteer dat je hem in hun org niet meer kunt corrigeren. Als de waarde bepaalt hoe je code werkt, houd hem upgradeable. Gebruik locked alleen voor waarden die nooit mogen veranderen. Let op: subscriber editable velden op beschermde records zijn na de release vergrendeld, dus plan bescherming en manageability samen.

Wat is permanent zodra je released?

• Aan picklistwaarden kun je alleen toevoegen. Volgens de implementatiegids voor custom metadata van Salesforce kunnen developers waarden toevoegen aan een verpakt picklistveld, maar ze niet verwijderen of deactiveren, en subscribers kunnen er helemaal niets aan veranderen. Een picklistveld met inactieve waarden blokkeert bovendien de package-upload tot je die waarden verwijdert of opnieuw activeert.
• Namen van beschermde records liggen vast. Volgens de Metadata API-referentie kan de developer name van een beschermd record na de release niet meer worden gewijzigd. Geef records namen alsof het een publieke API is.
• Bescherming kan alleen losser. Een protected type kan public worden, maar een public type kan niet terug naar protected. Protected types kunnen alleen in Developer Edition- en scratch-orgs worden aangemaakt.
• Alleen jij voegt velden toe. Subscribers kunnen geen custom velden toevoegen aan een managed custom metadata type, dus plan de velden vóór je uitlevert.

Wat gebeurt er met records die je uit een package haalt?

In second-generation managed packages worden verwijderde custom metadata-records als deprecated gemarkeerd als ze zichtbaar zijn voor de subscriber-org, en anders definitief verwijderd, volgens de gids van Salesforce over het verwijderen van metadatacomponenten uit 2GP-packages. Deprecated componenten blijven bestaan tot een subscriber-beheerder ze verwijdert, en de Setup Audit Trail legt vast wat de upgrade heeft verwijderd. Twee gevolgen:

• Ga er niet van uit dat een verwijderd record weg is. Een zichtbaar record kan als deprecated in de subscriber-org blijven staan, dus code moet stoppen met ernaar te verwijzen in plaats van op de afwezigheid te rekenen.
• Hergebruik nooit een verwijderde naam. Salesforce beschrijft een upgrade die faalde omdat een achtergebleven deprecated component botste met een opnieuw toegevoegde component met dezelfde naam.

Bouw je je packagemodel opnieuw op, dan laat onze gids over van Salesforce DevOps-tool wisselen zonder je pipeline te breken zien hoe je de packagegeschiedenis intact houdt bij een toolwissel.

Hoe deploy je een custom metadata-upgrade veilig?

1. Review het type, niet alleen de records. Wijzigingen in manageability, bescherming en picklists kun je niet ongedaan maken, dus markeer ze in de pull request.
2. Verpak standaardwaarden, geen klantconfiguratie. Lever de records die jij moet bezitten. Laat klantspecifieke waarden over aan subscriber editable velden of aan records die subscribers zelf aanmaken.
3. Bouw een upgrade-testorg. Installeer de vorige gereleasede versie, bewerk subscriber editable waarden, maak een paar klantrecords aan en installeer dan de nieuwe versie eroverheen.
4. Controleer wat overleefde. Subscriberwijzigingen moeten intact zijn, upgradeable waarden bijgewerkt, en verwijderde records deprecated en zonder verwijzingen.
5. Wijzig records vanuit Apex alleen via de Metadata API. Apex kan geen DML gebruiken op custom metadata-records. Het deployt ze asynchroon met Metadata.Operations.enqueueDeployment en een Metadata.DeployCallback-klasse, en Salesforce beperkt hoeveel van die deployments tegelijk in de wachtrij mogen staan.
6. Houd rekening met caching. Custom metadata-records worden na de eerste leesactie gecachet, en verzoeken die al lopen tijdens een update zien de nieuwe waarden niet. Post-installcontroles moeten geen directe wijziging verwachten.

Als twee branches hetzelfde .md-meta.xml-record wijzigen, volg dan onze gids over Salesforce-metadatamergeconflicten oplossen zonder iemands werk te verliezen.

Maakt dit uit als je geen managed package uitlevert?

Ja, in kleinere mate. Interne teams deployen custom metadata-records ook tussen sandboxes en productie, en een record deployen vanuit source overschrijft de kopie in de doel-org. Als beheerders records direct in productie aanpassen, draait de volgende deploy vanuit Git dat stilletjes terug. Maak Git de enige plek waar die records veranderen, of houd records die beheerders bezitten buiten de deployment. Onze gids over beheerders laten deployen zonder Git aan te raken laat zien hoe je hen een getrackte route geeft in plaats van directe bewerkingen.

Waar past Serpent?

Serpent is het Salesforce DevOps-platform van Tekunda. Het deployt custom metadata via dezelfde gereviewde pipeline als de rest van je metadata, met AI-codereview en menselijke goedkeuring vóór productie, zodat een manageability- of picklistwijziging een tweede paar ogen krijgt voordat hij live gaat. Vergelijk de Serpent-abonnementen, of bekijk meer SF Guides over packaging en CI/CD.

FAQ

Overschrijft een package-upgrade custom metadata-waarden van subscribers?

Alleen bij upgradeable velden. Package-upgrades overschrijven nooit waarden die een subscriber in een subscriber editable veld heeft gewijzigd.

Kan ik een picklistwaarde verwijderen uit een verpakte custom metadata type?

Nee. Na de release kun je picklistwaarden toevoegen, maar bestaande niet verwijderen of deactiveren.

Kan Apex custom metadata-records bijwerken?

Ja, maar niet met DML. Gebruik Metadata.Operations.enqueueDeployment, dat asynchroon deployt en via een callbackklasse terugmeldt.

Wie maakt Serpent?

Tekunda bouwt Serpent, een Salesforce DevOps-platform met CI/CD, AI-codereview en door mensen goedgekeurde deployments.