Dokumentation für B2B-Migration-Tool

B2B-Migration-Tool

Das B2B-Migrationstool ist eine Jar-Kommandozeilenanwendung. Es unterstützt zwei Hauptfunktionalitäten:

  1. Migration von Datenbankbenutzern zu Keycloak
  2. Migration von Arbeitsvorräten

Nachfolgend finden Sie die Beispielkonfigurationsdatei application.yml. Es müssen nicht alle Felder konfiguriert werden, je nach dem ob eine lokale oder eine Migration via SSH durchgeführt werden soll. Bitte beachten Sie dazu die Kommentare in der folgenen Beispielkonfiguration. Bitte kopieren Sie das komplette folgende Konfigurationsbeispiel, um das Migrationstool zu starten:

spring:
  main:
    banner-mode: off

# Keycloak configuration  
keycloak:
  serverUrl: http://localhost:9789/auth
  realm: master
  username: realm username
  password: realm password
  clientId: admin-cli

database:
  # Database driver which based on the database type this application need  to connect. Example can refer to https://www.codejava.net/java-se/jdbc/jdbc-driver-library-download database-connection-url-for-common-databases
  driver: org.postgresql.Driver
  # Database URL connection
  url: jdbc:postgresql://localhost:portnumber/DatabaseName
  username: dbUsername123
  # should quote '' the password value 
  password: 'password123'
  # below contains two select statement, where second statement is for migration which will check user enddate whether is expired. Please use either one
  selectTableSql: SELECT * FROM b2bbp_adm_account
  selectTableSql: SELECT * FROM b2bbp_adm_account LEFT JOIN b2bbp_adm_account_date_range ON b2bbp_adm_account.userid = b2bbp_adm_account_date_range.userid
  # basicColumns are columns from db, where it must be provided and migrate to keycloak. Below contain two example of configuration one is for migration which will check user expiration enddate. Please use either one
  basicColumns: username:userid;firstname:firstname;lastname:lastname;email:email;enddate:enddate;
  basicColumns: username:userid;firstname:firstname;lastname:lastname;email:email;
  # attributesColumns are columns from db, where is not necessary to be provided for keycloak user attribute
  attributeColumns: organization;password
  # attributeColumns:

ssh:
  # if database require SSH connection, then enable must be true
  enable: false
  # provide ldap username and password for ssh connection
  username: Ldap account
  password: Ldap password
  host: Ssh server
  port: 22
  remoteDbServer: Remote Database server name
  # Remote database server port number
  remoteDbPort: 5413
  # local db port must same as above database url port, else connection will fail
  localDbPort: 5437

output:
  filePath: ..\\..\\OutputDirectory\\Result.txt

Datenbankbenutzer-Migration zu Keycloak

Um die neue B2B-Benutzeroberfläche verwenden zu können, müssen alle Benutzer und die dazugehörigen Rollen mit Keycloack verwaltet werden. Das bedeutet, dass die Benutzer und Rollen nicht mehr in der B2B-Datenbank gespeichert werden. Daher müssen die Benutzerdaten von der bisherigen Datenbank auf den keycloak-Server migriert werden. Anmerkung: Bei der Benutzermigration werden nur Benutzer ohne Kennwort migriert.

Anforderungen des Migrationstools

Bevor mit der Benutzermigration zu Keycloak begonnen werden kann, müssen einige Voraussetzungen erfüllt sein, die zur Einrichtung erforderlich sind.

  1. Keycloak Server - Version > 10.0.0
    • Keycloak-Zugriffsrechte erforderlich: Lesen und Schreiben.
    • Einrichten eines Keycloak-Benutzers für die Verwendung bei der Migration
  2. B2B-Datenbank mit Zugang
    • Datenbank-Zugriffsrechte erforderlich: Nur Lesen.
  3. Java - Version >= 1.8
  4. LDAP-Konto
  5. Erstellen einer eigenen Datei application.yml durch Kopieren des obigen Beispielinhalts

Keycloak-Benutzer einrichten

Um das Migrationstool erfolgreich auszuführen, muss ein Keycloak Server laufen, sowie entsprechnde Clients und Benutzer vorhanden sein. Folgende Schritte sind dazu notwendig:

  1. Wenn Keycloak neu eingerichtet ist und kein Realm hat, erstellen Sie bitte einen neuen Realm, andernfalls können Sie einen bestehenden für die Benutzermigration verwenden.
    • Einen neuen Realm erstellen:
  2. klicken Sie dann unter dem gewünschten Realm auf Clients, um einen neuen Client zu erstellen.
    • Nachdem der neue Client erstellt wurde, stellen Sie sicher, dass der Access Type = public und die Einstellung Direct Access Grants Enabled = ON ist.
  3. Nachdem Sie den Client erstellt haben, erstellen Sie eine neue Rolle
    • Nach dem Speichern aktivieren Sie für die neu hinzugefügte Rolle dann die Composite Roles EIN. Geben Sie dann in Client Roles “realm-management” ein und fügen Sie dann alle verfügbaren Rollen hinzu.
  4. Nachdem Sie eine neue Rolle erstellt haben, gehen Sie zum Reiter Users, um die Rolle dem Benutzer zuzuweisen. Es kann ein vorhandener Benutzer verwendet werden oder ein neuer Benutzer angelegt werden.
    • Falls Sie für die Migration einen neuen Benutzer anlegen möchten, müssen Sie sicherstellen, dass das Kennwort nach dem Anlegen des Benutzers korrekt eingestellt ist. Temporär sollte ausgeschaltet sein.
    • Gehen Sie dann zum Konfigurieren zur Registerkarte Role Mappings. Fügen Sie in Realm Roles die neu hinzugefügte Migrationsrolle zu Assigned Roles hinzu. Geben Sie dann unter Client Roles den neu hinzugefügten Client ein, z.B. migration-cli.
  5. Nach der Konfiguration sollten alle oben genannten Relams, Client- und Benutzereinstellungen in der Datei application.yml verwendet werden.

