Dokumentation: EDI

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 Übertragungswege
• 1.1 HTTPS
• 1.2 AS2
• 1.3 REST
• 1.4 cXML
• 1.5 OFTP2
• 1.6 SFTP
• 1.7 X400
• 1.8 SMTP
• 1.9 myOpenFactory-EDI-Connector
• 2 Zertifikate
• 3 Newsletter

1 Übertragungswege

1.1 HTTPS

HTTPS-Parameter

URL-Freigabe

Bitte geben Sie „myopenfactory.net“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist).

Sollten Sie unsere IP-Adressen benötigen um die nötigen Freigaben in Ihrer Software einzurichten, dann melden Sie sich bitte.

1.2 AS2

ACHTUNG:
Wenn Sie in Zukunft von uns über AS2-Zertifikatswechsel informiert werden möchten, müssen Sie sich über folgenden Link anmelden:
Anmeldung Zertifikatsankündigung

AS2-Parameter

Benutzername und Passwort, sowie die AS2-IDs, werden separat per E-Mail verschickt.

URL-Freigabe

Bitte geben Sie „myopenfactory.net“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist).

Sollten Sie unsere IP-Adressen benötigen um die nötigen Freigaben in Ihrer Software einzurichten, dann melden Sie sich bitte.

Download myOpenFactory AS2-Zertifikat (self-signed)

myOpenFactory AS2-Zertifikat CER-Datei

myOpenFactory AS2-Zertifikat CRT-Datei

1.3 REST

REST

Die vollständige Dokumentation zur Implementierung (API-Doc) unserer Rest-Schnittstelle finden Sie hier.

1.4 cXML

cXML-Parameter

URL-Freigabe

Bitte geben Sie „myopenfactory.net“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist).

Sollten Sie unsere IP-Adressen benötigen um die nötigen Freigaben in Ihrer Software einzurichten, dann melden Sie sich bitte.

1.5 OFTP2

OFTP-Parameter

1.6 SFTP

SFTP-Parameter

Ordnerstruktur

Standardeinstellung für unsere Ordner:

*Die Benennung der Ordnernamen ist aus Anwendersicht zu verstehen, d.h. inbound sind für Sie eintreffende Belege und outbound sind Belege, die Sie an uns senden.

Die Ordnernamen können wir auf Wunsch nach Ihren Vorgaben anpassen.

Dateiname

Per Default ist der Dateiname folgendermaßen aufgebaut: message_[transmissionID].edi
TransmissionID = einzigartige Übertragungsnummer der myOpenFactory

Gerne können wir den Dateinamen auch mit anderen Werten ergänzen, z.B. Belegnummer oder Datum.

Hinweis: Die Dateinamen sind case-sensitive.

Dateinamenserweiterung

Aus Sicherheitsgründen akzeptieren wir nur eine mit uns abgestimmte Dateinamenserweiterung, per Default ist das .edi

Gerne können wir die Dateinamenserweiterung nach Ihren Vorgaben anpassen.

Lösch- und Schreibrechte

Inbound = keine Schreibrechte
Outbound = keine Löschrechte

Löschbefehl senden

Die vollständige Übertragung der eingehenden Belege wird von Ihnen mit einem Löschbefehl bestätigt.

Authentifizierung

Wir unterstützen Passwortauthentifizierung, sowie Publickeyverfahren.

Parameter

Schlüsselaustauschalgorithmus

• urve25519-sha256
• curve25519-sha256@libssh.org
• curve448-sha512
• ecdh-sha2-nistp521
• ecdh-sha2-nistp384
• ecdh-sha2-nistp256
• diffie-hellman-group-exchange-sha256
• diffie-hellman-group18-sha512
• diffie-hellman-group17-sha512
• diffie-hellman-group16-sha512
• diffie-hellman-group15-sha512
• diffie-hellman-group14-sha256
• ext-info-s

Serverschlüsselalgorithmus

• ecdsa-sha2-nistp256
• rsa-sha2-512
• rsa-sha2-256
• ssh-rsa

Verschlüsselungsalgorithmus

• chacha20-poly1305@openssh.com
• aes128-ctr
• aes192-ctr
• aes256-ctr
• aes128-gcm@openssh.com
• aes256-gcm@openssh.com
• aes128-cbc
• aes192-cbc
• aes256-cbc

MAC algorithmus

• hmac-sha2-256-etm@openssh.com
• hmac-sha2-512-etm@openssh.com
• hmac-sha1-etm@openssh.com
• hmac-sha2-256
• hmac-sha2-512
• hmac-sha1

