Dokumentation: myOpenFactory-EDI-Connector

Bitte beachten Sie, dass durch das Herunterladen dieser Seite als PDF ein statisches Dokument entsteht. Sobald sich Änderungen an den hier dargestellten Inhalten ergeben, können diese nicht nachträglich im PDF dargestellt werden. Es empfiehlt sich daher, immer die aktuelle Online-Version zu verwenden.

• 1 Einleitung
• 2 Vorbereitungen
• 3 Installation
• 4 Konfiguration
• 5 Steuerung des EDI-Connectors
• 6 Fehleranalyse

1 Einleitung

Der myOpenFactory-EDI-Connector, im weiteren Verlauf kurz EDI-Connector bezeichnet, übernimmt als Verbindungsclient den Dateiaustausch (Belege und ggf. Anhänge wie bspw. techn. Zeichnungen etc.) zwischen Ihrem ERP-System und der myOpenFactory-EDI-Plattform mittels einer REST-Schnittstelle. Der EDI-Connector wird als Dienst installiert, der auf Ihrem Server läuft und ein Monitoring Ihrerseits zwingend erforderlich macht. Dadurch wird der EDI-Connector auch strengen Compliance-Regeln gerecht.

Der EDI-Connector arbeitet verzeichnisbasiert, d.h. es werden Belege (bspw. eine Bestellung) aus einem definierten Ordner als Datei entgegengenommen und diese werden mittels einer REST-Verbindung (Methode POST) an die myOpenFactory-EDI-Plattform übertragen.

Falls Belege (bspw. Auftragsbestätigungen) auf der myOpenFactory EDI-Plattform bereitliegen holt der EDI-Connector diese mittels einer REST-Verbindung ab und legt diese als Datei in einem definierten Ordner auf Ihrem System ab.

Die Aktionen des Versandes und der Abholung werden in 60 Sekunden Intervallen durchgeführt.

Sollte es zu einem Problem mit dem Dateiversand kommen, werden die ausgehenden Belege in einen „error“-Verzeichnis verschoben, sodass keine Belege verloren gehen können.

Der EDI-Connector erzeugt eine Log-Datei, die jede Aktion protokolliert. Diese Log-Einträge werden in das Event-Log (Ereignisanzeige) vom Windows OS eingetragen. Dieses kann von Ihnen mit einem entsprechendem Monitoring Tool überwacht werden.

2 Vorbereitungen

Einrichten der Verzeichnisse

Der EDI-Connector arbeitet verzeichnisbasiert, d.h. er nimmt Belege (bspw. eine Bestellung) aus einem definierten Verzeichnis als Datei entgegen und überträgt dies an die myOpenFactory-EDI-Plattform und umgekehrt. Die notwendigen Verzeichnisse können lokal auf dem Kommunikationsserver oder auch auf einem Netzwerklaufwerk angelegt werden.

Folgende Verzeichnisse sollten eingerichtet werden:

Ein „prod“-Verzeichnis mit folgenden Unterverzeichnissen:

• Ein „prod-out“-Verzeichnis für die ausgehenden produktiven Belege.
• Ein „prod-in“-Verzeichnis, in denen die eingehenden produktiven Belege abgelegt werden, die der EDI-Connector von der Plattform abholt.
• Ein „error“-Verzeichnis für die Belege die nicht erfolgreich an die Plattform gesendet werden konnten. Nachdem die Verbindung wieder hergestellt wurde, kann der Beleg in das „prod-out“-Verzeichnis händisch verschoben werden, damit dieser dann automatisch vom EDI-Connector an die Plattform gesendet wird.

Einen „test“-Verzeichnis mit folgenden Unterverzeichnissen:

• Ein „test-out“-Verzeichnis für die ausgehenden Test-Belege.
• Ein „test-in“-Verzeichnis, in denen die eingehenden Test-Belege abgelegt werden, die der EDI-Connector von der Plattform abholt.

Nach der Einrichtung empfehlen wir, eine Testnachricht (z. B. eine beliebige Textnachricht mit einem Test-Text) in dem „prod-out“- und „test-out“-Verzeichnis zu legen, damit Tests der Verbindung durchgeführt werden können.

Freigabe bei Verwendung von Netzwerklaufwerken

Stellen Sie sicher, dass die Freigaben zum Zugriff auf Netzwerklaufwerke eingerichtet sind, falls die obengenannten Verzeichnisse auf einem anderen Server liegen. Der EDI-Connector benötigt Schreib-, Lese- und Löschrechte auf den Verzeichnissen.

Freigabe Internet

Stellen Sie sicher, dass der EDI-Connector mit den nötigen Freigaben ausgestattet ist, um das Internet zu erreichen. Geben Sie „myopenfactory.net“ (nur falls Anhänge versendet werden) und „rest.ediplatform.services“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist). Bedenken Sie, dass auch evtl. eingesetzte Virenscanner die Konnektivität beeinflussen können.

