Custom Metadata Types deployen, ohne Subscriber zu brechen

Kurze Antwort: Legen Sie vor dem ersten Release fest, wem jedes Feld gehört, denn diese Entscheidung lässt sich kaum zurücknehmen. Machen Sie Werte, die Kunden anpassen werden, subscriber editable, halten Sie Werte, von denen Ihr Code abhängt, upgradeable, behandeln Sie Picklist-Werte und Namen geschützter Datensätze als dauerhaft und testen Sie jedes Upgrade gegen eine Org, die bereits Kundenänderungen enthält.

Was heißt „Subscriber brechen“ bei Custom Metadata?

Ein Custom-Metadata-Upgrade bricht einen Subscriber auf eine von drei Arten:

• Es überschreibt einen Wert, den der Kunde angepasst hat. Seine Konfiguration wird beim Upgrade stillschweigend zurückgesetzt.
• Es scheitert bei Installation oder Upload. Die Plattform lehnt eine Änderung ab, etwa einen entfernten Picklist-Wert.
• Es entfernt etwas, das noch genutzt wird. Ein Datensatz, auf den Ihr Code oder seine Konfiguration angewiesen ist, wird als veraltet markiert oder gelöscht.

Alle drei gehen auf Packaging-Entscheidungen vor dem ersten Release zurück, nicht auf den Deploy-Befehl. Der sichere Weg beginnt deshalb bei der Typdefinition.

Welche Einstellung zur Feldverwaltung sollten Sie wählen?

Jedes Feld eines paketierten Custom Metadata Types trägt eine von drei Einstellungen, wie Salesforces Trailhead-Einheit zum Schutz von Custom Metadata erklärt:

• Upgradeable (vom Entwickler gesteuert): Sie können den Wert über Paket-Upgrades ändern. Subscriber können ihn nicht bearbeiten.
• Subscriber editable: Der Subscriber kann den Wert nach der Installation bearbeiten, und Paket-Upgrades überschreiben seine Änderungen nicht.
• Locked: Nach dem Release können weder Sie noch der Subscriber das Feld bearbeiten.

Faustregel: Wenn ein Kunde den Wert jemals anpassen möchte, machen Sie ihn subscriber editable und akzeptieren Sie, dass Sie ihn in seiner Org nicht mehr korrigieren können. Wenn der Wert das Verhalten Ihres Codes bestimmt, lassen Sie ihn upgradeable. Locked ist nur für Werte gedacht, die sich nie ändern dürfen. Beachten Sie: Subscriber-editable-Felder auf geschützten Datensätzen sind nach dem Release gesperrt, also planen Sie Schutz und Feldverwaltung gemeinsam.

Was ist nach dem Release dauerhaft?

• Picklist-Werte lassen sich nur ergänzen. Laut Salesforces Implementierungsleitfaden für Custom Metadata können Entwickler einem paketierten Picklist-Feld Werte hinzufügen, sie aber weder löschen noch deaktivieren, und Subscriber können daran gar nichts ändern. Ein Picklist-Feld mit inaktiven Werten blockiert außerdem den Paket-Upload, bis Sie diese Werte löschen oder reaktivieren.
• Namen geschützter Datensätze sind fix. Laut Metadata-API-Referenz lässt sich der Developer Name eines geschützten Datensatzes nach dem Release nicht mehr ändern. Benennen Sie Datensätze, als wären sie eine öffentliche API.
• Schutz lässt sich nur lockern. Ein geschützter Typ kann öffentlich werden, aber ein öffentlicher Typ kann nicht wieder geschützt werden. Geschützte Typen lassen sich nur in Developer-Edition- und Scratch-Orgs anlegen.
• Nur Sie fügen Felder hinzu. Subscriber können einem verwalteten Custom Metadata Type keine eigenen Felder hinzufügen, planen Sie die Felder also vor der Auslieferung.

Was passiert mit Datensätzen, die Sie aus einem Paket entfernen?

In Second-Generation Managed Packages werden entfernte Custom-Metadata-Datensätze als veraltet (deprecated) markiert, wenn sie für die Subscriber-Org sichtbar sind, und andernfalls endgültig gelöscht, so Salesforces Leitfaden zum Entfernen von Metadatenkomponenten aus 2GP-Paketen. Veraltete Komponenten bleiben, bis ein Subscriber-Admin sie löscht, und der Setup Audit Trail protokolliert, was das Upgrade entfernt hat. Zwei Folgen:

• Gehen Sie nicht davon aus, dass ein entfernter Datensatz weg ist. Ein sichtbarer Datensatz kann als veraltet in der Subscriber-Org bleiben, daher sollte Code ihn nicht mehr referenzieren, statt sich auf sein Fehlen zu verlassen.
• Verwenden Sie einen entfernten Namen nie wieder. Salesforce dokumentiert ein gescheitertes Upgrade, weil eine zurückgebliebene veraltete Komponente mit einer neu hinzugefügten Komponente gleichen Namens kollidierte.

