Documentation: EDI

Please note that downloading this page as a PDF creates a static document. Any changes to the content presented cannot be included in the PDF later. We therefore advise to always use the version available online.

• 1 Certificates
• 2 Protocols
• 2.1 AS2
• 2.2 OFTP2
• 2.3 REST
• 2.4 HTTPS
• 2.5 cXML
• 2.6 SFTP
• 2.7 X400
• 2.8 SMTP
• 2.9 myOpenFactory-EDI-Connector
• 3 File formats
• 4 Newsletter

1 Certificates

Transport Layer Security (TLS)

Applicability Statement 2 (AS2)

2 Protocols

2.1 AS2

IMPORTANT NOTE:
If you would like to be informed by us about upcoming AS2 certificate changes,you need to register viathe following link:
Registration

AS2 parameter

Username and password as well as the AS2 IDs will be provided seperately via mail.

URL-Sharing

Please allow “myopenfactory.net” in your firewall and proxy.

If you need our IP addresses to set up the necessary approvals in your software, please contact us.

Download myOpenFactory AS2-certificate (self-signed)

myOpenFactory AS2-Certificate CER-file

myOpenFactory AS2-Certificate CRT-file

2.2 OFTP2

OFTP-Parameter

2.3 REST

REST

The complete documentation for the implementation (API-Doc) of our rest interface can be found here.

2.4 HTTPS

HTTPS-Parameter

URL-Sharing

Please allow “myopenfactory.net” in your firewall and proxy.

If you need our IP addresses to set up the necessary approvals in your software, please contact us.

2.5 cXML

cXML-Parameter

URL-Sharing

Please allow “myopenfactory.net” in your firewall and proxy.

If you need our IP addresses to set up the necessary approvals in your software, please contact us.

2.6 SFTP

SFTP parameter

Folder structure

Default setting for our folders:

*The naming of the folders is to be understood from the user’s point of view, i.e. inbound are documents you receive and outbound are documents that you send to us.

We can customize the folder names according to your specifications if you wish.

Filename

By default, the file name is structured as follows: message_[transmissionID].edi
TransmissionID = myOpenFactory´s unique transmission number

We are also happy to add other values to the file name, e.g. document number or date.

Note: The file names are case sensitive.

File name extension

For security reasons, we only accept a filename extension agreed with us, by default this is .edi

We will gladly customize the file name extension according to your specifications.

Remove and write rights

Inbound = no write access
Outbound = no remove access

Remove files

The complete transfer of the incoming documents is confirmed by you with a remove command.

Authentication

We support password authentication and publickey authentication.

Parameter

Key exchange algorithm

• 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

Server key algorithm

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

Encryption algorithm

• 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 algorithm

• 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

Compression algorithm

• none
• zlib
• zlib@openssh.com

Public key of the server

ECDSA

ECDSA key of our SFTP server:

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

RSA

RSA key of our SFTP server:

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

URL sharing

Please allow “myopenfactory.net” in your firewall and proxy (allowlist/acceptlist).

If you need our IP addresses to set up the necessary approvals in your software, please contact us.

2.7 X400

X400 Address

Mailbox address of myOpenFactory at Deutsche Telekom

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

2.8 SMTP

Email address

To submit messages to our platform, you need an individual email address, which you will receive on request.

Example: sample-company@api.myopenfactory.net

Case sensitive

The email address is case sensitive, which means the individual characters must be transmitted as lowercase or uppercase letters according to our specifications.

Further information

The messages can be transferred both as an attachment or in the body of the email. When transmitting in the body, only plain text is supported.

It is possible to address individual process steps directly on the platform. In this case, the process ID is appended to the recipient address, for example sample-company+1A2b3C@api.myopenfactory.net.

2.9 myOpenFactory-EDI-Connector

Introduction of the myOpenFactory EDI Connector

As a connection client, the myOpenFactory EDI Connector executes the file exchange (EDI-files and, if necessary, attachments such as technical drawings etc.) between your ERP system and the myOpenFactory EDI platform. The connection client is a service that runs on your communication server and allows complete monitoring on your part. As a result, the software also meets strict compliance rules.

