Das Customizing der B2B kann in einer einzigen Zip Datei exportiert und importiert werden

Die in der B2B-Oberfläche gemachten Einstellungen (Actions, Services, Global Properties u. s. w.) können als eine Zip-Datei exportiert und wieder importiert werden. Das geschieht über die Schaltflächen im Modul Administration/Global Properties.

Mögliche Einstellungen beim Import und Export

Das Customizing der B2B kann in einer einzigen Zip Datei exportiert und importiert werden. Ein Customizing umfasst Actions, Channels, Services, GlobalProperties, Contents, Extensions, Users, Roles, Attributes. Customizing in einer einzigen XML

Single XML

Per Default wird das Customizing in mehreren XML Dateien exportiert. Mit Hilfe der folgenden GlobalProperty kann das Customizing in einer einzigen XML exportiert werden: EXPORT_SINGLE_XML=true Default false. Das Customizing kann in dieser Form auch wieder importiert werden, unabhängig davon, ob die Property gesetzt ist. Vorteil dieser Exportform ist, dass zwei Customizings leicht gegenübergestellt werden können. Da das ganze Customizing in einer XML bereit steht, kann dieses außerdem mit Hilfe von XSL leicht modifziert werden. Beachte, dass unabhängig von dieser Konfiguration Contents und Extensions in zusätzlichen Dateien exportiert werden.

Extension & Content Hashes exportieren

Es ist möglich, im Content und Extension xml ein Attribut “hash” zu exportieren. Dieses enthält den Hashwert der zugehörigen Datei. Hierfür ist folgende Global Property zu setzen: EXPORT_CUSTOMIZING_WITH_HASH = true Der Default ist false. Dieses Feature kann genutzt werden, um schnell zwei Customizings auf XML Basis zu vergleichen. Stimmen die Hashes nicht überein, unterscheiden sich auch die Files. Beachte, dass ein Customizing, das in dieser Form exportiert wurde, nicht importiert werden kann.

Default Werte

Es ist möglich, Customizing Dateien zu importieren, wenn nicht alle Attribute im XML gefüllt sind. Dieses Feature ist mit der folgenden GlobalProperty zu aktivieren: IMPORT_CUSTOMIZING_WITH_DEFAULT_VALUES=true Default ist false. In diesem Fall werden Default Werte gesetzt, üblicherweise der leere String oder 0. Spezialfälle:

ActionId in der Actionproperty wird auf die ActionId gesetzt
ServiceId in der ServiceProperty wird auf die ServiceId gesetzt
CreatedAt im Service wird auf “jetzt” gesetzt
Extension Filename wird automatisch aus den anderen Attributen abgeleitet
Content Filename wird automatisch aus den anderen Attributen abgeleitet

nicht gesetzt werden Pflichtschlüsselfelder:

Action: ActionId, PropertyKey
Service: ServiceId, PropertyKey
GlobalProperty Key
Channel: ChannelId, ActionId
Attribute: AttributeId
Role: RoleId, AttributeId
User: UserId, RoleId

CUSTOMIZING_EXPORT_FILTER

Mit Hilfe der Extension CUSTOMIZING_EXPORT_FILTER (leerer Provider, leere Version) kann gefiltert werden, welche Elemente des Customizings exportiert werden. Die zukünftigen Exports beinhalten dann nur noch die definierten Teilmengen des Customizings. So können gezielt einzelne Elemente exportiert & danach importiert werden.

Dieses Feature darf nicht auf Produktivsystemen eingesetzt werden, damit das vollständige Customizing-Backup nicht behindert wird.

Die Extension ist unmittelbar vor dem Export zu konfigurieren und direkt danach wieder zu leeren.

Beispiel Extension CUSTOMIZING_EXPORT_FILTER:

actions={15;17}
channels={IN_ISU;OUT_B2B,CONTRL}
services={}
contents={NLI,1.0,NLC,UTILMD,5.1E,EDI;NLI,1.0,NLC,UTILMD,5.1E,IDOCXML}
extensions={EXT_CHANNEL_DIST;ClearingCodes}
roles={admin;b2bbp}
roleAttributes={Buttons;Logout}

Mit dieser Konfiguration werden folgende Elemente exportiert:

die Actions mit ID 15 & 17
der Channel IN_ISU sowie der Channel OUT_B2B mit MessageType=CONTRL
kein Service
alle GlobalProperties (da kein Filter für GlobalProperties konfiguriert ist)
der Content NLI,1.0,NLC,UTILMD,5.1E,EDI und der Content NLI,1.0,NLC,UTILMD,5.1E,IDOCXML
die Extensions EXT_CHANNEL_DIST & ClearingCodes
alle User (da kein Filter für User konfiguriert ist)
die Rollen admin & b2bbp
die RollenAttribute Buttons & Logout

Die allgemeine Syntax der Extension lautet für jede Zeile: tabelle={key1;key2;...;keyN} Groß- und Kleinschreibung ist zu beachten.