Kompressionsalgorithmus

• none
• zlib
• zlib@openssh.com

Öffentliche Schlüssel des Servers

ECDSA

Die ECDSA Schlüssel unseres SFTP-Servers:

---- BEGIN SSH2 PUBLIC KEY ----
AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBMTlDZNXItXF
mcV+1SaFHuj0pcoPir8qAC0XD4yiqNrB6X6Y7BRsBtBluhWhPpOSiOwSaP/KdEvl
4MNbepD76XM=
---- END SSH2 PUBLIC KEY ----

RSA

Die RSA Schlüssel unseres SFTP-Servers:

---- BEGIN SSH2 PUBLIC KEY ----
AAAAB3NzaC1yc2EAAAADAQABAAABAQDp1uYKLWlW6sKzcoPxNWjIJb4JUnbDKfxt
ThcNCtWuRH2dRKaes8aNW+12CIsRWmIWB2x5NDVeZTPDfwhB3KaucWi6tICV/mPL
YHNJHNXH5Ev4d5GBYan3HqNFv35lpUUg2ue1gemc1xDiakZxOpgdnsRy9XpKbX4p
56NbBINrGDyq+wm1zkUVNrVNNdB7sYnDGYxcwEjZC1nc0A0zXsURJDDRESsUNOa8
JXaaQ6kZYacbb7EVY4V7/bxE9yn9rPkK+9CpKeFu8jM9NtE8ge5pstgucyMvRiNu
V32Wtn0SH71qhuDy+TxuzcZf0FY75myEuUtCU5pT+APlzZJWBGh/

URL-Freigabe

Bitte geben Sie „myopenfactory.net“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist).

Sollten Sie unsere IP-Adressen benötigen um die nötigen Freigaben in Ihrer Software einzurichten, dann melden Sie sich bitte.

1.7 X400

X400 Adresse

Mailbox-Adresse der myOpenFactory bei der Deutschen Telekom

S=EDI;CN=EDI;O=MYOPENFACTORY;P=MGATE;A=VIAT;C=DE

1.8 SMTP

E-Mail-Adresse

Zum Übermitteln von Belegen an unsere Plattform, benötigen Sie eine individuelle Empfängeradresse, die Sie auf Anfrage erhalten.

Beispiel: muster-firma@api.myopenfactory.net

Case sensitive

Die E-Mail-Adresse ist case-sensitive, d.h. die einzelnen Zeichen müssen entsprechend unserer Vorgabe als Klein- oder Großbuchstabe übertragen werden.

Weitere Informationen

Der Beleg kann sowohl im Anhang als auch im Body der E-Mail übergeben werden. Beim Übermitteln im Body wird ausschließlich Plaintext unterstützt.

Es besteht die Möglichkeit einzelne Prozessschritte auf der Plattform direkt zu adressieren. Hierbei wird die Prozess-ID an die Empfängeradresse angehängt,
z.B. muster-firma+1A2b3C@api.myopenfactory.net.

1.9 myOpenFactory-EDI-Connector

Einleitung myOpenFactory-EDI-Connector

Der myOpenFactory-EDI-Connector übernimmt als Verbindungsclient den Dateiaustausch (Belege und ggf. Anhänge wie bspw. Zeichnungen etc.) zwischen Ihrem ERP-System und der myOpenFactory-EDI-Plattform. Der EDI-Connector ist ein Dienst, der auf ihrem Kommunikationsserver läuft und ein vollständiges Monitoring Ihrerseits erlaubt. Dadurch wird die Software auch strengen Compliance-Regeln gerecht.

Der EDI-Connector arbeitet ordnerbasiert, d.h. er nimmt Belege (bspw. eine Bestellung) aus einem definierten Verzeichnis als Datei entgegen und überträgt diese mittels zertifikatgeschützter HTTPS-Verbindung (Methode POST) an die myOpenFactory-Plattform.

Minütlich fragt unser EDI-Connector bei der myOpenFactory-Plattform an, ob Belege (bspw. Auftragsbestätigungen) für Sie bereit liegen. Bei einer positiven Antwort des myOpenFactory-Servers holt der EDI-Connector diese mittels zertifikatgeschützter HTTPS-Verbindung (Methode GET) ab und legt diese als Datei in einem definierten Verzeichnis auf Ihrem System ab.

Sollte es zu einem Problem mit dem Dateiversand kommen, werden die Belege in einen Error-Ordner verschoben, sodass keine Belege verloren gehen können.

