Installation DHL Versenden

Rahmenbedingungen für die Verwendung der Schnittstelle DHL Versenden

Das von der DHL für Geschäftskunden verfügbare Angebot DHL Versenden stellt als Schnittstelle einen über das Internet erreichbaren Web-Service bereit. Anders als bei den meisten anderen Angeboten der diversen Logistikdienstleister erfolgt die Kommunikation mit diesem Web-Service nicht über eine vom Dienstleister bereitgestellte Anwendung, sondern über die von der Software-Schmiede Vogler & Hauke GmbH bereitgestellte Dienstanwendung SWSDHL. Diese Dienstanwendung muss auf einem hierfür geeigneten Rechnersystem installiert werden, wobei folgende Rahmenbedingungen zu erfüllen sind:

1. Das den Dienst ausführende Rechnersystem bzw. die Dienstanwendung selbst müssen über einen funktionierenden Internetzugang verfügen.
2. Das den Dienst ausführende Rechnersystem benötigt eine eigene GhostScript-Installation ab Version 9.20.
3. Für den Dienst muss ein Domänen-Benutzerkonto bereitgestellt werden, das folgende Bedingungen erfüllt:
   1. Lesender Zugriff auf das Programmverzeichnis von Professional ERP.
   2. Lesender und schreibender Zugriff auf das für die Datenhaltung verwendete Datenbanksystem. Hierfür reichen zunächst dieselben Berechtigungen, die normale Professional ERP Benutzer für den Zugriff auf den zur Datenhaltung verwendeten Microsoft SQL Server das Datenverzeichnis WEEKEND.DAT bei Microsoft Visual Fox basierter Datenhaltung verwenden. Bei Datenhaltung mit Microsoft SQL Server sind die Datenbankzugriffsrechte als Teil eines Installationsschrittes gezielt zu ändern.
   3. Ein Kennwort, das nicht aufgrund von Sicherheitsrichtlinien abläuft.
4. Vor der Installation und Inbetriebnahme der Dienstanwendung muss die Datenbank der zugehörigen Professional ERP Installation bzw. des jeweiligen Mandanten durch eine Aktualisierung auf Professional ERP Version 7.11 oder höher mit der für die Dienstnutzung geeignete Datenbankstruktur aktualisiert werden.
5. Auf dem den Dienst ausführende Rechnersystem muss der für den Labeldruck vorgesehene Drucker eingerichtet werden. Das in Punkt 3 beschriebene Domänenbenutzerkonto muss im Fall eines über das Netzwerk eingebundenen Druckers die Berechtigung besitzen, den eingerichteten Drucker anzusprechen.
6. In Professional ERP muss die DHL Versenden Schnittstelle durch die Mitarbeiter der Software-Schmiede Vogler & Hauke GmbH freigeschalten sein.

Installations- und Konfigurationsmaßnahmen für Schnittstelle DHL Versenden

Die Einrichtung der Schnittstelle DHL Versenden erfolgt in zwei bzw. drei Hauptschritten:

1. Bei einer Datenbankhaltung mit Microsoft SQL Server muss die Professional ERP Datenbank erweitert und mit speziellen Berechtigungen versehen werden. Bei einer Datenhaltung mit Microsoft Visual Fox Pro kann dieser Schritt übersprungen werden.
2. Installation und Konfiguration der Dienstanwendung SWSDHL
3. Abschließende Konfiguration in Professional ERP für die Verwendung von DHL Versenden.

Datenbankanpassungen bei Datenhaltung mit Microsoft SQL Server

Die nachfolgenden Schritte müssen mit einer Windows- und einer Professional ERP-Benutzeranmeldung durchgeführt werden, wie sie auch für die Durchführung einer Indexreparatur benötigt werden. D.h. auf Ebene des SQL-Servers müssen für die verwendete Windowsbenutzeranmeldung Rechte analog zu dbowner vorhanden sein und in Professional ERP bietet sich die Verwendung des administrativen Benutzers SUPERUSER an.