Folgende Werte für sind für Tabelle zulässig: actions,channels,services,globalProperties,contents,extensions,users,roles,roleAttributes Falls eine Tabelle nicht aufgeführt wird, werden alle Einträge der Tabelle exportiert. Ansonsten werden nur die aufgeführten Einträge der Tabelle exportiert. Wenn die leere Liste {} angegeben ist, wird kein einziger Eintrag der Tabelle exportiert. Die Schlüssel sind Semikolon-separiert anzugeben.

Für die Schlüssel gelten je nach Tabelle unterschiedliche Regeln:

actions: als Schlüssel wird die ActionId angegeben
channels: es gilt folgende Syntax: channelId,messageType,messageVersion,presentationType
services: als Schlüssel wird die ServiceId angegeben
globalProperties: als Schlüssel wird der GlobalPropertyKey angegeben
contents: es gilt folgende Syntax: provider,version,type,format,formatVersion,destFormat
extensions: es gilt folgende Syntax: provider,version,type
users: als Schlüssel wird die UserId angegeben
roles: als Schlüssel wird die RoleId angegeben
roleAttribute: als Schlüssel wird die RoleAttributeId angegeben

Die Schlüssel von Channels, Contents und Extensions setzen sich aus mehreren Komponenten zusammen. Beachte, dass Schlüssel durch Semikolon getrennt werden, die Komponenten eines einzelnen Schlüssels werden durch ein Komma getrennt. Falls nicht alle Komponenten angegeben werden, werden leere Strings bei den fehlenden Komponenten ergänzt. Beispiel: wenn als Channel-Schlüssel IN_ISU konfiguriert ist, wird der Channel IN_ISU mit leerem FormatType gefunden, nicht jedoch der gleichnamige Channel mit FormatType=CONTRL.

Anhang: eine Konfiguration, deren Ergebnis der leere Export ist. Auf dieser Basis können andere Konfigurationen erstellt werden.

actions={}
channels={}
services={}
globalProperties={}
contents={}
extensions={}
users={}
roles={}
roleAttributes={}

REST API Endpunkte für Customizing-Verwaltung

Alle Endpunkte liegen unter dem Basispfad /administration/customizing und erfordern die Rolle B2B_ADMIN_CUSTOMIZING.

Übersicht der Endpunkte

Methode	Pfad	Beschreibung
`GET`	`/administration/customizing`	Customizing als ZIP-Datei herunterladen
`POST`	`/administration/customizing`	Customizing aus ZIP-Datei importieren
`POST`	`/administration/customizing/sync`	Customizing aus ZIP-Datei synchronisieren
`POST`	`/administration/customizing/merge`	Vorschau der Synchronisation als gemergtes ZIP herunterladen

GET /administration/customizing – Export

Lädt das gesamte aktuelle Customizing als ZIP-Datei (b3p_customizing.zip) herunter. Entspricht dem bisherigen manuellen Export über die Oberfläche.

POST /administration/customizing – Import (klassisch)

Importiert ein Customizing-ZIP. Parameter:

file – die ZIP-Datei (Multipart)
deleteOld – wenn true, werden alle bestehenden Customizing-Einträge vor dem Import gelöscht (entspricht dem bisherigen „Ersetzen”-Verhalten)

POST /administration/customizing/sync – Synchronisation

Führt eine transaktionale Synchronisation durch. Im Unterschied zum klassischen Import werden dabei:

Einträge, die in der ZIP nicht enthalten sind, auf dem Zielsystem gelöscht (sofern nicht geschützt)
Einträge, die in der ZIP vorhanden sind, eingefügt oder überschrieben (sofern nicht geschützt)
Einträge, die durch die Extension SYNC_PROTECTED_CUSTOMIZING geschützt sind, nicht verändert

Jede Customizing-Bereiche (Actions, Channels, Services, Global Properties, Users, Roles, RoleAttributes, Extensions, Contents) wird in einer eigenen Datenbanktransaktion ausgeführt. Bei einem Fehler wird nur der betroffene Bereich zurückgerollt.

Einschränkung: Die Synchronisation erfordert das Split-XML-Format (mehrere XML-Dateien in der ZIP). Das Format mit einer einzelnen Customizing.xml wird nicht unterstützt.

POST /administration/customizing/merge – Merge-Vorschau (read-only)

Berechnet das Ergebnis einer Synchronisation, ohne Änderungen am System vorzunehmen. Gibt eine neue ZIP-Datei (b3p_customizing_merged.zip) zurück, die das zusammengeführte Customizing enthält.

Verwendung: Vor der eigentlichen Synchronisation kann so geprüft werden, welche Einträge sich ändern würden.

Einschränkung: Auch der Merge-Endpunkt erfordert das Split-XML-Format.

Geschützte Customizing-Einträge (SYNC_PROTECTED_CUSTOMIZING)

Beim Sync- und Merge-Vorgang können bestimmte lokale Einträge vor Änderungen durch die eingehende ZIP geschützt werden. Dafür dient die Extension vom Typ SYNC_PROTECTED_CUSTOMIZING (leerer Provider, leere Version).