Das zusammen mit dem EDI-Connector ausgelieferte Zertifikat ist 2 Jahre gültig und wird, bei Ablauf, von uns rechtzeitig neu versendet. Das alte Zertifikat muss dann nur durch das Neue ersetzt werden.

Der EDI-Connector erzeugt eine Log-Datei, die jeden Belegversand protokolliert. Wenn sie über einen eigenen Mailserver verfügen, können Sie sich, mit Hilfe des EDI-Connectors, automatisch benachrichtigen lassen, wenn Error-Einträge in das Log geschrieben werden.

1. Anforderungen

Es wird eine der folgenden Umgebungen benötigt:

• Windows Server 2012 oder höher
• CentOS 7 oder höher mit Docker-Container-Software siehe bspw.: https://docs.docker.com/install/linux/docker-ce/centos/
• Ubuntu 16.04 oder höher mit Docker-Container-Software siehe bspw.: https://docs.docker.com/install/linux/docker-ce/ubuntu/

2. Installation

Die Installation und Konfiguration erfolgt durch einen myOpenFactory-Mitarbeiter zusammen mit Ihrem Systemadministrator mittels einer Fernwartungs-Software. Dauer: ca. 40 min.

3. Vorbereitungen zur Installation des EDI-Connectors

3.1 Einrichten der Verzeichnisse

Folgende Ordner sollten eingerichtet werden:

Ein „prod“ Verzeichnis mit folgenden Unterordnern:

• Ein „prod-out“ Ordner für die ausgehenden produktiven Belege.
• Ein „prod-in“ Ordner, in denen die eingehenden produktiven Belege abgelegt werden, die der EDI-Connector von der Plattform abholt.
• Ein „error“ Ordner für die Belege die nicht erfolgreich an die Plattform gesendet werden konnten. Wenn dieser Fall eintritt, sendet der EDI-Connector eine E-Mail.* Nachdem die Verbindung wieder hergestellt wurde, kann der Beleg in den prod-out Ordner verschoben werden. Er wird dann automatisch vom EDI-Connector an die Plattform gesendet.
• Auf Wunsch kann ein optionaler „success“ Ordner angelegt werden, in dem der EDI-Connector die erfolgreich versendeten Belege als Kopie ablegt.

Einen „test“ Verzeichnis mit folgenden Unterordnern:

• Ein „test-out“ Ordner für die ausgehenden Test-Belege.
• Ein „test-in“ Ordner, in denen die eingehenden Test-Belege abgelegt werden, die der Connector von der Plattform abholt.
• Ein „test-error“ Ordner für die Belege die nicht erfolgreich an die Plattform gesendet werden konnten. Wenn dieser Fall eintritt, sendet der EDI-Connector eine E-Mail.* Nachdem die Verbindung wieder hergestellt wurde, kann der Beleg in den prod-out Ordner verschoben werden. Er wird dann automatisch vom EDI-Connector an die Plattform gesendet.

Wenn möglich, legen Sie eine Testnachricht (z. B. eine Bestellung oder AB) in den Prod-Out- oder Test-Out-Ordner, damit wir einen Konnektivitäts-Test durchführen können.

3.2 Freigabe Netzwerk

Sie müssen sicherstellen, dass die Freigaben zum Zugriff auf andere Server innerhalb Ihres Netzwerkes eingerichtet sind, falls die obengenannten Ordner auf einem anderen Server liegen.

3.3 Freigabe Internet

Sie müssen sicherstellen, dass der EDI-Connector mit den nötigen Freigaben ausgestattet ist, um das Internet zu erreichen. Bitte geben Sie „myopenfactory.net“ und „github.com“ in Ihrer Firewall und Ihrem Proxy frei (allowlist/acceptlist). Bitte bedenken Sie, auch evtl. eingesetzte Virenscanner können die Konnektivität beeinflussen.

Sollten Sie unsere IP-Adressen benötigen um die nötigen Freigaben in Ihrer Software einzurichten, dann melden Sie sich bitte.

3.4 Speicherkapazität

40 – 50 GB sind ausreichend, aber wenn Sie den Success-Ordner benötigen, sollten Sie mehr Kapazität einplanen.

3.5 SMTP Erreichbarkeit

• Wenn Sie über Fehler informiert werden möchten, benötigt der EDI-Connector die Möglichkeit, auf Ihren SMTP-Server zuzugreifen. Nach einer erfolgreichen Einrichtung sendet der EDI-Connector eine E-Mail, wenn ein Error-Eintrag in den Logs erkannt wird.

3.6 Installationsdatei herunterladen

Bitte laden Sie die passende Installationsdatei von Github herunter (z.B. myof-client.exe_windows_amd64.zip) und legen sie auf dem gewünschten Kommunikationsserver ab. https://github.com/myopenfactory/client/releases

