Zum Hauptinhalt springen

Blueprints

Im Abschnitt Blueprints des Refinery Studio können Sie den Blueprint-Katalog Ihrer Umgebung durchsuchen, Blueprints auf dem aktuellen Tenant installieren oder erneut anwenden und einsehen, was bereits installiert ist.

Ein Blueprint ist ein versioniertes Bündel aus Construction-Kit-Modellen und Seed-Daten, das einen Tenant in einen betriebsbereiten Zustand versetzt. Zur zugrunde liegenden Funktionsweise siehe den Technikleitfaden: Blueprints.

Zugriff auf die Blueprint-Seiten​

Wählen Sie in der Rail Data > Blueprints. Es stehen zwei Ansichten zur Verfügung:

  • Catalog (diese Seite) — jedes in den konfigurierten Katalogen verfügbare Blueprint, mit Aktionen zum Installieren und erneuten Anwenden.
  • Installed — jedes auf dem aktiven Tenant installierte Blueprint, erreichbar über View installed → (Adresse .../repository/blueprints/installations).

Catalog-Ansicht​

Der Seitentitel ist Data; das Kennzeichen im Kopf zeigt die Anzahl der Blueprints (z. B. „32 blueprints“). Die Filterleiste enthält:

SteuerelementZweck
All, Installed, Not installed, UpdatesStatusfilter; jede Schaltfläche zeigt die Anzahl der passenden Blueprints.
All CatalogsDie Liste auf eine Katalogquelle beschränken (z. B. PublicGitHubBlueprintCatalog, LocalFileSystemCatalog).
Search...Nach Blueprint-Name und Beschreibung filtern.
Aktualisieren-Schaltfläche (Refresh blueprint catalog)Die Kataloge neu laden.

Jedes Blueprint ist eine Karte mit

  • dem Namen,
  • einer Versions-Auswahlliste (welche Katalogversion installiert wird; bei dienstverwalteten Blueprints steht die installierte Version) und dem Katalog-Kennzeichen,
  • der (gekürzten) Beschreibung,
  • einem Statuskennzeichen (Available bei nicht installierten Blueprints, Installed, oder (installed) neben der Version) und
  • der Aktionsschaltfläche: Install (nicht installiert) oder Re-apply (installiert). Sie ist deaktiviert, solange die Karte Blocked zeigt oder die Kompatibilitätsprüfung läuft, siehe Blockierte Versionen.

Mit Service-managed gekennzeichnete Blueprints (z. B. System.UI.TenantCockpit, System.Identity.Bootstrap) werden von der Plattform angewendet und aktuell gehalten. Sie zeigen Installed und Managed by service und haben keine Aktionsschaltfläche.

Ein Blueprint installieren​

  1. Suchen Sie das Blueprint im Katalog. Verwenden Sie bei Bedarf Suche / Filter.
  2. Wählen Sie bei Bedarf die Version in der Auswahlliste und klicken Sie auf der Karte auf Install.
  3. Der Dialog Install blueprint fragt Install blueprint '<id>-<version>' on this tenant? CK model dependencies and seed data will be imported. Bestätigen Sie mit Yes oder brechen Sie mit No ab.
  4. Während die Anwendung läuft, zeigt die Karte einen Spinner. Die Aktion ist gesperrt, bis die Anwendung abgeschlossen ist.
  5. Bei Erfolg erscheint ein grüner Toast: Installed <blueprint-id> — <N> seed file(s). Hat die Anwendung Warnungen erzeugt, hängt der Toast (<n> warning(s)) an, und es öffnet sich automatisch ein Detaildialog — siehe Warnungen lesen unten.
  6. Die Karte wechselt auf INSTALLED, und die Aktionsschaltfläche ändert sich zu Re-apply.

Ein Blueprint erneut anwenden​

Re-apply ist der Wiederherstellungspfad: Es importiert die Seed-Daten erneut per Upsert, obwohl das Blueprint in derselben Version verzeichnet ist. Es stellt wieder her, was dem Blueprint gehört; was dem Tenant gehört, macht es nicht rückgängig (siehe Was Install, Update und Re-apply behalten). Verwenden Sie es, wenn:

  • Sie vermuten, dass Seed-Entitäten geändert oder teilweise gelöscht wurden, und Sie diese erneut durchsetzen möchten.
  • Eine frühere Anwendung Seed-Entitäten abgelegt, aber das Einfügen in den Verlauf nicht abgeschlossen hat (Legacy-Verhalten, behoben im Rollout des tenantspezifischen Speichers — siehe Technikleitfaden).