Die Extension verwendet dieselbe Map-Syntax wie CUSTOMIZING_EXPORT_FILTER:

actions={15;17}
channels={IN_ISU;OUT_B2B,CONTRL}
services={}
globalProperties={MY_LOCAL_PROPERTY}
contents={}
extensions={MY_LOCAL_EXT}
users={admin}
roles={localAdmin}
roleAttributes={}

Verhalten:

Einträge, die in der geschützten Liste stehen, werden bei der Synchronisation nicht überschrieben und nicht gelöscht
Die Extension selbst (SYNC_PROTECTED_CUSTOMIZING) ist implizit immer geschützt und kann durch eine Synchronisation nicht entfernt werden
Wenn kein Eintrag für einen Typ konfiguriert ist, sind alle Einträge dieses Typs synchronisierbar
Syntax und Schlüsselregeln sind identisch mit denen des CUSTOMIZING_EXPORT_FILTER (siehe oben)

Customizing in Deployment-Pipelines einbinden

Mit den neuen REST-Endpunkten lässt sich das Customizing vollständig automatisiert von einer Umgebung (z. B. QA) auf eine andere (z. B. Prod) übertragen.

Empfohlener Workflow

QA-System                           Prod-System
   │                                    │
   ├─ GET /customizing ──────────────►  │  (1) Customizing-ZIP exportieren
   │                                    │
   │    b3p_customizing.zip             │
   │           │                        │
   │           ▼                        │
   │    POST /customizing/merge ──────► │  (2) Vorschau prüfen (optional, read-only)
   │           │                        │
   │           ▼                        │
   │    POST /customizing/sync ───────► │  (3) Synchronisation durchführen
   │                                    │

Schritt 1 – Export aus Quellsystem (QA):

curl -u admin:password \
  https://qa.example.com/b3p/administration/customizing \
  -o b3p_customizing.zip

Schritt 2 – Merge-Vorschau (optional):

curl -u admin:password \
  -F "file=@b3p_customizing.zip" \
  https://prod.example.com/b3p/administration/customizing/merge \
  -o b3p_customizing_merged.zip

Das zurückgegebene ZIP kann zur Prüfung herangezogen werden, bevor die eigentliche Synchronisation ausgeführt wird.

Schritt 3 – Synchronisation auf Zielsystem (Prod):

curl -u admin:password \
  -F "file=@b3p_customizing.zip" \
  https://prod.example.com/b3p/administration/customizing/sync

Hinweise zur Nutzung in Pipelines

Idempotenz: Der /sync-Endpunkt ist idempotent – eine mehrfache Ausführung mit derselben ZIP erzeugt denselben Zielzustand.
Geschützte Einträge: Auf dem Prod-System sollten lokale, umgebungsspezifische Einträge (z. B. Verbindungsparameter, produktionsspezifische Services) über SYNC_PROTECTED_CUSTOMIZING geschützt werden, damit sie durch einen Sync nicht überschrieben werden.
Split-Format erforderlich: Für /sync und /merge muss die ZIP im Split-XML-Format vorliegen (also ohne EXPORT_SINGLE_XML=true).
Authentifizierung: Es wird die Rolle B2B_ADMIN_CUSTOMIZING benötigt. In Pipelines empfiehlt sich ein dedizierter technischer Benutzer mit genau dieser Rolle.
Transaktionssicherheit: Jeder Customizing-Bereich wird in einer eigenen Transaktion synchronisiert. Bei einem Fehler in einem Bereich bleiben bereits erfolgreich synchronisierte Bereiche erhalten.

Beispiel: GitLab CI/CD Pipeline

stages:
  - promote-customizing

promote-customizing:
  stage: promote-customizing
  script:
    # 1. Export aus QA
    - curl -s -u "$B2B_QA_USER:$B2B_QA_PASS"
        "$B2B_QA_URL/administration/customizing"
        -o customizing_qa.zip
    # 2. Sync auf Prod
    - curl -s -u "$B2B_PROD_USER:$B2B_PROD_PASS"
        -F "file=@customizing_qa.zip"
        "$B2B_PROD_URL/administration/customizing/sync"
  only:
    - main
  environment:
    name: production

Zugangsdaten werden dabei als CI/CD-Variablen (B2B_QA_USER, B2B_QA_PASS, etc.) hinterlegt und nicht im Code gespeichert.

Die Schaltflächen einblenden (Alte UI)

Die Schaltflächen “Customizing hochladen” und “Customizing herunterladen” werden standardmäßig ausgeblendet. Um sie für bestimmte Benutzerrollen einzublenden, muss folgendes Rollenattribut unter Benutzerverwaltung angelegt und einer Rolle zugewiesen werden:

Override={view=GlobalPropertyPanelView,type=SetProperty,target=customizingTransfer,name=visible,value=true}

View Me Edit Me

Customizing Import Export