1. Zunächst muss die im Installationsverzeichnis von Professional ERP liegende DateiSQL muss in MSSQLF10.SQL umbenannt werden.
2. Nach der Umbenennung der Datei muss Professional ERP gestartet werden. Beim Programmstart wird dann automatisch die Professional ERP-Datenbank erweitert. Sobald das Professional ERP Hauptmenü bzw. eine der im Autostart befindlichen Anwendungsmasken angezeigt werden, ist die Datenbankaktualisierung durchgeführt und Professional ERP kann wieder beendet werden.

3. Als nächstes sind die besonderen Berechtigungen auf dem Microsoft SQL Server einzurichten, die für die Verwendung der Dienstanwendung SWSDHL benötigt werden. Über das Microsoft SQL Server Management Studio sind die nachfolgenden SQL-Skriptbefehle auszuführen:

   grant CONTROL on CONTRACT::[//ProfERP/VHN/VHNContract] to <<BENUTZER/GRUPPE>> grant CONTROL on MESSAGE TYPE::[//ProfERP/VHN/CreatePackageMessage] to <<BENUTZER/GRUPPE>> grant CONTROL on SERVICE::[//ProfERP/VHN/VHNService] to <<BENUTZER/GRUPPE>> grant CONTROL on VHNQueue to <<BENUTZER/GRUPPE>>

   Die Platzhalter <<BENUTZER/GRUPPE>> sind hierbei geeignet durch die für den normalen Datenbankzugriff mit Professional ERP eingerichteten Benutzer bzw. Gruppen zu ersetzen. Sofern der Zugriff auf die Professional ERP Datenbank mit mehreren Benutzern oder Gruppen erfolgt, müssen die o.g. Skriptbefehle für jede(n) dieser Benutzer / dieser Gruppen separat ausgeführt werden.

Installation und Konfiguration der Dienstanwendung SWSDHL

Die nachfolgenden Schritte müssen auf einem Rechnersystem ausgeführt werden, welches die im ersten Abschnitt beschriebenen Rahmenbedingungen 1,2 und 5 erfüllt. Für die Installation wird eine Windowsbenutzeranmeldung benötigt, die zur Installation und Konfiguration von Dienstanwendungen berechtigt. Für die Konfiguration der Dienstanwendung wird dann die im ersten Abschnitt in Punkt 3 beschriebene Benutzerkennung benötigt.

1. Zunächst muss auf dem Zielsystem, das die Dienstanwendung bereitstellen soll, die Installationsroutine exe ausgeführt werden. Diese befindet sich im Verzeichnis SUPPORT des Professional ERP Installationsmediums. Beim Start der Installationsanwendung muss die eventuell erscheinende Rückfrage des Betriebssystems zur Ausführung der systemverändernden Anwendung bestätigt werden. Im Anschluss öffnet sich das erste Dialogfenster des Installationsassistenten:
   
   Unable to render {include} The included page could not be found.
   
   

   Dieser Dialog muss mit Weiter > bestätigt und Folgedialog durch Annehmen das Lizenzabkommen akzeptiert werden.
   
   

2. Im nächsten Dialogfenster ist das Zielverzeichnis für die Installation der Dienstanwendung anzugeben:
   

   Unable to render {include} The included page could not be found.

   Als Installationspfad wird zunächst ein Verzeichnis Pfad im Windows-Standardinstallationspfad für Programme bzw. dessen übersetzte Namensrepräsentation in der verwendeten Sprachversion ihres Windowssystems vorgeschlagen:

   C:\Program Files (x86)\Software-Schmiede\SWSDHL

   Dieses Verzeichnis und darin erzeugte Unterverzeichnisse unterliegen jedoch standardmäßig speziellen Beschränkungen, welche es für die Installation von Dienstanwendungen wie SWSDHL ungeeignet machen: Nach einer Installation haben in dieser Verzeichnisstruktur standardmäßig nur Benutzerkonten mit administrativen Rechten volle Schreib- und Leserechte. Die Dienstanwendung benötigt jedoch unbedingt sowohl Schreib- als auch Leserechte auf ihr eigenes Installationsverzeichnis. Da die Verwendung von Benutzerkonten mit administrativen Rechten ein Sicherheitsrisiko darstellen würden, empfiehlt es sich, die Dienstanwendung stattdessen in ein eigens hierfür erzeugtes Verzeichnis außerhalb des Standardinstallationspfades zu installieren und dieses dann mit den benötigten Schreib- und Leserrechten für das in der Dienstanwendung verwendete Domänenbenutzerkonto auszustatten. Für die Beispielabbildung wurde der Pfad

   C:\Software-Schmiede\SWSDHL

   gewählt. Als Installationsverzeichnis kann auch ein Verzeichnis auf einem anderen lokal verfügbaren Laufwerk ausgewählt werden.

   Über die Schaltfläche Durchsuchen kann der Windowsauswahldialog für Verzeichnisse aufgerufen werden, um ein geeignetes Installationsverzeichnis auszuwählen. Nach erfolgter Auswahl des Zielverzeichnisses ist auch dieses Dialogfenster mit Weiter > zu bestätigen.
   
   

3.  Im darauf folgenden Dialogfenster sind Konfigurationsparameter für die Dienstanwendung anzugeben.
   
   Unable to render {include} The included page could not be found.
   
   

   
   

   Parameter	Inhalt / Bedeutung
   SQL-Server Connection String	Erfolgt die Datenhaltung von Professional ERP mit einem Microsoft SQL-Server sind, in diesem Eingabefeld die oben abgebildeten Angaben zu machen, wobei die Platzhalter wie folgt zu ersetzen sind: [SERVERNAME]: Rechnername oder IP-Adresse des Rechnersystems auf dem der für die Datenhaltung verwendete SQL Server läuft. [SQLSERVERNAME]: Name der für die Datenhaltung verwendeten SQL-Serverinstanz. Für Standardinstallationen ist der Name der SQL-Serverinstanz üblicherweise identisch zum Rechnernamen des Rechnersystems, das den SQL Server bereitstellt. [DATENBANKNAME]: Name der für die Datenhaltung von Professional ERP verwendeten Datenbank. In Standardkonfigurationen ist dieser Name in der Regel eine Kombination aus der Zeichenfolge PERP und ihrer Professional ERP-Seriennummer, z.B. PERP999999 Erfolgt die Datenhaltung noch mit Microsoft Visual FoxPro-Tabellen, kann dieses Feld leer bleiben. Dann ist jedoch das nachfolgend beschriebene Feld zwingend zu belegen.
   Professional ERP Datenverzeichnis	Für Installationen mit einer Datenhaltung in Microsoft Visual FoxPro-Tabellen muss in diesem Feld der Pfad zum Datenverzeichnis WEEKEND.DAT ihrer Professional ERP Installation angegeben werden. Bei über das Firmennetzwerk freigegebenen Datenverzeichnissen, sollte hier statt eines Absolut-Pfades mit Laufwerksbuchstabe der UNC-Pfad der Freigabe verwendet werden. Für Professional ERP Installationen mit Datenhaltung auf einem Microsoft SQL Server kann dieses Feld leer bleiben; eine Belegung schadet jedoch nicht.
   Pfad zur GhostScript-Anwendung	In diesem Feld ist der Dateipfad zur ausführbaren Konsolenanwendung gswin32c.exe (32-Bit Systeme) bzw. gswin64c.exe (64-Bit Systeme) der lokalen GhostScript-Installation anzugeben. Die Standardpfade der Version 9.20 lauten: C:\Program Files\gs\gs9.20\bin\gswin64c.exe (64-Bit Systeme) bzw. C:\Program Files (x86)\gs\gs9.20\bin\gswin32c.exe
   PDF Speicherpfad	Der von der DHL bereitgestellte Web-Service stellt für den Label-Druck PDF-Dateien bereit, die die Dienstanwendung in einem lokal verfügbaren Verzeichnis zwischengespeichert. Im Eingabefeld PFD Speicherpfad ist ein Verzeichnispfad für diese Zwischenspeicherung anzugeben. Der Dienst benötigt Lese- und Schreibrechte auf dieses Verzeichnis. Ein häufig verwendetes Verzeichnis ist das globale Temporärverzeichnis unter C:\TEMP der Windowsinstallation. Achtung! Die temporären PDF-Dateien in diesem Verzeichnis werden von der Dienstanwendung nicht automatisch bereinigt, damit ausgedruckte Label notfalls auch manuell nochmal ausgedruckt werden können. Auch wenn die Dateigrößen der einzelnen Dateien kein unmittelbares Problem für den verfügbaren Speicherplatz des verwendeten Laufwerks darstellen, sollte eine regelmäßige Bereinigung – z.B. als Teil der regelmäßigen Serverwartungsmaßnahmen – sichergestellt werden.
   Pfad zur Mapping-Datei (ERP2DHL.json)	Im Installationsverzeichnis einer Professional ERP Installation befinden sich nach dem Update auf Version 7.11 zwei Mapping-Dateien im .json-Format: a)    ERP2DHL.json b)    ERP2DHL.example.json Beide Dateien enthalten zunächst identische Mapping-Informationen mit denen die Dienstanwendung Daten von Professional ERP an den DHL-Web-Service weiterleitet bzw. die von dort erhaltenen Daten wieder ins System zurückschreibt. In der Datei ERP2DHL.json können individuelle Anpassungen für die Steuerung der Dienstanwendung vorgenommen werden. Die Datei ERP2DHL.example.json dient als Vorlagendatei für eine Mehrfacheinrichtung der Dienstanwendung in Professional ERP Mandantenversionen. Im Eingabefeld des Installationsdialogs ist der Dateipfad zur Datei ERP2DHL.json anzugeben. Befindet sich das Professional ERP Installationsverzeichnis auf einem anderen Rechnersystem, muss das Verzeichnis für lesende Netzwerkzugriffe durch das für den Dienst verwendete Domänenbenutzerkonto freigegeben sein und der Netzwerkpfad ist als UNC-Pfad anzugeben. Die Datei ERP2DHL.json wird während einer Servicepack-Installation nicht verändert. D.h. die in dieser Datei vorgegebenen Einstellungen gelten bis zu einem expliziten Austausch mit einer gleichnamigen Datei weiter. Die Datei ERP2DHL.example.json wird dagegen während einer Servicepack-Installation immer dann überschrieben, wenn sich Änderungen am Default-Mapping oder anderen Default-Einstellungen ergeben haben.

   Nach Eingabe der Konfigurationsparameter den Dialog mit Weiter > bestätigen.
   
   