The EDI Connector works folder-based, it fetches document-files (e.g. an order) from a defined directory and transfers them to the myOpenFactory platform using a certificate-protected HTTPS connection (method POST).

Every minute our EDI connector checks whether documents (e.g. order confirmations) could be picked up from the myOpenFactory platform. If yes the EDI connector retrieves it using a certificate-protected HTTPS connection (method GET) and stores the file in a designated folder on your system.

If there is a problem with the file dispatch, the documents are moved to an error folder so that no documents can be lost.

The certificate that comes with the EDI connector is valid for 2 years and a new one will be sent by us in good time upon expiration. The old certificate only needs to be replaced by the new one.

The EDI connector generates a log file that logs each of the Connector’s actions. If you have your own mail server, you can be automatically notified when error entries are written to the log.

1. Requirements

One of the following server-OS are required:

• Windows Server 2012 or higher • CentOS 7 or higher with Docker-Container-Software see e.g.: https://docs.docker.com/install/linux/docker-ce/centos/ • Ubuntu 16.04 or higher with Docker-Container-Software see e.g.: https://docs.docker.com/install/linux/docker-ce/ubuntu/

2. Installation

The installation and configuration is carried out by a myOpenFactory employee together with your system administrator using remote control software. Duration: approx. 40 min.

3. Preparing to Install the EDI Connector

3.1 Setting up the directories

A “prod” directory with the following subfolders:

Ein „prod“ Verzeichnis mit folgenden Unterordnern: • A “prod-out” folder for the outgoing productive documents. • A “prod-in” folder in which the incoming productive documents that the EDI Connector fetches from the platform are stored. • An “error” folder for the documents that could not be successfully sent to the platform. if this occurs the EDI-Connector sends an e-mail*. After the connection has been re-established, the document can be moved to the prod-out folder. Then it will be sent to the platform automatically. • If desired, an optional “success” folder can be created in which the EDI connector stores the successfully sent documents as a copy.

A “test” directory with the following subfolders:

• A “test-out” folder for the outgoing productive documents. • A “test-in” folder in which the incoming productive documents that the EDI Connector fetches from the platform are stored. • An “error” folder for the documents that could not be successfully sent to the platform. if this occurs the EDI-Connector sends an e-mail*. After the connection has been re-established, the document can be moved to the prod-out folder. Then it will be sent to the platform automatically.

If possible, put a test message (e.g. an po or oc) in the prod-out or test-out folder so that a connectivity test can be done.

3.2 Network share

You must ensure that a permitted access is configured to access other servers within your network if the above folders are on a different server.

3.3 Internet share

You must ensure that the EDI connector is equipped with the necessary permission to access the Internet. Please allow “myopenfactory.net” and “github.com” in your firewall and proxy. Any virus scanners that may be used can also affect connectivity.

If you need our IP addresses to set up the necessary approvals in your software, please contact us.

3.4 Storage capacity

40 – 50 GB is sufficient, but if you need the Success folder, you should plan for more capacity.

3.5 SMTP accessibility

• If you want to be notified of errors, the EDI Connector needs the permission to access your SMTP server. After a successful setup, the EDI connector sends an email when an error entry is detected in the logs.

3.6 Download installation file:

Please download the suitable installation file from Github (e.g. myof-client.exe_windows_amd64.zip) and save it on the desired communication server. https://github.com/myopenfactory/client/releases

4. GitHub

Our EDI Connector is available as an open-source project on GitHub and can be validated by you. Our updates are signature-protected. See: https://github.com/myopenfactory/client

5. Update of the EDI-Connector

For all the information in this guide, we assume that the EDI Connector is installed in “C: \Program Files\myOpenFactory\Client”.

5.1 Stopping

Before the EDI Conenctor can be updated, it must first be stopped. To do this, switch to the Windows “Services” (press windows key and search for “Services”).