Wenn Sie Ihr Paketmodell neu aufsetzen, zeigt unser Leitfaden zum Wechsel des Salesforce-DevOps-Tools, ohne die Pipeline zu brechen, wie die Paket-Historie bei einem Toolwechsel erhalten bleibt.

Wie deployen Sie ein Custom-Metadata-Upgrade sicher?

1. Prüfen Sie den Typ, nicht nur die Datensätze. Änderungen an Feldverwaltung, Schutz und Picklists lassen sich nicht rückgängig machen, markieren Sie sie also im Pull Request.
2. Paketieren Sie Standardwerte, keine Kundenkonfiguration. Liefern Sie die Datensätze aus, die Ihnen gehören müssen. Überlassen Sie kundenspezifische Werte Subscriber-editable-Feldern oder Datensätzen, die Subscriber selbst anlegen.
3. Bauen Sie eine Upgrade-Test-Org. Installieren Sie die vorherige veröffentlichte Version, bearbeiten Sie Subscriber-editable-Werte, legen Sie einige Kundendatensätze an und installieren Sie dann die neue Version darüber.
4. Prüfen Sie, was überlebt hat. Subscriber-Änderungen müssen intakt sein, upgradeable Werte aktualisiert und entfernte Datensätze veraltet und unreferenziert.
5. Ändern Sie Datensätze aus Apex nur über die Metadata API. Apex kann kein DML auf Custom-Metadata-Datensätze anwenden. Es deployt sie asynchron mit Metadata.Operations.enqueueDeployment und einer Metadata.DeployCallback-Klasse, und Salesforce begrenzt, wie viele solcher Deployments gleichzeitig in der Warteschlange stehen dürfen.
6. Berücksichtigen Sie das Caching. Custom-Metadata-Datensätze werden nach dem ersten Lesen gecacht, und Anfragen, die während eines Updates bereits laufen, sehen die neuen Werte nicht. Post-Install-Prüfungen sollten keine sofortige Änderung erwarten.

Wenn zwei Branches denselben .md-meta.xml-Datensatz ändern, folgen Sie unserem Leitfaden zum Lösen von Salesforce-Metadaten-Merge-Konflikten, ohne dass jemand seine Arbeit verliert.

Spielt das eine Rolle, wenn Sie kein Managed Package ausliefern?

Ja, in kleinerem Maß. Auch interne Teams deployen Custom-Metadata-Datensätze zwischen Sandboxes und Produktion, und das Deployment eines Datensatzes aus der Quelle überschreibt die Kopie in der Ziel-Org. Wenn Admins Datensätze direkt in der Produktion anpassen, setzt das nächste Deployment aus Git sie stillschweigend zurück. Machen Sie Git zum einzigen Ort, an dem sich diese Datensätze ändern, oder halten Sie von Admins verwaltete Datensätze aus dem Deployment heraus. Unser Leitfaden dazu, wie Admins deployen, ohne Git anzufassen, zeigt, wie Sie ihnen einen nachverfolgten Weg statt direkter Änderungen geben.

Wo passt Serpent hinein?

Serpent ist die Salesforce-DevOps-Plattform von Tekunda. Sie deployt Custom Metadata über dieselbe geprüfte Pipeline wie Ihre übrigen Metadaten, mit KI-Code-Review und menschlicher Freigabe vor der Produktion, sodass eine Änderung an Feldverwaltung oder Picklists ein zweites Paar Augen bekommt, bevor sie ausgeliefert wird. Vergleichen Sie die Serpent-Pläne oder stöbern Sie in weiteren SF Guides zu Packaging und CI/CD.

FAQ

Überschreibt ein Paket-Upgrade die Custom-Metadata-Werte von Subscribern?

Nur bei upgradeable Feldern. Paket-Upgrades überschreiben nie Werte, die ein Subscriber in einem Subscriber-editable-Feld geändert hat.

Kann ich einen Picklist-Wert aus einem paketierten Custom Metadata Type löschen?

Nein. Nach dem Release können Sie Picklist-Werte hinzufügen, aber bestehende weder löschen noch deaktivieren.

Kann Apex Custom-Metadata-Datensätze aktualisieren?

Ja, aber nicht per DML. Verwenden Sie Metadata.Operations.enqueueDeployment, das asynchron deployt und über eine Callback-Klasse zurückmeldet.

Wer entwickelt Serpent?

Tekunda entwickelt Serpent, eine Salesforce-DevOps-Plattform mit CI/CD, KI-Code-Review und von Menschen genehmigten Deployments.