4.  Im nun folgenden Dialogfenster sind weitere Konfigurationsparameter für die Dienstanwendung anzugeben.
   

   Unable to render {include} The included page could not be found.

   Parameter	Inhalt / Bedeutung
   Instanzname des Dienstes	Im Rahmen der Installation des Dienstes wird auch ein Eintrag in der Dienste-Übersicht der Windowsinstallation erzeugt. Der Dienst erhält den Namen SWS – DHL (Instance: [DIENSTNAME]), wobei der Platzhalter [DIENSTNAME] mit der in diesem Feld des Installationsdialogs eingegebenen Zeichenfolge ersetzt wird. Es empfiehlt sich als Instanzname die eigene Firmenbezeichnung zu verwenden. Sofern mehrere Instanzen des Dienstes für unterschiedliche Professional ERP Mandanten eingerichtet werden, kann hier jeweils die Mandantenbezeichnung angegeben werden, um die einzelnen Dienste in der Windows-Dienstübersicht leichter unterscheiden zu können.
   DHL-Benutzername	Hier ist der von der DHL zugewiesene Benutzername für den DHL Versenden Web-Service anzugeben.
   DHL-Passwort	In diesem Feld ist das von DHL zugewiesene Passwort für den DHL Versenden Web-Service anzugeben.
   DHL-Kundennummer	Hier ist der von der DHL zugewiesene Benutzername für den DHL Versenden Web-Service anzugeben.

   Nach Abschluss dieser Eingaben wird die eigentliche Installation der Dienstanwendung über die Schaltfläche Installieren ausgeführt.
   
   