4. GitHub

Unser EDI-Connector liegt als open-Source Projekt auf GitHub und kann von Ihnen validiert werden. Unsere Updates sind durch eine Signatur geschützt. Siehe: https://github.com/myopenfactory/client

5. Update des EDI-Connectors

Bei allen Angaben in dieser Anleitung gehen wir davon aus, dass der EDI-Connector im Pfad “C:\Program Files\myOpenFactory\Client” installiert ist.

5.1 Stoppen

Bevor der EDI-Connector aktualisiert werden kann, muss dieser zunächst gestoppt werden. Dafür wechseln Sie in die Windows-„Dienste“ (Windows-Taste drücken und nach „Dienste“ suchen).

Jetzt lokalisieren den EDI-Connector mit dem Namen „myof-client“ (die Namensgebung hinter „myof-client“ kann je nach Nutzer leicht abweichen). Anschließend stoppen Sie den EDI-Connector mithilfe des Kontextmenüs (Rechtsklick) und der Selektion „Beenden“. Neben dem Namen wird in der selektierten Zeile der aktuelle Status der Software angezeigt. Zu Beginn der Prozedur sollte sich dieser im Status „Wird ausgeführt“ befinden und nach dem erfolgreichen Stoppen sollte das Feld „Status“ leer sein.

5.2 Update

Der EDI-Connector verfügt über einen integrierten Update-Mechanismus. Hierbei sucht der EDI-Connector nach der neusten Version und aktualisiert sich nach Bestätigung durch den Nutzer auf eben diese.

• Zum Starten des Updates wird eine administrative Powershell benötigt.

• Anschließend muss mit der Powershell in den Ordner des EDI-Connectors navigiert werden. Hierfür wird der Befehl „cd (change directory“) verwendet. Die Standardinstallation des EDI-Connectors befindet sich unter „C:\Program Files\myOpenFactory\Client“, sodass mit dem Befehl „cd ‘C:\Program Files\myOpenFactory\Client‘ “ in den Ordner der Installation gewechselt werden kann.
• Im Anschluss kann das Update mithilfe von „.\myof-client.exe update“ angestossen werden. Hierbei fragt der EDI-Connector, ob das Update auf die neuste Version z.B. 1.4.2 durchgeführt werden soll. Diese Abfrage muss mit einem „y“ (Yes) bestätigt werden. Sollte keine neuere Version zur Verfügung stehen, meldet der EDI-Connector dies mit einer entsprechenden Meldung. Sollte beim Einspielen des Updates ein Problem auftreten, folgen Sie bitte den unter Punkt 5.4 angegebenen Hinweisen und führen ein manuelles Update durch.

Beispiel - Erfolgreiches Update

Beispiel - Fehlerhaftes Update

5.3 Starten

Folgen Sie den gleichen Schritten wie unter 5.1 beschrieben um die Windows-„Dienste“ zu öffnen und den myOpenFactory-EDI-Connector zu lokalisieren. Anschließend starten Sie bitte den EDI-Connector über das Kontextmenu (Rechtsklick).

Sollte der EDI-Connector sich wider Erwarten nicht starten lassen, so kontaktieren Sie bitte unseren Support – support@myopenfactory.com . Halten Sie bitte für weitere Rückfragen die Log-Dateien aus dem Ordner „C:\ProgramData\myOpenFactory\Client\logs“ zur Verfügung.

5.4 Optional: Manuelles Einspielen

Sollte das automatische Update unter 5.2 einen Fehler ergeben haben, versuchen Sie bitte das Update manuell einzuspielen.

• Hierfür muss der EDI-Connector zunächst, wie unter 1 beschrieben, gestoppt werden.
• Bitte benennen Sie die alte EDI-Connector-Datei unter „C:\Program Files\myOpenFactory\Client“ in .myof-client.exe.old um, bevor Sie fortfahren (bitte beachten Sie hier den Punkt (.) vor dem eigentlichen Namen).
• Anschließend laden Sie auf dem Server oder einem externen Computer die neuste Version des EDI-Connectors von „https://github.com/myopenfactory/client/releases/latest“ herunter. Hierbei benötigen Sie in der Regel die Version „myof-client_windows_amd64.zip“.
• Nach erfolgreichem Herunterladen der Datei muss diese entpackt und die enthaltene Datei „myof-client.exe“ in den Ordner „C:\Program Files\myOpenFactory\Client“ kopiert werden (Bitte beachten Sie, dass hierfür unter Umständen administrative Rechte benötigt werden).
• Im Anschluß folgen Sie bitte der Anleitung unter Punkt 5.3 zum Starten des EDI-Connectors.