Installationsdatei herunterladen

Laden Sie die passende Installationsdatei von Github herunter. Seit Version 2.0 wird auch eine Version mit Windows Installer angeboten. (edi-connector_installer.exe) https://github.com/myopenfactory/edi-connector/releases Unser EDI-Connector kann von Ihnen validiert werden. Unsere Updates sind durch eine Signatur geschützt. Siehe: https://github.com/myopenfactory/edi-connector/

Schnittstellen-Benutzerdaten

Der EDI-Connector benötigt zum Verbindungsaufbau einen Benutzernamen mit Passwort, sowie Prozess-IDs. Diese Daten erhalten Sie von Ihrem myOpenFactory-Ansprechpartner.

3 Installation

1. Bitte wählen Sie Ihre Installationssprache aus und bestätigen mit “Weiter”.

A. Lassen Sie das Feld leer und klicken Sie einfach auf „Weiter“. Der EDI-Connector erstellt dann einen lokalen Benutzer.

B. Korrekterweise sollte aber für jeden Dienst ein eigener User mit passenden Rechten angelegt werden. Wenn dies geschehen ist, können die entsprechenden Angaben hier eingesetzt werden. Dies ist besonders wichtig, weil dann der EDI-Connector auch Ordner auf entfernten Servern erreichen kann.

A. Sollten Sie eine Json-Konfigurationsdatei besitzen, dann wählen Sie die zweite Option „Vordefinierte Konfiguration nutzen“ aus. Dadurch wird der Button „Wählen“ aktiviert und Sie können anschließend zum Ordner navigieren, in dem die Konfigurationsdatei liegt. Wenn Sie den korrekten Ordner angesteuert haben, dann sehen Sie eine Datei, die config.json heißt. Wählen Sie diese Datei aus und klicken auf „Öffnen“. Der Dateipfad wird anschließend in der Maske angezeigt, siehe Screenshot unten.

B. Wenn Sie jetzt „Weiter“ klicken wird der EDI-Connector nach der definierten Konfiguration der json-Datei installiert. Lesen Sie jetzt unter Punkt 11 weiter.

8. Konfigurationsfenster-Eingehend:

A. Konfigurationsid: Dieses Feld entspricht der Prozess-ID im myOpenFactory Portal unter „Meine Firma/Eingehende Belege, bzw. Ausgehende Belege“. In der Regel werden Ihnen aber die IDs von Ihrem Ansprechpartner der myOpenFactory mitgeteilt. Bitte tragen Sie den entsprechenden Wert ein.

B. Ordner: Hier steuern Sie über den Button „Wählen“ den Order an, in dem Sie die eingehenden EDI-Dateien erwarten.

C. Anhänge: Falls Sie Anhänge erwarten, dann können sie hier über den Button „Wählen“ den Order ansteuern, in dem Sie die eingehenden Anhänge erwarten.

D. Anhänge Dateinendungen: Hier tragen Sie ein, welche Dateiendung die Anhänge haben werden.

Für den Reiter „Test Eingehend“ wiederholen Sie den Prozess.

Im Reiter „Ausgehend“ gibt es 2 zusätzliche Elemente.

A. Dateiendung: Hier tragen Sie die Dateiendung der EDI-Dateien ein, die Sie versenden werden. Falls Sie keine Dateiendung nutzen, dann können Sie dieses Feld auch freilassen.

B. Fehlerordner: Über den Button „Wählen“ navigieren Sie zu einem Fehlerordner und bestätigen diesen. Sollte die Verbindung zu unserem Server unterbrochen sein, werden alle fehlgeschlagenen EDI-Dateien, die nicht versendet werden konnten in diesen Error-Order kopiert. Nach Wiederherstellung der Kommunikation brauchen Sie lediglich die Dateien aus dem Fehlerordner in das Outbound-Verzeichnis verschieben und diese werden dann an die myOpenFactory EDI-Plattform übermittelt.

Für den Reiter „Test Ausgehend“ wiederholen Sie den Prozess.

A. Funktionen hinzufügen oder entfernen

B. Reparieren

C. Entfernen

4 Konfiguration

Die Konfigurationsdatei befindet sich im Ordner des EDI-Connectors. Dieser befindet sich im Standard unter: ProgramData / myOpenFactory Software GmbH / EDI-Connector

Die Konfigurationsdatei ist eine Json-Datei und lässt sich mit jedem Text-Editor öffnen und bearbeiten.

Nachfolgende Elemente finden Sie zum Teil in der Original-Datei, andere wiederrum sind Erweiterungen, z.B. für Anhänge, die hier beispielhaft dargestellt sind:

