COBISOFT Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

====== Setting Up the Team Counting Service (InventoryCountingService) ======

The COBI.wms InventoryCountingService is a separate Windows service developed specifically for extensive team counting during inventory. \\
It receives the captured inventory counts from the handheld scanners asynchronously and processes them in the background.\\
This has the great advantage that the users' app is not blocked after sending, allowing them to continue working immediately.

===== 1. Preparations (Management Database) =====
Before installing the service, two fields must be added to the COBI.wms management database. \
To do this, execute the following SQL script on your management database:

<code sql>
ALTER TABLE COBIWMS.COMPANIES ADD (
INCAPIURL VARCHAR(255),
INCAPIKEY VARCHAR(255)
);
</code>
Note: This SQL script can be used without modification for both Microsoft SQL Server and SAP HANA databases.

===== 2. Installation of the Windows Service =====
{{ :en:cobi.wms:cobi.wms-inventorycounting-service.setup.exe |COBI.wms Team Counting Service.exe}}

  - Run the setup file for the Windows service (''COBI.wms.InventoryCounting.service.exe'') on the designated Windows server.
  - During the installation, the wizard prompts for various configuration parameters:
    * Database Type: Select the database type using the dropdown menu.
    * SAP Server: Enter the address and port of your SAP server here (Format: ''IP:PORT'', e.g., ''192.168.0.1:30015'').
    * SAP Database: Enter the database name / company database here.
    * SAP User: Enter the SAP username here.
    * SAP Password: Enter the SAP password here.
    * Cron Expression: Define the time interval at which the service should process the received counts (help on cron syntax can be found at [[https://crontab.guru/|crontab.guru]]).
    * API Key: Set a secure API key. This will later authenticate the connection between the handheld scanners (app) and this service.
    * Hangfire User & Password: Set the login credentials here. These will be required later to access the monitoring dashboard (Hangfire).

{{:en:cobi.wms:inventory_setup_config.png?600|Configuration step in the setup wizard}}

Complete the setup. \\
The Windows service will then be registered and started automatically. \\
You can verify this in the Windows Services management (''services.msc'').

===== 3. Firewall & Database Update =====
**Important: Port Forwarding** \\
By default, the service runs on port 61000. \\
It is mandatory that this port is accessible for the handheld scanners (WLAN/network) in the server's Windows firewall!

After a successful installation, you must inform the COBI.wms management database where to find the service. \\
To do this, execute the following update script (adjust the IP address, port, API key, and Company Name to your environment):

<code sql>
UPDATE COBIWMS.COMPANIES
SET INCAPIURL = 'http://10.10.10.20:61000/api/v1/',
INCAPIKEY = 'YOUR_CHOSEN_API_KEY'
WHERE COMPANY = 'Your_SAP_Company_Name';
</code>

===== 4. Monitoring via Hangfire Dashboard =====
The service includes its own dashboard for monitoring background processes.

  * Open a browser on the server and go to the address ''http://localhost:61000/hangfire''.
  * Log in using the Hangfire User and Password that you set during installation (Step 2).
  * Under the "Recurring Jobs" tab, you will see the scheduled cron job. If you do not want to wait for the next automatic interval, you can manually trigger the processing at any time by clicking the "Trigger now" button.

{{:en:cobi.wms:inventory_hangfire_dashboard.png?1200|Hangfire Dashboard - Recurring Jobs}}

===== 5. Functionality & Limitations =====
When the scanners send data to the service, it initially saves the counts under "Requests". \\
During processing (cron job), the following logic applies:

  * Consolidation (different users): If different users count the same item, the service adds the counted quantities together.
  * Overwriting (same user): If the same user counts the same item multiple times (e.g., as a correction), the older entries are ignored, and only the latest count is processed.

**Performance Note:** \\
The processing speed is primarily limited by SAP Business One, not by the COBI.wms service. \\
As a rough guideline: For an inventory count with approximately 5,000 rows and 11 counters, the SAP system requires about 2 hours for processing.

**User Experience:** \\
The app user does not notice this background process. \\
As soon as the data is successfully transferred to the service, the user can continue working in the app immediately without any wait time.

===== 6. Subsequent Configuration (appsettings.json) =====
If it becomes necessary to adjust the configuration after the initial installation (e.g., if the SAP password changes or a different port is to be used for Hangfire), the setup does not need to be run again. \\
You can make the changes directly in the configuration file.

Navigate to the installation directory of the Windows service (usually located under ''C:\COBI.wms-inventorycounting-service'' or similar) and open the **''appsettings.json''** file with a text editor (as Administrator).

The configuration is divided into different blocks. Here is an overview of the most important fields and their functions:

  * Kestrel -> Endpoints -> Http -> Url: The port on which the service and the Hangfire dashboard run (Default: ''http://0.0.0.0:61000''). Change the port number at the end here if the default port is already in use.
  * SAP -> Server: Address and port of the SAP server.
  * SAP -> Database: Name of the SAP company database.
  * SAP -> User / Password: The credentials for SAP Business One.
  * SAP -> DatabaseType: The selected database type (e.g., ''dst_HANADB'' or ''dst_MSSQL2016'').
  * Jobs -> UpdateInventoryCountingJobCron: The interval (cron expression) for asynchronous processing.
  * Hangfire -> User / Password: The access data for the monitoring dashboard.
  * Api -> Key: The authentication key for the connection between the handheld scanner and the service.

> **Important: Handling Passwords** \\
> If you want to change a password (e.g., in the `"SAP"` or `"Hangfire"` block), simply enter the new password in **plain text** into the ''appsettings.json'' file. Save the file and restart the Windows service via the Services management (''services.msc''). \\
> Upon starting, the service automatically detects the plain text and immediately **hashes** the password. If you open the file again afterwards, you will only see the unreadable hash value instead of your password.

====== 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.