MDE Installation

Die MDE Installation beschreibt die technische Installation der Serverkomponente und die dazugehörige Konfiguration in Business Central. Die Einrichtung der Clients ist in MDE Clients beschrieben.

Installation

Zur Kommunikation mit den Geräten ist es erforderlich einen zusätzlichen Windows Dienst zu installieren, der MDE Clients und Business Central "verbindet".

Folgendes Setup muss auf dem Server ausgeführt und eingerichtet werden:

Server Service Setup.msi (Voraussetzung: .NET Framework 4.7.2)

Hierdurch wird der Dienst "TSO.TCPServer" installiert. Im Installationsordner gibt es die Konfigurationsdatei "ConnectorCfg.xml", in der die Konfiguration des Dienstes beeinflusst werden kann.

Beispiel:

    <ServerServiceConfigItems xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Debug>EventLog</Debug>
    <Error>EventLog</Error>
    <AdcsWebServiceType>OData</AdcsWebServiceType>
    <WebServiceUrl>https://api.businesscentral.dynamics.com/v2.0/{0}/MySandbox/ODataV4/TSOADCS_ProcessScannerMessage?company=CRONUS%20DE</WebServiceUrl>
    <WebServiceAuthenticationType>OAuth2</WebServiceAuthenticationType>
    <OAuthClientId>5555</OAuthClientId>
    <OAuthClientSecret>1234</OAuthClientSecret>
    <TenantId>XYZ</TenantId>
    <SendTimeOut>2000</SendTimeOut>
    <ReceiveTimeOut>2000</ReceiveTimeOut>
    <ServerType>TSO.Server.ADCS.ADCSServer</ServerType>
    <BaseAddress>localhost</BaseAddress>
    <HttpPort>8000</HttpPort>
    </ServerServiceConfigItems>

Hinweis: Der Platzhalter {0} in der WebServiceUrl wird automatisch durch die TenantId ersetzt.

Business Central

Die Kommunikation findet über ODATA Web Services statt. Die App veröffentlicht dafür automatisch die Codeunit "5371190 ADCSConnectorOdataWSTDCS" mit dem Servicenamen "TSOADCS". Dieser wird sowohl für die Scanner, als auch für die Pick-by-Voice Kommunikation benutzt.

Authentifizierung

In der ConnectorCfg gibt es die Möglichkeit, die Authentifizierung gegen Business Central zu konfigurieren. Um auf die WebServices von Business Central Online zuzugreifen, ist es nötig, im Azure Portal des Kunden über [Azure-Dienste] - [Microsoft Entra ID] eine App-Registrierung vorzunehmen, die den Zugriff auf die Business Central API erlaubt. Zur genauen Einrichtungsanleitung, siehe Microsoft Learn

Die benötigte API-Berechtigung ist in diesem Fall: API.ReadWrite.All

Die daraus resultierenden Werte für OAuthClientId, OAuthClientSecret und TenantId müssen passend in der ConnectorCfg eingetragen werden.

Client-ID

Die Client-ID ist später auch in Business Central über die [Microsoft Entra-Anwendungen] einsehbar. Das entsprechende Feld auf der Anwendungskarte lautet [Client-ID].

Innerhalb von Business Central müssen der Entra App [Microsoft Entra-Anwendungen] die entsprechenden Benutzerrechte zugeordnet werden. Siehe Microsoft Learn

Die MDE-App stellt den Berechtigungssatz "TDCS Service" bereit. Dieser inkludiert auschließlich die für das Modul relevanten Berechtigungen. D.h. es ist zusätzlich noch ein Berechtigungssatz nötig, damit der Dienst sich überhaupt an Business Central anmelden kann (z.B. "D365 Automation").

Timeouts

Die Einstellungen für die Server Timeouts sind zu überprüfen. Es wird empfohlen, den Timeout nicht zu klein zu wählen, damit auch länger laufende Prozesse abgearbeitet werden können.

Timeouts

Empfehlung: ReceiveTimeout = 10000 ms und Timeout am MDE Client = 12000 ms.

TSO Scannerclient (Android und Windows CE)

Zu den verschiedenen TSO MDE Clients gibt es unter MDE Clients weitere Informationen.

Pick-by-Voice

Um die Pick-by-Voice Geräte von Perdictum/Prologistik anzubinden, muss in der ConnectorCfg Folgendes konfiguriert werden: - ServerType: TSO.Server.Sockets.Pbv - WebServiceUrl: Der Funktionname in der Url muss wie folgt aussehen - ODataV4/TSOADCS_ProcessPbvMessage

Sonstiges

Netzwerk