Der Ablauf ist identisch mit Install, aber der Dialog Re-apply blueprint lautet Re-apply blueprint '<id>'? Existing seed entities will be upserted. „Upserted" heißt nicht, dass jeder Wert zurückgesetzt wird: Werte, die Ihrem Tenant gehören, bleiben erhalten.

Was Install, Update und Re-apply behalten​

Ein Blueprint-Update oder erneutes Anwenden ersetzt die Entitäten des Blueprints durch das Seed, löscht aber nie stillschweigend, was in Ihrem Tenant eingegeben wurde:

  • Werte, die Ihrem Tenant gehören, bleiben unverändert. Beispiele: der Enforcement-Modus einer Datenrichtlinie, die Konfiguration eines Adapters (einschließlich seiner Zugangsdaten), der Zustand eines Stream-Data-Archivs. Das Seed setzt sie nur, wenn die Entität erstmals angelegt wird.
  • Ein leeres Seed leert keinen gefüllten Wert. Würde eine neue Blueprint-Version einen Wert leeren, der in Ihrem Tenant gefüllt ist, behält das Update Ihren Wert und meldet ihn als Warnung.
  • Entitäten, die der Blueprint dem Tenant überlässt (eine Standardvorlage, eine Beispielregel), werden einmal angelegt. Spätere Updates ändern sie nicht, und nach einem Löschen kommen sie nicht zurück.
  • Entitäten, die dem Blueprint gehören (die gesperrten), werden aus dem Seed erneuert. Bearbeiten Sie sie nur über den Blueprint oder geben Sie sie vorher frei.

Studio wendet immer mit diesen Standardwerten an, ein Update aus Studio leert also nie einen Wert. Studio listet die Werte, die ein Update behalten würde, noch nicht auf; führen Sie vor dem Update eines Tenants mit eingegebenen Daten octo-cli -c PreviewBlueprintUpdate für die Liste aus. Die Regeln im Detail: Blueprint-Eigentum.

Warnungen lesen​

Wenn das Backend während der Anwendung Warnungen zurückgegeben hat, hängt der Erfolgs-Toast eine Anzahl an, und es öffnet sich automatisch ein Detaildialog:

  • Titel — Blueprint apply warnings — <blueprint-id>
  • Text — ein Aufzählungspunkt pro Warnung, in Festbreitenschrift (Leerraum erhalten).
  • Aktionen — Copy, um die vollständige Liste in die Zwischenablage zu kopieren; Close, um zu schließen.

Der Dialog ist in der Größe veränderbar und nicht blockierend — die Katalogaktualisierung läuft im Hintergrund weiter, während der Dialog geöffnet ist.

Wenn eine Warnung unklar ist, kopieren Sie den Text und prüfen Sie die asset-repo-Logs auf den entsprechenden ERROR-/WARN-Eintrag im Zeitraum um den Zeitstempel der Anwendung.

Blockierte Versionen​

Bevor Sie klicken, fragt das Studio den Server, ob die CK-Modelle der angezeigten Blueprint-Version ein bereits auf dem Tenant installiertes Modell beschädigen würden (z. B. weil ein installiertes Modell auf Basic-2.4.0 festgelegt ist und das Blueprint Basic-2.5.0 mitbringt). Das ist der Tenant-Upgrade-Guard, dieselbe Prüfung wie auf der Seite Model libraries. Sie gilt für Install, Re-apply, Update und Downgrade und auch für die erste Installation. Das Studio hat keine Force-Aktion: Ein beschädigendes Update zu erzwingen ist eine Operation der octo-cli und der API für Datenmodell-Verantwortliche.

  • Checking compatibility… — solange die Prüfung läuft, ist die Aktion deaktiviert (der Tooltip sagt es), sodass eine Schaltfläche nie vor der Antwort aktiv ist. Im Katalog wird eine Karte geprüft, wenn sie in den sichtbaren Bereich kommt oder wenn Sie eine andere Version wählen.
  • Blocked — ein rotes Badge Blocked erscheint (auf der Karte neben dem Statuskennzeichen, auf der Detailseite bei den Kennzeichen im Kopf), die Aktion ist deaktiviert und ihr Tooltip nennt den ersten Grund. Auf der Karte klappt Why? die Liste der Blocker auf (Hide details klappt sie zu); auf der Detailseite steht die Liste unter der Zusammenfassung. Jeder Blocker nennt das blockierte Modell (das installierte Modell, das beschädigt würde), das Update, das es verursacht, die betroffene fest verankerte Abhängigkeit, den erforderlichen Bereich oder das Element und, wenn die Kataloge eine neuere Version des blockierten Modells anbieten, die das Problem löst, How to resolve. Beheben Sie die Blocker (zuerst das blockierte Modell aktualisieren) und laden Sie die Seite neu.
  • Cannot check this update — schlägt die Prüfung selbst fehl (Netzwerk, Berechtigungen, Serverfehler), bleibt die Aktion mit diesem Grund deaktiviert, und Retry führt die Prüfung erneut aus.

