Systemartefakt-Releases sicher anwenden

Verwalten Sie globale Setup-Bestandteile in System > Konfiguration > Setup. Workspace plant jede Änderung zuerst und speichert den anschließenden Apply-Lauf. So können Sie Zielrelease, Operationen, Blocker und Ergebnis nachvollziehen, ohne bestehende Workflow-Definitionen direkt zu verändern.

Status einordnen

Die Setup-Seite zeigt für jedes Systemartefakt einen verwalteten Zustand:

Zustand	Bedeutung	Nächster Schritt
`Noch nicht verwaltet`	Es gibt noch kein aktives Release-Binding.	Erzeugen Sie einen Plan.
`Aktualisierung verfügbar`	Das Zielrelease unterscheidet sich vom aktiven Release.	Prüfen und wenden Sie den Plan an.
`Blockiert`	Eine Voraussetzung oder ein Overlay verhindert den Apply.	Lesen Sie den Blocker und lösen Sie die Ursache.
`Wird angewendet`	Ein persistierter Apply-Lauf besitzt die aktive Lease.	Warten Sie auf den Laufstatus; starten Sie keinen parallelen Apply.
`Abweichung erkannt`	Das aktive Release konnte nicht vollständig verifiziert werden.	Prüfen Sie Lauf und Betriebsbereitschaft.
`Bereit`	Zielrelease und effektives Binding sind verifiziert.	Keine Aktion nötig.
`Bereit mit Overlay`	Das Zielrelease ist verifiziert und besitzt ein kompatibles aktives Overlay.	Prüfen Sie das Overlay beim nächsten Update erneut.

Der allgemeine Bereitschaftswert bleibt während der Einführung mit älteren Provisionierungsabläufen kompatibel. Für den neuen Releasevertrag ist der Zustand des einzelnen Systemartefakts maßgeblich.

Änderung planen und anwenden

Öffnen Sie System > Konfiguration > Setup.
Wählen Sie die benötigten Systemartefakte.
Starten Sie die Prüfung.
Kontrollieren Sie Zielrelease, Ablaufzeit, Operationen und Blocker.
Wenden Sie nur einen gültigen Plan ohne Blocker an.
Prüfen Sie den angezeigten Apply-Lauf und aktualisieren Sie anschließend den Status.

Ein Plan ist 15 Minuten gültig. Wenn sich das Zielmanifest, der beobachtete Zustand oder die Binding-Generation ändern, lehnt Workspace den alten Plan ab. Erzeugen Sie dann einen neuen Plan. Eine Wiederholung derselben Plan-ID erzeugt keinen zweiten Lauf.

Workflow-Library und Overlays

Verwaltete Workflow-Releases veröffentlichen System-Workflows versionsgebunden. Sobald ein solches Release freigegeben und aktiviert ist, verwenden neue Instanzen das effektive globale Binding, sofern der Mandant keinen eigenen Workflow-Override besitzt. Bereits laufende Instanzen bleiben an ihre bisherige Workflow-ID und Version gebunden.

Die Capability workflow.library.managed schaltet diesen verwalteten Fallback pro Business-Mandant frei. Nur der System-Mandant darf die Capability für einen Ziel-Mandanten setzen oder entziehen. Ein Business- Mandant kann sie nicht selbst aktivieren. Ein eigener aktiver Workflow des Business-Mandanten hat immer Vorrang und benötigt diese Capability nicht. Fehlt bei aktivierter Capability das veröffentlichte Binding oder weicht sein Vertrag ab, startet Workspace keine neue Instanz über einen Legacy-Fallback.

Bei einem neu provisionierten Business-Mandanten legt das Workflows-Modul die Auswahl automatisch an, wenn sie fehlt. Vorhandene Werte, auch ein ausdrückliches false, bleiben unverändert. Bestehende Mandanten erhalten keine automatische Nachpflege. Dort darf nur ein ausdrücklich gestarteter Provisionierungslauf für die aktuelle Workflows-Modulversion eine fehlende Auswahl ergänzen. Schlägt die anschließende Auflösung oder Kompilierung fehl, endet dieser Lauf ohne fertigen Modulstatus.

