Installation & Update - Nevaris Middleware Connector - 2024.2.2

Owned by von Reeken, Björn
Dec 11, 2024
9 min read

Einleitung

Der Middleware Connector (MWC) ist ein Dienst, der die Kommunikation zwischen verschiedenen Anwendungen, Systemen oder Technologien ermöglicht.
Er fungiert als Schnittstelle, die es unterschiedlichen Programmen ermöglicht, miteinander zu kommunizieren und Daten auszutauschen, selbst wenn diese auf verteilten Plattformen oder mit verschiedenen Technologien arbeiten.

Er wird eingesetzt, um die Integration verschiedener Softwareanwendungen im Unternehmensumfeld zu erleichtern, indem er die Interoperabilität zwischen ihnen sicherstellt.

Zurzeit wird der MWC für die Anbindung von JobRouter (per SQL-Zugriff) genutzt.

Versionsangaben in den Screenshots können abweichen.

Installation

1. Führen Sie das SetupMwc.exe aus.

2. Wählen Sie den Middleware Connector aus und klicken Sie auf "Weiter".

 

3. Wählen Sie einen User aus, unter dem der Middleware Connector laufen soll und unter welchem Port (Default: 8501) die Weboberfläche erreichbar sein soll, klicken Sie auf "Weiter".

 

4. Hier sehen Sie nochmals eine Zusammenfassung der Installation. Klicken Sie auf "Jetzt installieren".

 

5. Es werden die nötigen Dateien für den Middleware Connector kopiert.

 

6. Der Middleware Connector ist nun vollständig installiert, schließen Sie das Setup.

 

7. Der Middleware Connector erzeugt einen Eintrag unter "Programme und Funktionen".

 

8. Die eigentlichen Programmdateien liegen unter dem Pfad %PROGRAMFILES%\NEVARIS MWC:

 

9. Die Konfigurationsdatei appsettings.json für die Kopier-Jobs zwischen den verschiedenen Datenbanken (beispielsweise einer Finance-Datenbank und einer JobRouter-Datenbank) findet sich im Verzeichnis %PROGRAMDATA%\NEVARIS\MiddlewareConnector. Zusätzlich werden dort Log-Dateien zum Austausch der Daten (mwc*.txt) angelegt.

Die Datei appsettings.json kann auch manuell bearbeitet werden, was im den Abschnitten Job-Konfiguration per appsettings.json und Anpassung der Datenhaltungs-Konfiguration erklärt wird.

10. Unter den Windows-Diensten findet sich ein neuer Dienst, der die Weboberfläche hostet und die Kopierjobs verwaltet.

Weiter geht es mit der Job-Einrichtung.

Benutzerverwaltung

Der MWC bietet eine einfache Kommandozeilen-basierte Benutzerverwaltung. Im Installationsverzeichnis befindet sich dafür das Programm Mwc.exe, mit dem unter anderem ein neuer Benutzer angelegt werden kann:

Die Benutzer werden in der Datei %PROGRAMDATA%\NEVARIS\MiddlewareConnector\users.json, die bei der ersten Anlage eines Benutzers initial erstellt wird. Sobald sie vorhanden ist, ist für den Zugriff auf die Web-Oberfläche die Eingabe von Zugangsdaten erforderlich:

Der Aufruf von .\mwc.exe (ohne Argumente) liefert eine Übersicht über die verfügbaren Befehle:

 

Update

Wenn eine neue Version des MWCs bereit steht, folgen Sie bitte diesem Leitfaden.

  1. Führen Sie das neue SetupMwc.exe aus.

2. Klicken Sie auf "NEVARIS aktualisieren".

 

3. Hier sehen Sie noch einmal eine Zusammenfassung des Updates, klicken Sie auf "Jetzt installieren".

 

4. Verlauf des Updates, Kopieren neuer Dateien.

 

5. Fertigstellung des Updates, klicken Sie auf "Schließen".

 

6. Das Update ist abgeschlossen, der MWC ist aktualisiert.