5. Während des eigentlichen Installationsprozesses öffnet sich zunächst ein für Eingaben gesperrtes Konsolenanwendungsfenster, in welchem einzelne Installationsschritte angezeigt werden. Nach kurzer Zeit öffnet sich dann ein Eingabedialog zur Eingabe der Windowsbenutzerinformationen in deren Kontext der Dienst ausgeführt werden soll.
   

   Unable to render {include} The included page could not be found.

   Es ist darauf zu achten, dass dem Benutzernamen des verwendeten Domänenbenutzerkontos auch die Domänenkennung in der Form DOMÄNE\ vorangestellt wird. Andernfalls kann es zu zwei Fehlerbildern kommen:

   1. Existiert auf dem Rechnersystem kein lokales Benutzerkonto mit diesem Benutzernamen, kommt bereits beim Versuch den Dialog mit OK zu verlassen die Meldung, dass das Passwort nicht stimmt und der Dialog kann nicht verlassen werden.
   2. Existiert auf dem Rechnersystem ein lokales Benutzerkonto mit diesem Benutzernamen und übereinstimmendem Passwort, dann kann der Dialog zwar geschlossen werden, aber bei der späteren Inbetriebnahme des Dienstes wird es sehr wahrscheinlich zu Zugriffsproblemen kommen, weil lokalen Benutzerkontos ohne zusätzliche administrative Eingriffen in aller Regel die nötigen Vertrauensstellungen innerhalb der Domäne fehlen.