Ein aktives globales Overlay bleibt getrennt vom Produktrelease. Ändert das Zielrelease dieselbe Workflow-Ressource, blockiert Workspace den gesamten Apply. Rebasen, ersetzen oder entfernen Sie das Overlay bewusst; Workspace führt keinen automatischen Merge aus.

Die Workflow-Library veröffentlicht ihren vollständigen verwalteten Zielvertrag auch dann als neues unveränderliches Release, wenn eine aktive Legacy-Definition vom früheren Foundation-Hash abweicht. Workspace verändert dabei weder den Legacy-Graphen noch bereits daran gebundene Instanzen. Neue Instanzen verwenden nach erfolgreicher Aktivierung das effektive verwaltete Binding. Eine bereits anders belegte Zielversion, Workspace-Authority- Konflikte oder aktive, noch nicht unterstützte Overlays blockieren den Plan weiterhin fail-closed. Verändern Sie bei einem solchen Blocker keine aktiven Workflow-Actions direkt und verwenden Sie keinen erzwungenen Apply.

Für den verwalteten Invoice-V2-Workflow prüft das Zielmanifest zusätzlich die beiden Action-Descriptoren, Bundle-Worker, Retry-/Recovery-, Publication- und Orphan-Vertrag. Vor der Aktivierung muss der Business-Mandant außerdem den Pflichtschlüssel commerce.invoices.documents_group_id auf eine bestehende tenantgebundene Gruppe setzen. Öffnen Sie dafür im Business-Tenant die Zugriffsgruppenverwaltung und wählen Sie bei einer passenden Gruppe „Für Rechnungsbelege verwenden“. Sie benötigen die Berechtigung zum Ändern von Zugriffsgruppen und Schreibzugriff auf die ausgewählte Gruppe. Ein globaler Wert oder eine Gruppe aus einem anderen Tenant gilt nicht als Ersatz. Die Gruppe erhält Leserechte auf XML, HTML und PDF; der auslösende Benutzer erhält kein implizites Einzelrecht.

Das Setup Center und die konkrete Rechnung zeigen fehlende Voraussetzungen vor der Finalisierung an. Dazu gehören auch eine ungültige Bestellwährung und ein bereits vorhandener Dokumentenstand, der einer erstmaligen Finalisierung widerspricht. Mail ist keine Finalisierungsvoraussetzung; das Erzeugen des Belegs versendet daher nicht automatisch eine Nachricht.

Nach dem Start der Rechnungsfinalisierung kann die Rechnung vorübergehend Finalisierung läuft anzeigen. Erst die gemeinsame Publication von XML, HTML, PDF, Berechtigungen, finalem Beleg, Workflow-, OSS- und Accounting- Fortschritt öffnet die Rechnung. Ein terminaler Fehler führt zu Finalisierung fehlgeschlagen; die angebotene Retry-Aktion setzt dieselbe Operation mit einem neuen begrenzten Versuch fort. manual_review verlangt eine administrative Prüfung und wird nicht automatisch erneut gestartet.

Auch ein blockierter Workflow-Library-Plan zeigt den vorgesehenen Ablauf:

vollständiges Workflow-Manifest und Action-Verträge validieren,
unveränderliches Workflow-Release veröffentlichen,
effektive Workflow-Bindings atomar aktivieren,
veröffentlichtes Release und Bindings verifizieren.

Diese Operationen beschreiben den geplanten Zielablauf. Sie sind keine Apply-Freigabe. Solange der Plan einen Blocker enthält, startet Workspace keinen Apply-Lauf und führt keine dieser Operationen aus.