5.5 Optional: Update rückgängig machen

Sollten nach dem Update Probleme oder Fehler mit dem EDI-Connector auftreten, so wenden Sie sich bitte an unseren Support – support@myopenfactory.com.

Zusätzlich kann es in Ausnahmefällen hilfreich sein, den EDI-Connector auf die alte Version zurückzusetzen. Die jeweils zuvor installierte Version des EDI-Connector wird nach einem Update im Programmverzeichis („C:\Program Files\myOpenFactory\Client“) mit dem Namen .myof-client.exe.old abgelegt. Zum Einspielen der alten Version ist es ausreichend, die neue Version „myof-client.exe“ zu löschen und die alte in „myof-client.exe“ umzubennenen. Bitte beachten Sie, dass hierfür der EDI-Connector gestoppt sein muss, siehe 5.2. Im Anschluss können Sie mit dem Punkt 5.3 zum Starten des EDI-Connectors fortfahren.

5.6 Troubleshooting des Update-Vorgangs

• Während des Updates gibt der EDI-Connector den Fehler aus, dass die Rechte nicht ausreichen.

Lösung: Bitte starten Sie das Update mithilfe einer administrativen Powershell

• Der EDI-Connector kann das Update nicht automatisch von GitHub herunterladen.

Lösung: Bitte führen Sie ein manuelles Update mithilfe von Punkt 5.4 durch.

• Die Datei .myof-client.exe.old wird nicht angezeigt

Lösung A: In den Einstellungen des Windows Explorers kann man das Anzeigen von versteckten Dateien aktivieren (siehe: https://support.microsoft.com/de-de/help/14201/windows-show-hidden-files)

Lösung B: Das Update war nicht erfolgreich. Bitte führen Sie ein manuelles Update durch, siehe 5.4

6. Zertifikatswechsel

• Wenn Sie ein neues Zertifikat von uns zugesendet bekommen, enthält die Email eine Zip-Datei.

• In der Zip-Datei befinden sich zwei Dateien: “certificate.pem” und “certificate.p12”. Die .p12-Datei ist für den EDI-Connector nicht relevant, diese wird nur für den Browser benötigt. Der EDI-Connector benötigt die PEM-Datei.

• Diese benennen Sie einfach in “client.crt” um. Entweder per Kontext-Menü mittels Rechtsklick / Umbenennen oder mit der F2-Taste.

• Es sollte anschließend folgendermaßen aussehen.

• Jetzt öffnen Sie das Verzeichnis der Dienste und suchen den myOF-Client (kann evtl. auch anders benannt sein). Der EDI-Connector muss nun gestoppt werden, wenn er nicht schon steht. (Letzteres tritt ein, wenn das Zertifikat schon abgelaufen ist). Siehe Punkt 5.1

• Anschließend wechseln Sie in den Installations-Ordner des EDI-Connectors unter “ProgramData”. Dort finden Sie die abgelaufene “client.crt”. Diese ersetzen Sie mit der neuen “client.crt” die Sie soeben erhalten und umbenannt haben.

• Prüfen Sie zuletzt, ob der Dateiname des Zertifikats in der Datei config.properties dem neuen Dateinamen des Zertifikats entspricht. Falls nicht, bitte benennen Sie die Einstellung in der config.properties entsprechend um, damit das Zertifikat bei Neustart geladen werden kann.

• Danach starten Sie den EDI-Connector neu. Siehe 5.3

7. Fehleranalyse

Sollte der EDI-Connector nicht ordnungsgemäß funktionieren, kann ein Neustart des Dienstes helfen, siehe Punkt 5.3

Sollte der Neustart des EDI-Connectors das Problem nicht lösen, können Sie die Logdateien durchsuchen. Sie befinden sich üblicherweise im Installationsverzeichnis des EDI-Connectors unter ‚ProgramData‘.

Hier öffnen Sie die jüngste Logdatei und suchen nach dem Stichwort ‚ERROR‘.

Wenn die Fehlermeldung nicht aussagekräftig genug ist oder keine Error-Meldung vorhanden ist, wenden Sie sich bitte an unseren Support – support@myopenfactory.com. Senden Sie bitte in jedem Falle die Logdateien der letzten 3 Tage mit, wir kümmern uns dann umgehend um das Problem.

2 Zertifikate

Transport Layer Security (TLS)

Applicability Statement 2 (AS2)

3 Newsletter

Aktuelle Nutzerliste