Differences

This shows you the differences between two versions of the page.

--- de:cobi.wms:teamzaehlerdienst [2026/02/17 14:16] – created thuth
+++ de:cobi.wms:teamzaehlerdienst [2026/02/18 13:26] (current) – [6. Nachträgliche Konfiguration (appsettings.json)] thuth
@@ Line 1: / Line 1: @@
-===== Teamzählerdienst =====
+====== Einrichtung des Teamzählerdienstes (InventoryCountingService) ======
+Der COBI.wms InventoryCountingService ist ein separater Windows-Dienst, der speziell für umfangreiche Teamzählungen bei der Inventur entwickelt wurde. \\
+Er nimmt die erfassten Bestandszählungen der Handscanner asynchron entgegen und verarbeitet sie im Hintergrund. \\
+Dies hat den großen Vorteil, dass die App der Benutzer nach dem Senden nicht blockiert wird und diese sofort weiterarbeiten können.
+===== 1. Vorbereitungen (Management Datenbank) =====
+Bevor der Dienst installiert wird, muss die COBI.wms Management-Datenbank um zwei Felder erweitert werden. \\
+Führen Sie dazu folgendes SQL-Skript auf Ihrer Management-Datenbank aus:
+<code sql>
+ALTER TABLE COBIWMS.COMPANIES ADD (
+INCAPIURL VARCHAR(255),
+INCAPIKEY VARCHAR(255)
+);
+</code>
+Hinweis: Dieses SQL-Skript kann unverändert sowohl für Microsoft SQL Server als auch für SAP HANA Datenbanken verwendet werden.
+===== 2. Installation des Windows Dienstes =====
+{{ :de:cobi.wms:cobi.wms-inventorycounting-service.setup.exe |COBI.wms Teamzählerdienst.exe}} \\
+  - Führen Sie die Setup-Datei für den Windows-Dienst (''COBI.wms.InventoryCounting.service.exe'') auf dem designierten Windows-Server aus.
+  - Während der Installation fragt der Assistent verschiedene Konfigurationsparameter ab:
+    * Datenbanktyp: Per Dropdown lässt sich hier der Datenbanktyp auswählen
+    * SAP Server: Tragen Sie hier die Adresse und den Port Ihres SAP-Servers ein (Format: ''IP:PORT'', z.B. ''192.168.0.1:30015'').
+    * SAP Datenbank: Tragen Sie hier bitte den Datenbanknamen/Datenbankmandanten ein.
+    * SAP User: Tragen Sie hier den SAP Benutzernamen ein.
+    * SAP Passwort: Tragen Sie hier das SAP Passwort ein.
+    * Cron Expression: Hier legen Sie fest, in welchem zeitlichen Intervall der Dienst die empfangenen Zählungen verarbeiten soll (Hilfe zur Cron-Syntax finden Sie unter [[https://crontab.guru/|crontab.guru]]).
+    * API Key: Legen Sie einen sicheren API-Schlüssel fest. Dieser authentifiziert später die Verbindung zwischen den Handscannern (App) und diesem Dienst.
+    * Hangfire User & Password: Vergeben Sie hier Zugangsdaten. Diese werden später für den Zugriff auf das Überwachungs-Dashboard (Hangfire) benötigt.
+{{:de:cobi.wms:inventory_setup_config.png?600|Konfigurationsschritt im Setup-Assistenten}}
+Schließen Sie das Setup ab. Der Windows-Dienst wird im Anschluss automatisch registriert und gestartet. \\
+Sie können dies in der Windows-Diensteverwaltung (''services.msc'') überprüfen.
+===== 3. Firewall & Datenbank-Update =====
+Wichtig: Port-Freigabe \\
+Der Dienst läuft standardmäßig auf dem Port 61000. \\
+Es ist zwingend erforderlich, dass dieser Port in der Windows-Firewall des Servers für die Handscanner (WLAN/Netzwerk) erreichbar ist!
+Nach der erfolgreichen Installation müssen Sie der COBI.wms Management-Datenbank noch mitteilen, wo der Dienst zu finden ist. \\
+Führen Sie dazu folgendes Update-Skript aus (passen Sie IP-Adresse, Port, API-Key und Company Name an Ihre Umgebung an):
+<code sql>
+UPDATE COBIWMS.COMPANIES
+SET INCAPIURL = 'http://10.10.10.20:61000/api/v1/',
+INCAPIKEY = 'IHR_GEWÄHLTER_API_KEY'
+WHERE COMPANY = 'Ihr_SAP_Company_Name';
+</code>
+===== 4. Überwachung via Hangfire Dashboard =====
+Der Dienst bringt ein eigenes Dashboard zur Überwachung der Hintergrundprozesse mit.
+  - Öffnen Sie auf dem Server einen Browser und rufen Sie die Adresse ''http://localhost:61000/hangfire'' auf.
+  - Loggen Sie sich mit dem Hangfire User und Password ein, das Sie bei der Installation (Schritt 2) vergeben haben.
+  - Unter dem Reiter "Wiederholende Aufträge" sehen Sie den geplanten Cronjob. Wenn Sie nicht auf das nächste automatische Intervall warten möchten, können Sie die Verarbeitung hier auch jederzeit manuell über den Button "Jetzt ausführen" anstoßen.
+{{:de:cobi.wms:inventory_hangfire_dashboard.png?1200|Hangfire Dashboard - Wiederholende Aufträge}}
+===== 5. Funktionsweise & Limitierungen =====
+Wenn die Scanner Daten an den Dienst senden, speichert dieser die Zählungen zunächst unter "Requests". \\
+Bei der Verarbeitung (Cronjob) gilt folgende Logik:
+  - Zusammenfassung (verschiedene User): Zählen unterschiedliche User den gleichen Artikel, werden die Zählmengen vom Dienst zusammenaddiert.
+  - Überschreiben (gleicher User): Zählt derselbe User denselben Artikel mehrfach (z.B. Korrektur), werden die älteren Einträge ignoriert und nur die neueste Zählung wird verarbeitet.
+Hinweis zur Performance: \\
+Die Verarbeitungsgeschwindigkeit ist maßgeblich durch SAP Business One limitiert, nicht durch den COBI.wms Dienst. \\
+Als grober Richtwert: Für eine Bestandszählung mit ca. 5.000 Zeilen und 11 Zählern benötigt das SAP-System ca. 2 Stunden für die Verarbeitung.
+Erfahrung für den Anwender: \\
+Der App-User bekommt von diesem Hintergrundprozess nichts mit. \\
+Sobald die Daten erfolgreich an den Dienst übergeben wurden, kann der User in der App ohne Wartezeit direkt weiterarbeiten.
+===== 6. Nachträgliche Konfiguration (appsettings.json) =====
+Sollte es notwendig sein, die Konfiguration nach der ursprünglichen Installation anzupassen (z. B. wenn sich das SAP-Passwort ändert oder ein anderer Port für Hangfire genutzt werden soll), muss das Setup nicht erneut ausgeführt werden. \\
+Sie können die Änderungen direkt in der Konfigurationsdatei vornehmen.
+Navigieren Sie dazu in das Installationsverzeichnis des Windows-Dienstes (standardmäßig unter ''C:\COBI.wms-inventorycounting-service'' oder ähnlich) und öffnen Sie die Datei **''appsettings.json''** mit einem Texteditor (als Administrator).
+Die Konfiguration ist in verschiedene Blöcke unterteilt. \\
+Hier ist eine Übersicht der wichtigsten Felder und ihrer Funktion:
+  * Kestrel -> Endpoints -> Http -> Url: Der Port, auf dem der Dienst und das Hangfire-Dashboard laufen (Standard: ''http://0.0.0.0:61000''). Ändern Sie hier die Portnummer am Ende, falls der Standardport belegt ist.
+  * SAP -> Server: Adresse und Port des SAP-Servers.
+  * SAP -> Database: Name der SAP-Firmendatenbank.
+  * SAP -> User / Password: Die Anmeldedaten für SAP Business One.
+  * SAP -> DatabaseType: Der ausgewählte Datenbanktyp (z. B. ''dst_HANADB'' oder ''dst_MSSQL2016'').
+  * Jobs -> UpdateInventoryCountingJobCron: Das Intervall (Cron-Ausdruck) für die asynchrone Verarbeitung.
+  * Hangfire -> User / Password: Die Zugangsdaten für das Überwachungs-Dashboard.
+  * Api -> Key: Der Authentifizierungsschlüssel für die Verbindung zwischen Handscanner und Dienst.
+> **Wichtig: Umgang mit Passwörtern** \\
+> Wenn Sie ein Passwort (z. B. im Block `"SAP"` oder `"Hangfire"`) ändern möchten, tragen Sie das neue Passwort einfach im **Klartext (Plaintext)** in die ''appsettings.json'' ein. Speichern Sie die Datei und starten Sie den Windows-Dienst über die Diensteverwaltung (''services.msc'') neu. \\
+> Der Dienst erkennt beim Start automatisch, dass es sich um Klartext handelt, und **hashed** das Passwort umgehend. Wenn Sie die Datei danach erneut öffnen, sehen Sie anstelle Ihres Passworts nur noch den unleserlichen Hash-Wert.