Schritte zum Ausführen des Migrationstools

Nachdem Sie die b2b-Migrations-Tool-Jar-Datei erhalten haben, starten Sie eine CMD-Eingabeaufforderung, um die Anwendung auszuführen. Folgen Sie dann den folgenden Schritten:

  1. Erfordert die b2b-migration-tool jar-Datei und die passenden Datenbanktreiber jar-Datei z.B. Verknüpfung, Hinweis: die Migration kann mit jeder Datenbank durchgeführt werden, solange der richtige Treiber verwendet wird.
  2. Nachdem Sie beide Jar-Dateien erhalten haben, erstellen Sie einen Ordner, z.B. b2b-migration-tool, dann erstellen Sie zwei Ordner innerhalb des Verzeichnisses, z.B.:
    • Legen Sie dann beide jar-Dateien in den lib-Ordner
    • Und erstellen Sie dann die Datei application.yml und legen diese in den config-Ordner
  3. Nachdem die Einrichtung des Ordners abgeschlossen ist, starten Sie die Eingabeaufforderung und geben Sie folgenden Befehl ein: java -cp …filepath...\config\;…filepath...\lib* org.springframework.boot.loader.JarLauncher
  4. Nachdem Sie den obigen Befehl ausgeführt haben, wird ein Konsolenmenü angezeigt:
  5. Wählen Sie den 1. Punkt um die bisherigen Benutzer aus der Datenbank nach Keycloak zu migrieren
  6. Vergewissern Sie sich, ob die obige Datei application.yml korrekt konfiguriert wurde. Nur dann kann die Anwendung erfolgreich ausgeführt werden. Details können Sie dem obigen Beispiel der application.yml und der darin enthaltenen Kommentare entnehmen.
  7. Die application.yml enthält eine filePath-Konfiguration. Dort werdenim Fehlerfall weitere Informationen hinterlegt.

Migration von Arbeitsvorräten

Wenn Kunden die neue B2B-Benutzeroberfläche verwenden und erwarten, dass die bisherigen Arbeitsvorräte weiter verwendet werden können, dann hilft diese Migration bei der Migration von der alten Konfiguration zur neuen Konfiguration. Die alte Konfiguration bezieht sich auf die Definition eines Arbeitsvorrats, so wie dieser in der Tabelle b2bbp_adm_role_attribute gespeichert ist. Dann bereinigt das Migrationstool die Daten und migriert sie nach b2bbp_adm_extension mit dem neuen Datentyp = “WORKLISTS”. Anmerkung: Das Migrationstool migriert bisher nur den Worklist-Typ = “MSGMON”.

Anforderungen

Bevor mit der Migration der Arbeitsvorräte begonnen wird, sind einige Anforderungen zu erfüllen:

  1. B2B-Datenbank mit Zugang
    • Erforderliche Datenbank-Zugriffsrechte: Lesen und Schreiben.
  2. Java - Version >= 1.8
  3. LDAP-Konto
  4. Erstellen einer eigenen Datei application.yml durch Kopieren des obigen Beispielinhalts

Schritte

Nachdem Sie die b2b-Migrations-Tool-Jar-Datei erhalten haben, starten Sie eine CMD-Eingabeaufforderung, um die Anwendung auszuführen. Folgen Sie dann den folgenden Schritten:

  1. Erfordert die b2b-migration-tool jar-Datei und die Datenbanktreiber jar-Datei, z.B. https://www.codejava.net/java-se/jdbc/jdbc-driver-library-download. Hinweis: die Migration kann mit jeder Datenbank durchgeführt werden, solange der richtige Treiber verwendet wird.
  2. Nachdem Sie beide Jar-Dateien erhalten haben, erstellen Sie einen Ordner, z.B. b2b-migration-tool, dann erstellen Sie zwei Ordner innerhalb des Verzeichnisses, z.B.:
    • Legen Sie dann beide jar-Datein in den lib-Ordner
    • Und erstellen Sie dann die Datei application.yml und legen diese in den config-Ordner
  3. Nachdem die Einrichtung des Ordners abgeschlossen ist, starten Sie die Eingabeaufforderung und geben Sie folgenden Befehl ein: java -cp …filepath...\config\;…filepath...\lib* org.springframework.boot.loader.JarLauncher
  4. Nachdem Sie den obigen Befehl ausgeführt haben, wird ein Konsolenmenü angezeigt:
  5. Wählen Sie die 2. Auswahl um die Arbeitsvorräte zu migrieren
  6. Für die Migration der Arbeitsvorräte ist nur die Konfiguration des Datenbanktreibers, der URL, des Benutzernamens, des Kennworts und des Ausgabedateipfads(filePath) erforderlich. Andere Konfigurationen sind nicht erforderlich.
  7. Wenn die Migration erneut ausgeführt wird, überschreibt sie die vorhandenen Daten mit den neuen Daten aus der alten Tabelle. Die application.yml enthält die filePath-Konfiguration, die der Benutzer konfigurieren kann, um zu wissen, welche alten Daten überschrieben wurden.
View Me   Edit Me