DataMigrate PRO Synch-Service

Diese Dokumentation beschreibt die Installation und den Betrieb des DataMigrate PRO Service-Bus-Listeners als Windows-Dienst unter dem Namen „DataMigrate PRO Synch-Service“. Die Anleitung basiert auf den verfügbaren CLI-Referenzen und den Vorgaben für settings.json.

Überblick

Der Befehl

DataMigratePro -t listen --install "DataMigrate PRO Synch-Service" --registration "<dein-registrierungsschlüssel>" --tenantid "<deine-tenant-id>"

Führt nacheinander die folgenden Schritte aus:

1. -t listen startet den Azure Service Bus Listener von DataMigrate PRO. Für den produktiven Betrieb werden die Verbindungseinstellungen aus settings.json geladen.
2. --install "DataMigrate PRO Synch-Service DWP" installiert den Listener im Windows-Dienst-Wrapper (Launcher) und richtet den angegebenen Dienstnamen ein.
3. --registration ... --tenantid ... prüft und speichert den Registrierungs-/Lizenzschlüssel sowie den Azure AD Mandanten. Ohne gültige Registrierung verweigert das Tool nach kurzer Zeit den Dienstbetrieb.

Voraussetzungen

• Windows-Server mit Administratorrechten (erforderlich für die Dienstinstallation).
• Kopie des DataMigratePro-Programmordners (inkl. DataMigratePro.exe, settings.json).
• Netzwerkzugriff auf:
  • SQL Server der Business Central Datenbanken.
  • Business Central OData-Endpunkt (Upload_LoadData).
  • Azure Service Bus Namespace für eingehende Aufträge.
• SQL Berechtigungen für den Dienst User
  • Mindestens db_reader auf Business Central Datenbanken
  • Sofern die Migrations- und die Mapping-Datenbank angelegt wurde auf diese db_owner Berechtigung geben
• Registrierungs-Key (--registration) und Azure AD Tenant-ID (--tenantid).

Installationsschritte

1. Ordner vorbereiten
   • Kopieren Sie den gesamten Lieferumfang nach C:\Programme\DataMigratePro (oder ein anderes Ziel ohne Leerzeichen im Pfad).
   • Stellen Sie sicher, dass DataMigratePro.exe und settings.json erreichbar ist, und dass der Service User berechtigt ist im Pfad das Logs-Verzeichnis anlegen darf und dort Log-Dateien beschreiben darf.
2. settings.json anlegen/anpassen
   • Erstellen oder aktualisieren Sie settings.json im Installationsordner entsprechend dem Beispiel im Abschnitt Beispielkonfiguration.
3. Registrierung vorbereiten
   • Öffnen Sie eine administrative PowerShell.
   • Navigieren Sie in den Installationsordner: cd C:\Programme\DataMigratePro.
4. Registrierung ausführen
   • Führen Sie den Befehl oben aus, aber ohne --install, um Lizenz- und Service-Bus-Daten zu validieren:
   • .\DataMigratePro.exe -t listen –registration „<dein-registrierungsschlüssel>“ –tenantid „<deine-tenant-id>“
   • Bei Erfolg werden die Service-Bus-Parameter (Queue-Namen, Connection String) in settings.json ergänzt.
5. Dienst installieren
   • Starten Sie anschließend die endgültige Installation:.\DataMigratePro.exe -t listen –install „DataMigrate PRO Synch-Service“ –registration „<dein-registrierungsschlüssel>“ –tenantid „<deine-tenant-id>“
   • Der Launcher registriert einen Windows-Dienst. Die Log-Ausgabe wird in das Windows-Ereignisprotokoll umgeleitet.
6. Dienst starten
   • Öffnen Sie services.msc, suchen Sie DataMigrate PRO Synch-Service DWP, setzen Sie den Starttyp auf Automatisch und starten Sie den Dienst.

Funktionsweise des Service-Bus-Listeners