Nach Abschluss des Installationsprozesses taucht der neu eingerichtete Dienst in der Windows-Dienste-Übersicht auf.

Diese kann wie folgt aufgerufen werden:

a) Tastenkombination WINDOWS-Taste + R, um einen Befehlszeilendialog zu öffnen

b) Aufruf der Dienste-Übersicht mit dem Befehl msc und Bestätigung OK oder der ENTER-Taste

Der Dienst ist nach der Installation für einen automatischen Start im Rahmen von Rechnersystemstarts konfiguriert und verwendet das zuvor zugewiesene Domänenbenutzerkonto.

Konfiguration in Professional ERP

In diesem Schritt wird eine Benutzeranmeldung an einem Professional ERP Arbeitsplatz mit einer ERP-Benutzeranmeldung benötigt, die Zugriff auf die Einstellungen mittels Konfigurationsvariablen besitzt. Hierfür eignet sich der administrative Benutzer SUPERUSER.

1. Damit Professional ERP in Verbindung mit Erweiterungsmodul Versandhandel Versandaufträge für DHL über die DHL Versenden-Schnittstelle erstellen und zugehörige Labels drucken kann, muss die Konfigurationsvariable DGVLBLPRINTER mit dem Namen des Label-Druckers belegt werden, der zuvor auf dem für die Dienstausführung vorgesehenen Rechnersystem eingerichtet wurde.
   

   Unable to render {include} The included page could not be found.

   Der in der Konfigurationsvariablen angegebene Drucker muss nur auf dem die Dienstanwendung ausführenden Rechnersystem zwingend verfügbar sein. Andere Professional ERP Arbeitsplätze benötigen diesen Drucker nicht, da die Label-Druckaufträge immer über die Dienstanwendung abgewickelt werden.

Mit diesem Konfigurationsschritt sind die Installations- und Konfigurationsmaßnahmen abgeschlossen.

Inbetriebnahme und Überwachung des Dienstes

Nach Abschluss der Installations- und Konfigurationsmaßnahmen kann die Dienstanwendung und danach der Labeldruck mit DHL Versenden in Betrieb genommen werden.

1. Zunächst wird der zuvor installierte und beendete Dienst (vgl. "Installation und Konfiguration der Dienstanwendung SWSDHL" Schritt [5]) wieder gestartet.
   
   Unable to render {include} The included page could not be found.
   
   
   