{
  "instancePort": 9643,                                // Standardwert - Mutex-Port
  "proxy": null,                                       // Proxy-Konfiguration - URL und port
  "runWaitTime": "1m0s",                               // Standardwert - Rundenzeit
  "log": {
    "level": "info",                                   // Standardwert - Loglevel
    "type": "EVENT",                                   // Standardwert - FILE/EVENT/STDOUT_TEXT/STDOUT_JSON
    "folder": null,                                    // Standardwert - Order für Logdateien beim Typ 'FILE'
  },  
  "url": "https://rest.ediplatform.services",          // Standardwert - Basis URL für die Rest-Schnittstelle
  "caFile": null,                                      // Root-Zertifikatsdatei für die Platform
  "inbounds": [{                                       // RICHTUNG EINGEHEND Client
    "id": "nBjCkM",                                    // myOF Prozess ID - eingehend
    "type": "FILE",                                    // Dateitype
    "authName": null,                                  // Authentifizierungsnamen "EDI-Connector/[Name]"
    "settings": {
      "path": "C:/edi/inbound",                        // Pfad - Test Strecke eingehend
      "attachmentPath": "C:/edi/attachments_inbound",  // 
      "attachmentWhitelist": [                         // Standardwert - Von welcher Domain dürfen Anhänge runter geladen werden
        "https://myopenfactory.net",                   // Platform
      ],
      "mode": "create"                                 // Standardwert - create/append
    }
  }], 
  "outbounds": [{                                      // RICHTUNG AUSGEHEND Client
    "id": "0T6Qgn",                                    // myOF Prozess ID - ausgehend Produktiv
    "type": "FILE",                                    // Dateitype
    "authName": null,                                  // Authentifizierungsnamen "EDI-Connector/[Name]"
    "settings": {
      "message": {
        "path": "C:/edi/outbound",                     // Pfad - Produktive Strecke ausgehend
        "extensions": [                                // Dateinamenserweiterung
          "csv"                                        // Wert der Dateinamenserweiterung
        ],
        "waitTime": "1m0s"                             // Standardwert Rundenzeit
      }, 
      "attachment": {                                  // ANHÄNGE
        "path": "C:/edi/outbound/attachments",         // Pfad - Produktive Strecke ausgehend - Anhänge
        "extensions": [                                // Dateinamenserweiterung
          "pdf",                                       // Wert der Dateinamenserweiterung
          "step"                                       // Wert der Dateinamenserweiterung
        ],
        "waitTime": "15s"                              // Standardwert Rundenzeit - Anhänge
      },
      "errorPath": "C:/edi/outbound/error",            // Pfad - Fehlerordner ausgehend
      "successPath": "C:/edi/outbound/success"         // Pfad - Erfolgsordner ausgehend
    }
  }]
}

5 Steuerung des EDI-Connectors

Ab einer installierten Version des EDI-Connectors 2.0 oder höher wird im Microsoft Startmenü ein Verzeichnis EDI-Connector angelegt.

Hier gibt es zwei Menüpunkte:

A. EDI-Connector: Hierdurch wird die Anwendung ausgeführt, die Ihnen dann die unter Installation / Punkt 14 beschriebenen Menüpunkte anbietet.

B. Updater: Hierdurch wird geprüft, ob eine aktuellere Version des EDI-Connectors verfügbar ist. Diese wird Ihnen dann zum Update angeboten. Eine automatische Überprüfung auf Updates wird regelmäßig ausgeführt.

Selbstverständlich kann der EDI-Connector auch in der Liste der Windows-Dienst aufgerufen und dort gesteuert werden.

Zudem kann der Client ohne Installer über die Windows-Eingabeaufforderung (CMD) ausgeführt werden.

6 Fehleranalyse

• Sollte der EDI-Connector nicht ordnungsgemäß funktionieren, kann es helfen, den Dienst zu beenden und neu zu starten. Der Dienst heißt EDI-Connector.

• Führt ein Neustart des EDI-Connectors nicht zum ordnungsgemäßen Betrieb, können Sie sich die Logdateien ansehen. Der EDI-Connector schreibt seine Logs in die Windows Ereignisanzeige (Eventlogs). Diese können mit dem Eventviewer kontrolliert werden.

Klicken Sie mit der rechten Maustaste auf das Windows-Symbol und wählen Sie im Menü den Eintrag “Ereignisanzeige”. Sie das können das Programm auch über das “Ausführen”-Fenster [Windows] + [R] starten: Hier geben Sie den Befehl “eventvwr.exe” ein und bestätigen mit “OK”.

Mit Windows Bordmitteln oder mittels spezialisierter Software lassen sich die Eventlogs automatisiert überwachen.