Einrichten der Jobs via WebClient

Die Einrichtung wird nachfolgend beschrieben am Beispiel der Finance-JobRouter-Schnittstelle (Connect2JR).

Auf dem Server, auf dem der Middleware Connector installiert wurde, lässt sich die Konfigurations-Seite nach Eingabe des Ports, der bei der Installation eingegeben wurde, im Webbrowser öffnen. Initial wird dort eine leere Liste von Jobs angezeigt, mit der Möglichkeit, neue Jobs zu erstellen.

Klicken Sie auf Neuer Job, um einen neuen Job zu erstellen und anschließend auf Bearbeiten, um ihn zu konfigurieren:

Bei einem Job handelt es sich um zeitgesteuerte Datentransfer-Anweisung. Dafür muss konfiguriert werden, von wo Daten gelesen werden (Quelle) und wohin diese geschrieben werden sollen (Ziel). Als mögliche Datenhaltungen kommen aktuell HTTP APIs sowie SQL Server-Datenbanken infrage. Es werden bereits einige konfigurierte Datenhaltungen ausgeliefert, die jeweils im Feld Datenhaltung für Quelle und Ziel ausgewählt werden:

Es wird empfohlen die drei folgenden Jobs wie folgt anzulegen:

Job Nr. 1: Export

Beschreibung: Übertragung der Stammdaten aus Finance in die SQL-Datenbank.

  1. Quelle: Datenhaltung FINExport, zusätzliche Informationen sind im Kapitel Einrichtungen zu HTTP-APIs (Datenhaltungen beginnend mit FIN) beschrieben.

  2. Ziel: Datenhaltung JRExport, die zusätzliche Einrichtung ist im Kapitel Einrichtungen zu SQL-Datenbanken (Datenhaltungen beginnend mit JR) beschrieben.

Nach erfolgter Einrichtung den Job speichern und mit der Aktion "Duplizieren" den zweiten Job anlegen. Den neu angelegten Job über "Bearbeiten" wie folgt anpassen:

Job Nr. 2: BK_Status und Upload

Beschreibung: Übertragung der Statusupdates vom BK_Status und optional die Übertragung der weiteren Rechnungs- und Kontierungsdaten wenn der Upload-Schritt im REBU-Import verwendet wird.

Im duplizierten Job muss jeweils für Quelle und Ziel die Datenhaltung angepasst werden. Je nach verwendeten Umfang (REBU, RABU, etc.) der Schnittstelle, weicht die auszuwählende Datenhaltung ab. Zur Auswahl stehen die Datenhaltungen:

  • JRRebuOhneExport und FINRebuOhneExport: Rechnungseingangsbuch

  • JRRebuRabuOhneExport und FINRebuRabuOhneExport: Rechnungseingangsbuch und Rechnungsausgangsbuch

  • JRRebuRabuKabuOhneExport und FINRebuRabuKabuOhneExport:  Rechnungseingangsbuch, Rechnungsausgangsbuch und Kassenbuch

  • JRRebuRabuKabuUrlaubOhneExport und FINRebuRabuKabuOhneExport: Rechnungseingangsbuch, Rechnungsausgangsbuch, Kassenbuch und Urlaubsanträge

Die endgültige Auswahl der Datenhaltungen sieht dann wie folgt aus:

  1. Quelle: Datenhaltung FIN***OhneExport

  2. Ziel: Datenhaltung JR***OhneExport

Nach erfolgter Einrichtung den Job speichern und mit der Aktion "Duplizieren" den dritten Job anlegen. Den neu angelegten Job über "Bearbeiten" wie folgt anpassen:

Job Nr. 3: Import

Beschreibung: Ermittlung und Übertragung der zu importierenden Datensätze.

Über die Pfeile zwischen Quelle und Ziel die Richtung tauschen, dass als Quelle die SQL-Datenbank verwendet wird und als Ziel die HTTP API.