Now locate the EDI Connector with the name “myof-client” (the naming after “myof-client” may vary slightly depending on the user). Then stop the EDI connector using the context menu (right-click) and the “Stop” selection. Next to the name, the current status of the EDI Connector is displayed in the selected line. At the beginning of the procedure, it should be in the “Running” state and after successful stopping, the “Status” field should be empty.

5.2 Updating

The EDI Conenctor has a built-in update mechanism. The EDI connector searches for the latest version and updates itself to the latest version after confirmation by the user.

• An administrative powershell is required to start the update.

• Then you have to navigate to the EDI Conenctor’s folder with the Powershell. The command “cd (change directory”) is used for this purpose. The default installation of the EDI connector is located at „C:\Program Files\myOpenFactory\Client“, so you can use the „cd ‘C:\Program Files\myOpenFactory\Client‘ “ command to navigate to the installation folder.
• The update can then be triggered using “.myof-client.exe update”. The EDI connector asks whether the update to the latest version e.g. 1.4.2 should be carried out. This query must be confirmed with a “y” (Yes). If no newer version is available, the EDI Connector reports this with a corresponding message. If a problem occurs when installing the update, please follow the instructions given under point 5.4 and perform a manual update.

Example - Successful Update

Example - Failed Update

5.3 Starting

Follow the same steps as described in 5.1 to open the Windows “Services” and locate the myOpenFactory EDI Connector. Then please start the Connector via the context menu (right-click).

If, contrary to expectations, the EDI connector cannot be started, please contact our support – support@myopenfactory.com . For further questions, please keep the log files from the folder „C:\ProgramData\myOpenFactory\Client\logs“ available.

5.4 Optional: Manual update

If the automatic update under 5.2 has resulted in an error, please try to install the update manually.

• To do this, the Connector must first be stopped as described in 5.1.
• Please rename the old Connector file under „C:\Program Files\myOpenFactory\Client“ to .myof-client.exe.old before proceeding (please note the dot (.) before the actual name).
• Then download the latest version of the Connector from https://github.com/myopenfactory/client/releases/latest to the server or an external computer. Usually you´ll need the version “myof-client_windows_amd64.zip”.
• After successful downloading the file, it must be unpacked and the contained file “myof-client.exe” copied to the folder „C:\Program Files\myOpenFactory\Client“ (Please note that administrative rights may be required for this).
• Then please follow the instructions under point 5.3 to start the EDI Connector.

5.5 Optional: Undo update

If you encounter problems or errors with the EDI Connector after the update, please contact our support – support@myopenfactory.com.

Sometimes, it may be helpful to reset the EDI connector to the old version. After an update, the previously installed version of the EDI Connector is stored in the program directory („C:\program files\myOpenFactory\client“) with the name .myof-client.exe.old. To install the old version, just delete the new version “myof-client.exe” and rename the old version to “myof-client.exe”. Please note that the EDI Connector must be stopped for this, see 5.2. You can proceed now to point 5.3 to restart the EDI Connector.

5.6 Troubleshooting the update process

• During the update, the EDi Connector returns an error that your rights are insufficient.

Solution: Please start the update using an administrative powershell.

• The EDI cannot download the update from GitHub automatically.

Solution: Please perform a manual update using point 5.4.

• The file .myof-client.exe.old is not displayed.