Folgende Infos müssen vom Kunden eingeholt bzw. weitergegeben werden, damit die Inbetriebnahme der MDEs beim Kunden vorgenommen werden kann. Es müssen die Ports in der Firewall freigeschaltet werden, auf dem der "TSO.TCPServer" (TSO ScannerClient) bzw. "PiccoLink Connector" (DTE Piccolink Client) läuft.
* Port für die Kommunikation zwischen MDE Gerät und dem TSO.TCPServer. Default: 8000

Werden PiccoLink Clients eingesetzt ist, wird ein Port zur Kommunikation zwischen dem PiccoLink Client und dem PiccoLink Connector genutzt. Default: 2000

Das WLAN muss vor Ort auf den MDEs konfiguriert werden.
Außerdem muss die Netzwerkeinstellung per DHCP oder manuell eingerichtet werden.
Die CommID / GeräteID muss pro Gerät eindeutig vergeben und im MDE Modul eingerichtet werden.

Installation mehrerer TSO.TCPServer

Damit sich MDE-Clients parallel gegen verschiedene Systeme verbinden können, kann es notwendig sein, dass gleichzeitig mehrere TSO.TCPServer auf einer Maschine laufen. Dies ist zum Beispiel bei gleichzeitigem Betrieb von Echt- und Testsystem oder bei Nutzung des MDE-Moduls in verschiedenen Mandaten hilfreich. Jeder Dienst kann sich dann mit einem eigenen Business Central WebService verbinden.

Die Installation des zweiten Dienstes funktioniert nicht über die Installationsroutine sondern über den PowerShell Befehl

New-Service.

Vor der Ausführung des folgenden Scrips wurde der TSO Server Service Ordner kopiert um danach den Dienst TSO.SecondTcpServer zu erstellt. In der Konfiguration der Dienste ist darauf zu achten, dass die vergebenen Ports frei sind.

    $params = @{
      Name = "TSO.SecondTcpServer"
      BinaryPathName = "C:\Program Files\TSO-DATA GmbH\TSO Server Service - Kopie\TSO.Server.Service.exe -k netsvcs"
      DependsOn = ""
      DisplayName = "TSO.SecondTcpServer"
      StartupType = "Manual"
      Description = "TSO.SecondTcpServer"
    }
    New-Service @params

Logging

Die Kommunikation der Server Komponenten kann umfangreich mitgeloggt werden, um möglichen Problemen auf die Spur zu kommen. Dazu wird bei Installation der Programme ein eigenes Windows Eventlog eingerichtet:

In der Konfigurationsdatei gibt es folgende Möglichkeiten das Logging zu beeinflussen:

<Debug>EventLog</Debug>
<Error>EventLog</Error>

Hier kann konfiguriert werden in welcher Form mitgeloggt werden soll. Optionen:
None, EventLog, File

Über den Parameter EventLogSource kann ein abweichender Quellenname angegeben werden, der im Ereignisprotokoll im Feld Quelle auftaucht. Dies ist z.B. dann hilfreich, wenn auf einem Server mehrere Instanzen des TSO.TCPServer laufen (Test/Echt, mehrere Mandanten).

Logging Message bei Verwendung des OData Web Services

Dauert ein Request an Business Central länger als 1500 ms, so wird eine Warning protokolliert:

ProcessMessage took longer than expected: n ms - Tritt innerhalb der Prozessverarbeitung in Business Central ein Fehler auf, der nicht durch die jeweilige Prozessverarbeitung abgefangen wurde, wird ein Error protokolliert, z. B.:

"error": "code":"Application_DialogException","message":"No. must have a value in Item: No.=. It cannot be zero or empty. CorrelationId: 0934f36d-5f35-4a3e-a8f6-309a86850d1e."
Wird der konfigurierte Server Timeout überschritten, so wird ein allgemeiner Error protokolliert:

Mindestens ein Fehler ist augetreten

Transaktionsverhalten bei Server Timeout (OData Web Service)

Bei Server Timeout wird die Business Central Transaktion direkt abgebrochen.

Besonderheiten OnPrem

In Business Central OnPrem Umgebungen gibt es einige weitere nennenswerte Konfigurationsmöglichkeiten.

Web Services und Authentifizierung

OnPrem besteht neben OAuth2 auch die Möglichkeit, die Windowsanmeldung oder UserPassword als Authentifizierung zu benutzen. Über folgende ConnectorCfg Einstellungen kann die Authentifizierung eingestellt werden:

WebServiceAuthenticationType: Mögliche Werte sind "DefaultCredentials" (Windowsauthentifizierung) oder "UserNameAccessKey" (UserPassword-Authentifizierung). Bei DefaultCredentials wird der Dienstbenutzer zur Authentifizierung mit Business Central benutzt und sollte entsprechend sinnvoll konfiguriert werden.

Windowsauthentifizierung

Bei der Installation muss ein Benutzer angegeben werden, der der lokaler Admin auf dem System ist. Wird die Windows Authentifizierung genutzt, muss dieser User auch als Benutzer mit entsprechenden Rechten in Business Central eingerichtet sein.