Die endgültige Auswahl der Datenhaltungen sieht dann wie folgt aus:

  1. Quelle: Datenhaltung JR***OhneExport

  2. Ziel: Datenhaltung FIN***OhneExport

Einrichtungen zu HTTP-APIs (Datenhaltungen beginnend mit FIN)

Ermöglicht den Zugriff auf die von Finance per HTTP API veröffentlichten Daten (lesend und schreibend). Für die Konfiguration ist die Eingabe der API-Basisadresse (URI) erforderlich sowie die notwendigen Zugangsdaten.

  • Datenhaltung: FIN***

  • URI: https://Webserver:OData-Port/Mittelschicht/api/nevaris/financeworkflow/v2.0/companies(ID des Mandanten). Die ID des Mandanten kann über die Seitenüberprüfung in der Mandantenübersicht oder alternativ über einen GET-Request des Endpunktes /companies der Finance API (https://Webserver:OData-Port/Mittelschicht/api/nevaris/finance/v2.0/companies) ermittelt werden. Damit die API "financeworkflow" vollständig initialisiert wird, ist das Öffnen der entsprechenden Einrichtung "Workflow Standorte" in Finance erforderlich.

  • Authentifizierung:

Einrichtungen zu SQL-Datenbanken (Datenhaltungen beginnend mit JR)

  • Datenhaltung: JR***

  • SQL-Server: Name des SQL-Servers inkl. Instanz

  • Datenbank: Name der Datenbank

  • Integrated Security: Aktivierung/Deaktivierung von Integrated Security

  • Benutzer: Angabe des SQL-Benutzers. In diesem Fall ist ein dbo-Benutzer erforderlich, da im Rahmen der Ausführung des Jobs für die Richtung Finance → JobRouter die Stammdatentabellen angelegt werden, sofern diese noch nicht angelegt sind.

  • Passwort: Passwort des SQL-Benutzers.

  • Weitere Argumente: Die genannten Felder bilden den Connection String für den SQL-Server, welcher bei Bedarf durch weitere Argumente erweitert werden kann.

In einigen Fällen wie z. B. abweichenden Tabellennamen vom Standard (Beispiel: REBU_JR statt REBUKOPF) kann es erforderlich, eigene Konfigurationen zu erstellen. Die Vorgehensweise wird im unten stehenden Kapitel Anpassung der Datenhaltungs-Konfiguration beschrieben.

Abgesehen von Quelle und Ziel kann noch der Name des Jobs festgelegt werden sowie (optional) eine Cron-Anweisung, die angibt, zu welchen Zeitpunkten der Job ausgeführt, das heißt ein Datentransfer von der Quelle zum Ziel stattfinden soll. Die Cron-Anweisung ist Sekunden-basiert, das heißt, die erste Zahl gibt an, zu welchen Sekunden-Werten der Job ausgeführt wird. Es folgen Minuten und Stunden. Die initial vorgeschlagene Anweisung 0 0 * * * ? bedeutet: Führe den Job genau zu jeder vollen Stunde aus. Eine detaillierte Beschreibung der Cron-Syntax findet sich hier.

Ein vollständig konfigurierter Job sieht zum Beispiel so aus:

Abgesehen von der Möglichkeit, Jobs zu erstellen und zu bearbeiten, gibt es noch weitere Funktionen:

  • Löschen: Löscht einen Job nach einer Sicherheitsabfrage.

  • Duplizieren: Erstellt eine Kopie eines Jobs unter neuem Namen.
    Tipp: Häufig möchte man zusätzlich zu einem bestehenden Job einen weiteren Job erstellen, der Daten in die entgegengesetzte Richtung (das heißt vom Ziel in die Quelle) transferiert. Dies kann durch Duplizieren des Jobs und anschließendem Vertauschen von Quelle und Ziel (mithilfe des Buttons ⇆) erreicht werden.

  • Ausführen: Startet den Datentransfer unabhängig von der Cron-Anweisung.

  • Stoppen: Bricht die Ausführung eines Datentransfers ab.

  • Aktivieren/Deaktivieren eines Jobs: Standardmäßig ist ein Job aktiv, d.h. er wird gemäß der per Cron-Anweisung definierten Zeitplanung periodisch ausgeführt. Durch Entfernen des Aktiv-Häkchens wird diese Zeitplanung deaktiviert. Der Job kann aber trotzdem per Ausführen-Funktion explizit angestoßen werden.

  • Aktivieren/Deaktivieren der gesamten Job-Verarbeitung: Wenn dieses Häkchen entfernt wird, wird kein Job mehr automatisch gestartet. Ein explizites Ausführen einzelner Jobs ist weiterhin möglich.