• Der Listener überwacht die konfigurierte RequestQueueName auf eingehende Nachrichten. Jede Nachricht löst die Datenverarbeitungs-Pipeline von DataMigrate PRO aus.
• Antworten und Statusmeldungen werden auf ResponseQueueName geschrieben.
• Die Schleife läuft dauerhaft und nutzt kurze Polling-Intervalle (ca. 1 Sekunde), um neue Nachrichten zu erkennen.
• Fehler werden in das Windows-Ereignisprotokoll geschrieben; bei schwerwiegenden Fehlern stoppt der Dienst mit einem entsprechenden Fehlercode.

Konfiguration in Business Central

• n der Business-Central-Erweiterung muss dieselbe connectionId hinterlegt sein wie in der settings.json, damit Nachrichten eindeutig dem Listener zugeordnet werden.
• Verwenden Sie nach Möglichkeit eine eindeutig generierte Kennung (z. B. GUID oder generiertes Passwort) als connectionId, um Überschneidungen mit weiteren Integrationen auszuschließen.
• In der Business-Central-Konfiguration wird außerdem der Endpunkt der vorbereiteten Azure Function samt dem in Azure generierten Zugriffsschlüssel hinterlegt. Nur so kann die Anwendung Nachrichten erfolgreich in die Service-Bus-Queue einstellen.

Beispielkonfiguration (settings.json)

{
  "SqlConnectionString": "Data Source=SQLSERVER;Initial Catalog=BC_PROD;Integrated Security=SSPI;",
  "SourceCompany": "CRONUS AG",
  "DestinationCompany": "CRONUS AG",
  "SourceDatabase": "BC_PROD",
  "MappingDatabase": "BC_PROD",
  "MigrationDatabase": "BC_MIGRATION",
  "EndpointUrl": "https://api.businesscentral.dynamics.com/v2.0/<deine-tenant-id>/Production/ODataV4/Upload_LoadData?company=CRONUS%20AG",
  "BlobMagicSignature": [2, 69, 125, 91],
  "IsSaaS": true,
  "Environment": "Production",
  "TenantInfo": {
    "TenantId": "<deine-tenant-id>",
    "ClientId": "<Azure AD App ID>",
    "ClientSecret": "<Azure AD App Secret>"
  },
  "HttpClientTimeoutSeconds": 100,
  "ServiceBus": {
    "ServiceBusConnectionString": "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<Name>;SharedAccessKey=<Key>",
    "RequestQueueName": "<deine-request-queue>",
    "ResponseQueueName": "<deine-response-queue>",
    "connectionId": "<deine-connection-id>"
  }
}

Hinweise:

• Die ServiceBus-Sektion ist zwingend erforderlich für -t listen. Fehlende Werte führen beim Start des Dienstes zu einer Validierungs-Exception.
• Stimmen Sie die hier eingetragene connectionId mit der Konfiguration in Business Central ab. Verwenden Sie eine eindeutige Kennung, um Fehlzuordnungen zu vermeiden.
• TenantInfo wird für SaaS/OAuth benötigt. Für On-Premises-Betrieb setzen Sie IsSaaS auf false und verwenden BCUser/BCPassword statt TenantInfo.
• BlobMagicSignature kann übernommen werden, sofern keine individuelle Vorgabe vorliegt.
• Weitere optionale Einstellungen wie SqlConnectionStringMigration oder AppSourceEnabled können bei Bedarf ergänzt werden.

Überprüfung und Wartung

1. Dienststatus prüfen
   • Get-Service "DataMigrate PRO Synch-Service" in PowerShell aufrufen.
2. Logausgaben kontrollieren
   • Ereignisanzeige → Anwendungs- und Dienstprotokolle → DataMigratePro.
3. Einstellungen anpassen
   • Dienst vorher stoppen, settings.json bearbeiten, Dienst neu starten.
4. Dienst deinstallieren
   • DataMigratePro.exe --uninstall "DataMigrate PRO Synch-Service" ausführen.

Troubleshooting