Ein blockierter verwalteter Zielstand sagt nicht allein aus, ob der aktuell effektive Legacy-Workflow ausführbar ist. Prüfen Sie zusätzlich die tenantbezogene Workflow-Readiness. Workspace löst dort den effektiven Tenant- oder Systemworkflow auf und kompiliert seinen vollständigen Graphen. Der Hinweis „Workflow vorhanden, aber nicht ausführbar“ ist ein echter Betriebsblocker; umgehen Sie ihn weder mit Force noch durch direkte Datenbankänderungen.

Mit `nucli` prüfen

Verwenden Sie eine System-Mandanten-Session mit system_init:read für Status und Plan sowie system_init:apply für Apply:

bash

nucli --tenant system system init status --json
nucli --tenant system system init plan --artifact workflow_library --json
nucli --tenant system system init apply --plan <PLAN_ID> --json
nucli --tenant system system init run <RUN_ID> --json

tenants:init gewährt keinen Zugriff auf diese globalen Operationen. Verwenden Sie keine direkten Datenbankänderungen und kein lokales Offline-Administrationswerkzeug als Ersatz für den Serververtrag.

Mit einem Agenten arbeiten

Zeigen Sie dem Agenten zuerst den eingebauten Arbeitsablauf:

bash

nucli skills show system-artifacts

Ein MCP-fähiger Agent kann denselben Ablauf über folgende Tools ausführen:

Tool	Aufgabe
`nucleus_system_artifacts_skill`	Zeigt die sichere Arbeitsanweisung.
`nucleus_system_artifacts_status`	Liest den aktuellen Zustand.
`nucleus_system_artifacts_plan`	Erzeugt einen Plan für genau ein Artefakt.
`nucleus_system_artifacts_apply`	Wendet genau eine freigegebene Plan-ID an.
`nucleus_system_artifacts_run`	Liest den Apply-Lauf.

Der Agent muss Ihnen Zielrelease, Ablaufzeit, Operationen und Blocker zeigen, bevor er einen Plan anwendet. Geben Sie genau diese Plan-ID frei. Erst danach darf der Agent nucleus_system_artifacts_apply mit approved: true aufrufen. Ohne diese Bestätigung sendet nucli keinen Apply-Request. Der Server prüft zusätzlich System-Mandant, Scopes, Planbindung und Blocker; die Bestätigung ersetzt diese Prüfungen nicht.

Ein Plan erzeugt noch keinen aktiven Releasezustand und benötigt deshalb keine Apply-Freigabe. Automatisieren Sie weder Force noch Wiederholungen für abgelaufene, veraltete oder blockierte Pläne.

Die Aufgabe ist erfolgreich abgeschlossen, wenn der Apply-Lauf den Zustand succeeded und das Artefakt anschließend ready oder ready_with_overlay meldet. Ein blockierter Plan ist dagegen ein gültiger Prüfbefund: Lösen Sie zuerst die angezeigte Ursache.

Fehler sicher behandeln

Bei ERR_SYSTEM_ARTIFACT_PLAN_EXPIRED oder ERR_SYSTEM_ARTIFACT_PLAN_STALE erzeugen Sie einen neuen Plan. Bei ERR_SYSTEM_ARTIFACT_PLAN_BLOCKED lesen Sie den Blocker. Bei ERR_SYSTEM_ARTIFACT_RUN_IN_PROGRESS prüfen Sie den aktiven Lauf. Bei ERR_SYSTEM_ARTIFACT_APPLY_FAILED bleibt das vorherige Binding erhalten; prüfen Sie Betriebsbereitschaft und Laufstatus. Bei ERR_SYSTEM_ARTIFACT_VERIFICATION_FAILED bleibt das vorherige effektive Binding erhalten; prüfen Sie Laufstatus und Betriebsbereitschaft, bevor Sie erneut planen.

Siehe auch Automatisierung, Workflows und Reporting und Diagnose und Betriebsbereitschaft.