Job-Konfiguration per appsettings.json

Die über die Web-Oberfläche erfolgte Konfiguration der Jobs wird in der Datei %PROGRAMDATA%\NEVARIS\MiddlewareConnector\appsettings.json abgespeichert. Der Inhalt sieht z.B. auszugsweise so aus und kann auch von Hand bearbeitet werden:

Anpassen der Basisadresse (URL mit Port)

In der Datei %PROGRAMDATA%\NEVARIS\MiddlewareConnector\appsettings.json ist neben der Job-Konfiguration auch der URL hinterlegt, über den die Web-Oberfläche erreichbar ist. In diese fließt der im Setup eingegeben Port ein, z.B.:

Ein nachträgliches Ändern des URLs ist möglich und erfordert einen Neustart des NEVARIS MiddlewareConnector-Diensts:

Die Angabe mehrerer URLs ist möglich (per Semikolon getrennt, z.B.: "Urls": "http://localhost:5210;https://localhost:7180").

Anpassen der Datenhaltungs-Konfiguration

Der MWC wird bereits vorgefertigten Konfigurationen ausgeliefert. Diese Konfigurationen liegen im Programmverzeichnis. Außerdem befindet sich im Programmverzeichnis die Datei appsettings.json, in der die Konfigurationsdateien eingebunden werden:

Zum Anpassen der Konfiguration sollten diese Dateien nicht modifiziert werden, da sie Teil der Installation sind. Es ist aber möglich, Inhalte der ausgelieferten appsettings.json-Datei zu überschreiben, indem man in der oben genannten %PROGRAMDATA%\NEVARIS\MiddlewareConnector\appsettings.json den relevanten Abschnitt neu definiert, z.B:

Die hier referenzierten Dateien my-configuration-finance.json und my-configuration-jobrouter.json werden in %PROGRAMDATA%\NEVARIS\MiddlewareConnector erwartet. Sie können durch Kopieren und Anpassen der ausgelieferten configuration-finance.json und configuration-jobrouter.json entstanden sein.

Sofern mehrere Konfigurationen pro Quelle-Ziel-Verbindung benötigt werden, ist es erforderlich der entsprechenden configuration.json-Datei eine eigene Id zu vergeben und diese Id anschließend in den DataStores der appsettings.json zu ergänzen. In der Konfiguration des jeweiligen Jobs können diese dann über die Datenhaltung ausgewählt werden.

 Sollten in den JobRouter-Importtabellen Felder enthalten sein, die nicht den entsprechenden Datentypen des Standard-Importumfangs entsprechen, müssen diese in der config-finance.json oder einer alternativen config-finance.json in den "FieldMappings" der "WriteOptions" ergänzt werden. Beispielhafter Aufbau:

"WriteOptions": { "OutputStringForNullDate": "0001-01-01T00:00:00Z", "FieldMappings": [ { "DataSet": "Rebukopf", "SourceField": "Feld1", "TargetField": null }, { "DataSet": "Rebuzeile", "SourceField": "Feld1", "TargetField": null } ] }

Weitere detaillierte Erläuterungen für verschiedenste Fälle am Beispiel JobRouter Im- und Export ist in der Online-Hilfe zu finden.

 

 

Gehen Sie nun zurück zur Hauptseite und folgen der weiteren Anleitung
NEVARIS Finance Version 2024.2