(NAV)UserPassword

Bei UserNameAccessKey müssen noch folgende Parameter gesetzt werden

User: Name des NAV/BC Users
WebServiceAccessKey: Hier wird nicht das Passwort des Benutzers, sondern der Webdienst-Zugriffsschlüssel des Benutzers angegeben. Dieser kann auf der Benutzerkarte in NAV/BC erstellt werden.

Die OnPrem-WebService URL für den ODATA Server sollte wie folgt aussehen: http://BCService:7048/ODataV4/TSOADCS_ProcessScannerMessage?company=ABC

Per AdcsWebServiceType kann die Art des Webdienstes konfiguriert werden - AdcsWebServiceType: Mögliche Werte sind ODATA und SOAP

ODATA Web Service

Der ODATA Web Service steht erst ab der MDE Modulversion 21.x zur Verfügung

Für die Nutzung der SOAP Web Services muss jeweils eine Codeunit als Web Service mit dem Namen ADCSConnector veröffentlicht werden:

Scanner: 5371159 ADCS Connector Scanner WS
PbV: 5371160 ADCS Connector PbV WS

Hierfür gibt es passende Actions in der MDE Einrichtung. . Ein Parallelbetrieb von Scannern und PbV ist aktuell mit SOAP Web Services nicht möglich.

In der ConnectorCfg muss der Parameter WebServiceUrl auf die SOAP-URL des veröffentlichten ADCSConnector Webservice gesetzt werden.

Am Service Tier für die Web Services sollte die gewünschte Sprache gesetzt werden. Dabei sind folgende Schalter relevant:

Services Language: de-DE
Services Option Text Source = OptionCaption

Dynamics NAV 2009 Classic

Für ältere Dynamics NAV Versionen (bis 2009 Classic), in denen ohne Web Services oder noch mit Piccolink Software/Geräten gearbeitet wird, ist zu beachten, dass die Kommunikation mit Dynamics NAV anders funktioniert und entsprechend andere Komponenten installiert werden müssen:

Piccolink Connector Setup.msi
Server Connector Setup.msi
PLServerInstaller_x_x_x.zip

Alle Setups setzen aktuell .NET Framework 4.7.2 voraus.

Die Kommunikation läuft über Sockets. Dazu ist gibt es in der ConnectorCfg einen weiteren Port für den SocketServer (siehe unten Beispiel PiccoLink). Standardmäßig wird hier Port 4444 benutzt.

HTTPS mit selbstausgestelltem Zertifikat

Ist der Zugriff auf die NAV / Business Central WebServices SSL-verschlüsselt (https://) und das zugrundeliegende Zertifikat ist ein unsicheres selbstausgestelltes Zertifikat (z.B. weil es sich um ein OnPrem-Testsystem handelt), so muss in der ConnectorCfg angegeben werden, dass der TSO.TCPServer das unsichere Zertifikat akzeptieren soll:

AllowSelfSignedCertificates = true (default ist false)

Piccolink

Zur Kommunikation mit den Piccolink Geräten ist es notwending folgendes durchzuführen:

Entpacken der PLServerInstaller_x_x_x.zip und ausführen der darin enthaltenen PLServerInstaller.exe.
Ausführen des Piccolink Connector Setups

Der Piccolink Connector muss immer laufen, d.h. das Fenster des Programms muss immer geöffnet sein wenn Geräte mit NAV arbeiten sollen.
Vor dem Start des Connectors muss der NAS bzw. der Web Service gestartet sein, da sich der Connector die Konfigurationsdaten aus NAV zieht.
Ansonsten werden Defaultwerte aus der piccolink_cfg_xml genommen, die beim ersten Start des Programms erzeugt wird.

In der piccoConnector_cfg.xml muss dann die URL des Web Services eingetragen werden, sowie der Communication Type auf Webservice gesetzt werden.

Beispiel:

    <?xml version="1.0"?>
    <PiccolinkConnectorConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">  
        <Debug>`EventLog`</Debug>  
        <Error>`EventLog`</Error>  
        <SendTimeOut>`2000`</SendTimeOut>  
        <ReciveTimeOut>`2000`</ReciveTimeOut>  
        <SocketServerList>  
            <SocketServer>  
            <IpAdr>`127.0.0.1`</IpAdr>  
            <Port>`4444`</Port>  
        </SocketServer>  
        </SocketServerList>  
        <WebServiceUrl>[`http://localhost:7047/DynamicsNAV70/WS/KatarGo%20Demo/Codeunit/ADCSConnector`](http://localhost:7047/DynamicsNAV70/WS/KatarGo%20Demo/Codeunit/ADCSConnector)</WebServiceUrl>  
        <CommunicationType>`Webservice`</CommunicationType>  
    </PiccolinkConnectorConfig>