Ein älteres Asset Repository meldet keine Blocker; die Seiten sehen dann aus und funktionieren wie bisher.

Lehnt der Server eine Installation oder ein Update dennoch ab (z. B. weil die Seite länger offen war und sich der Tenant inzwischen geändert hat), öffnet sich statt eines roten Fehler-Toasts der Dialog Update blocked. Er sagt, dass die Anfrage abgelehnt wurde, und listet dieselben Blocker. Close schließt ihn; die Karte bzw. die Seite zeigt danach den Status Blocked.

Fehlermodi​

SymptomUrsache
Roter Toast Install failed: <message>Das Backend hat die Anwendung abgelehnt. Die Meldung enthält oft einen harten Konflikt, eine fehlende CK-Abhängigkeit oder einen YAML-Schemafehler.
Dialog Update blocked, rotes Badge BlockedDer Server hat die Anfrage abgelehnt: Sie würde ein installiertes Modell beschädigen. Siehe Blockierte Versionen.
Spinner bleibt dauerhaft stehenNetzwerk- oder Backend-Stau. Laden Sie die Seite neu; die Anwendung wurde serverseitig möglicherweise bereits abgeschlossen.
Karte bleibt nach Erfolg auf NOT INSTALLEDVeralteter Cache. Öffnen Sie View installed →, um dies zu bestätigen; der Katalog wird beim Betreten der Seite neu geladen.

Ansicht Installed​

View installed → öffnet die Seite Installed blueprints mit der Anzahl der installierten Blueprints (z. B. „11 installed“) und einer Zusammenfassung wie „11 root · 0 transitive deps“. ← Browse catalog führt zurück zum Katalog. Die Tabelle hat die Spalten:

SpalteBedeutung
BlueprintName des Blueprints.
InstalledInstallierte Version, Root (explizit angefordert) oder Dependency (installiert, um ein anderes Blueprint zu erfüllen), Service-managed, wenn die Plattform es verwaltet, und der Zeitpunkt der ersten Anwendung.
Last updatedZeitpunkt der jüngsten Anwendung (Install, Update, Re-apply, Rollback).
Statusz. B. Up to date.

Die Schaltfläche Refresh installed blueprints ruft die Liste erneut vom Backend ab.

Apply History​

Die Verlaufsansicht ist ein chronologisches Protokoll jedes Anwendungsvorgangs (Initial, Update, Rollback, Reapply, Uninstall) mit Zeitstempeln, der vorherigen Version (bei Updates und Rollbacks) und Entitätsanzahlen pro Vorgang:

SpalteBedeutung
Applied atUTC-Zeitstempel der Anwendung.
BlueprintName und Version, die angewendet wurde.
ModeInitial / Update / Rollback / Reapply.
Previous versionDie Version, die vor dieser Anwendung installiert war (bei Initial leer).
CreatedAnzahl der erstellten Seed-Entitäten.
UpdatedAnzahl der aktualisierten Seed-Entitäten.
DeletedAnzahl der gelöschten Seed-Entitäten.

Der Verlauf ist append-only — es gibt kein Bearbeiten/Löschen in der Benutzeroberfläche. Die Aufbewahrung erfolgt pro Tenant: Wird ein Tenant gelöscht, verschwindet sein Verlauf mit ihm.

Wo die Daten liegen​

Sowohl die Installationszeilen als auch die Verlaufseinträge werden als Construction-Kit-Entitäten im eigenen Runtime-Repository des Tenants gespeichert — es gibt keine zentrale Registry. Das ist in der Praxis für zwei Szenarien relevant:

  • Tenant-Backup — mongodump --db=<tenant> erfasst den Blueprint-Zustand zusammen mit den Seed-Entitäten.
  • Tenant-Löschung — das Verwerfen eines Tenants löscht den Blueprint-Verlauf mit. Es bleibt kein „Geister-Verlauf" in einer Systemdatenbank zurück.

Siehe auch​