2.  An allen Professional ERP Arbeitsplätzen, die einen Labeldruck mit der DHL Versenden Schnittstelle durchführen sollen, müssen die Anwendungen – insbesondere Auftragsbearbeitung und Bestellwesen – ebenfalls neu gestartet werden.
   
   
3. Nach dem Neustart kann der Status der Dienstanwendung nun auch ohne eine Anmeldung am Dienst-Rechner innerhalb von Professional ERP überprüft werden. Professional ERP Benutzer mit Zugriff auf den Mehrwertdienste-Monitor, können dort den aktuellen Betriebszustand einsehen:
   
   Unable to render {include} The included page could not be found.
   
   Ganz allgemein wird der Aktivitätszustand auch über im Mini-Monitoring-Bereich von Anwendungsmasken signalisiert. Die überwachten Dienste werden hierbei durch Klick auf das Monitoring-Symbol eingeblendet.
   
   Unable to render {include} The included page could not be found.
   
   
   
4. Ab jetzt kann in den vom Erweiterungsmodul Versandhandel betroffenen Anwendungen – insbesondere der Auftragsbearbeitung und dem Bestellwesen – die Versandschnittstelle DHL Versenden genutzt werden.

Deinstallation der Dienstanwendung

Im Installationsverzeichnis der Dienstanwendung befindet sich nach der Installation neben den eigentlichen Anwendungsdateien auch eine Deinstallationsroutine mit der die Dienstanwendung bei Bedarf wieder entfernt werden kann:

Separate Dienste für mehrere Professional ERP Installationen / Mandanten

Die Dienstanwendung lässt sich bei Bedarf auch mehrfach auf demselben Rechnersystem installieren, um mehrere Professional ERP Installationen bzw. unterschiedliche Mandanten derselben Professional ERP Installation mit einem jeweils eigenen Dienst versehen zu können.

Hierbei sind dann folgende Dinge zu beachten:

1. Jeder Dienst muss ein eigenes Installationsverzeichnis erhalten.
2. Bei der Installation ist für jeden Dienst ein jeweils eindeutiger Instanzname anzugeben, da Windows für jeden Dienst zwingend einen eindeutigen Namen verlangt. Zudem können die einzelnen Dienste in der Windows Dienst-Übersicht nur anhand des Instanznamens voneinander unterschieden werden.
3. Sollte für einen oder mehrere der zu installierenden Dienste ein spezielles Mapping benötigt werden, muss den betroffenen Dienstversionen die jeweilige ERP2DHL.json-Datei an geeignet getrennten Speicherorten zur Verfügung gestellt werden. Bei mehreren Professional ERP Installationen wird dies durch die unterschiedlichen Installationsverzeichnisse in aller Regel schon gewährleistet. Im Fall von Professional ERP Mandantenversionen, die ein gemeinsames Installationsverzeichnis mit getrennten Datenverzeichnissen verwenden, bietet es sich an, die jeweils zu verwendende .json-Datei im Datenverzeichnis des Mandanten bereitzustellen.

Protokollierung von Fehlerereignissen durch die Dienstanwendung SWSDHL

Bei der Abarbeitung von Versandinformationen kann es funktional auf drei Ebenen zu Fehlern kommen:

1. Fehler auf inhaltlicher Ebene bei den Paketinformationen, z.B. wegen fehlender Adressinformationen. Vom Web-Service gemeldete Fehler dieser Art werden genau wie bei erfolgreicher Datenübertragung / Abarbeitung durch den Web-Service in Paketinformationen des jeweiligen Pakets in der Packstückerfassung protokolliert.
2. Bei der Kommunikation der Dienstanwendung mit dem Web-Service kann es zu Fehlern kommen, bei denen die Dienstanwendung keine durch sie sinnvoll bearbeitbaren Daten erhält. Derartige Fehler werden innerhalb des Professional ERP Mehrwertdienste-Monitors in der rechten unteren Tabellenanzeige protokolliert.
3. Sofern sich Probleme im Programmablauf der Dienstanwendung selbst ergeben, die häufig zum Beenden des Dienstes führen, trägt der Dienst diese ins Windows-Ereignisprotokoll ein. Auch Abstürze der Dienstanwendung selbst werden von Windows normalerweise im Windows-Ereignisprotokoll festgehalten.