Solution A: In the settings of Windows Explorer you can activate the display of hidden files (see: https://support.microsoft.com/en-de/help/14201/windows-show-hidden-files)

Solution B: The update was not successful. Please perform a manual update, see 5.4

6. Certificate Change

• If you receive a new certificate from us, the email contains a zip file.

• If you unzip it, you will see two files: “certificate.pem” and “certificate.p12”. The.p12 file is not relevant for the EDI Connector, just for using the browser. Only the PEM file will be used for the EDI Connector.

• Simply rename it to “client.crt”. Either via context menu by right-clicking / rename or with the F2 key.

• It should look like this afterwards.

• Now open the directory of services and search for the myOF-client (may also be named differently). The Connector must now be stopped if it is han´t already stopped. (The latter occurs when the certificate has already expired). See point 5.1

• Then change to the installation folder of the EDI Connector under “ProgramData”. There you will find the expired “client.crt”. Replace it with the new “client.crt” that you have just received and renamed.

• Finally, verify that the certificate filename in the config.properties file matches the new certificate filename. If not, please rename the configuration in config.properties accordingly so that the certificate can be loaded on restart.

• After that, restart the Connector. See 5.3

7. Error-handling

If the EDI Connector does not work properly, restarting can help, see point 5.4

If restarting the Connector does’nt solve the problem, you can search the log files. They are usually located in the installation directory of the EDI Connector under ‘ProgramData’.

Here you open the most recent log file and search for the keyword ‘ERROR’.

If the error message is not ‘speaking’ enough or there is no error message, please contact our support – support@myopenfactory.com. In any case, please send the log files of the last 3 days, we will then take care of the problem immediately.

3 File formats

Unlike the transmission paths, it is not possible to present a list for EDI formats, as there is a wide variety of different formats and versions of these. In this respect, an individual mapping must always be set up.

Introduction

EDI formats can be divided into 4 groups according to their syntax.  

Flat file formats or ASCII formats

Here, each piece of information is assigned a specific position in the file, e.g. in line 2 from position 75 to 99, the supplier’s city name must be positioned.

Well-known examples are e.g. flat IDoc and the old VDA format.

000123456      Campus-Boulevard 55       Aachen       52074       DE

XML formats

This is probably the largest group of EDI formats. Each piece of information is placed between an opening and a closing TAG <City>Aachen</City>. Individual pieces of information are sorted into groups, which significantly increases readability.

Well-known examples are openTRANS, XML-IDoc and our myOpenFactory in-house format. Many ERP systems also use XML as an exchange format.

<Company>
  <City>Aachen</City>
  <CompanyID>123456</CompanyID>
  <Country>DE</Country>
  <Name>myOpenFactory Software GmbH</Name>
  <Street>Campus-Boulevard 55</Street>
  <ZipCode>52074</ZipCode>
</Company>  

Segment-based formats

EDIFACT

The EDIFACT standard was developed by the UN in the 1970s and is still maintained today by a UN organization (UN/CEFACT). EDIFACT is the established standard in some industries and is still widely used today.
NOTE: EDIFACT is not the same as EDI, the latter stands for Electronic Data Interchange, i.e. describes the general process of electronic data exchange!

In an EDIFACT file, the information is grouped in individual segments, which are specified by an introductory identifier, e.g. NAD+BY stands for Name And Address of the BUYER (customer). The segment is concluded with an apostrophe.

NAD+BY+123456++myOpenFactory Software GmbH+Campus-Boulevard 55+Aachen++52074+DE'

ANSI X12

This standard was developed in the late 1970s by the American National Standards Institute and is therefore widely used in the USA. Here, too, the information is grouped into individual segments, which are specified by corresponding identifiers; here N1*BY stands for the buyer’s address data.

N1*BY*myOpenFactory Software GmbH*92*123456'
N3*Campus-Boulevard 55'
N4*Aachen**52074*520'

Table formats

CSV stands for Comma Separated Value and is essentially a table format. CSV files can therefore also be displayed natively in MS Excel, or Excel tables can be exported as a csv file.

In a CSV file, there are columns in which the value is specified, e.g. column 15 contains the supplier’s city name.

Sometimes different information is transferred for different rows, with each row containing different column information.
For example, the first line contains the header information of the document and the following lines contain each article item in a line.

K;123456;;;;;;myOpenFactory Software GmbH;Campus-Boulevard 55;DE;52074;Aachen;DE;

Application

As myOpenFactory, we support every file format. We are always guided by the technical specifications and possibilities of our customers. We require documentation and sample documents in order to be able to create the appropriate mapping.

Sometimes we are also asked whether we can provide documentation for a file format. Please contact us if required, we can also help you in this case.

4 Newsletter

Current participant list