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 Protocols
• 1.1 AS2
• 1.2 OFTP2
• 1.3 REST
• 1.4 HTTPS
• 1.5 cXML
• 1.6 SFTP
• 1.7 X400
• 1.8 SMTP
• 1.9 myOpenFactory-EDI-Connector
• 1.9.1 Introduction
• 1.9.2 Preparations
• 1.9.3 Installation
• 1.9.4 Configuration
• 1.9.5 EDI connector controls
• 1.9.6 Error handling
• 2 File formats
• 3 Newsletter

1 Protocols

1.1 AS2

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

1.2 OFTP2

OFTP-Parameter

1.3 REST

REST

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

1.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.

1.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.

1.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.

1.7 X400

X400 Address

Mailbox address of myOpenFactory at Deutsche Telekom

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

1.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.

1.9 myOpenFactory-EDI-Connector

1.9.1 Introduction

The myOpenFactory EDI Connector, hereinafter referred to as the EDI Connector, acts as a connection client for file exchange (documents and any attachments such as technical drawings, etc.) between your ERP system and the myOpenFactory EDI platform. The EDI Connector is installed as a service that runs on your communication server and allows you to monitor it. This means that the EDI Connector also complies with strict compliance rules.

The EDI connector works on a directory basis, i.e., documents (e.g., an order) are received as files from a defined folder and transferred to the myOpenFactory EDI platform via a REST connection (POST method).

If documents (e.g., order confirmations) are available on the myOpenFactory EDI platform, the EDI connector retrieves them using a REST connection (GET method) and stores them as files in a defined folder on your system.

The sending and retrieval actions are performed at short intervals

If there is a problem with file transfer, the outgoing documents are moved to an “error” directory so that no documents can be lost.

The EDI connector generates a log file that records every action. These log entries are entered into the event log of the Windows OS. You can monitor this with an appropriate monitoring tool.

1.9.2 Preparations

Setting up the directories

The EDI connector works on a directory basis, i.e., it receives documents (e.g., an order) from a defined directory as a file and transfers them to the myOpenFactory EDI platform and vice versa. The necessary directories can be created locally on the communication server or on a network drive.

The following directories should be set up:

A “prod” directory with the following subdirectories:

• A “prod-out” directory for outgoing productive documents.
• A “prod-in” directory in which the incoming productive documents that the EDI connector retrieves from the platform are stored.
• An “error” directory for documents that could not be sent to the platform successfully. Once the connection has been reestablished, the document can be moved manually to the “prod-out” directory so that it is then sent automatically to the platform by the EDI connector.

A “test” directory with the following subdirectories:

• A “test-out” directory for outgoing test documents.
• A “test-in” directory where incoming test documents are stored, which the EDI connector retrieves from the platform.

After setup, we recommend placing a test message (e.g., any text message with test text) in the “prod-out” and “test-out” directories so that connection tests can be performed.

Sharing when using network drives

Ensure that permissions for accessing network drives are set up if the above directories are located on another server. The EDI connector requires write, read, and delete permissions for the directories..

Sharing Internet

Ensure that the EDI connector has the necessary permissions to access the internet. Add “myopenfactory.net” (only if attachments are sent) and “rest.ediplatform.services” to your firewall and proxy allowlist/acceptlist. Keep in mind that any virus scanners you may be using can also affect connectivity.

Download installation file

Download the appropriate installation file from Github. A Windows Installer version is also available in newer releases, starting from version 2.0. (edi-connector_installer.exe) https://github.com/myopenfactory/client/releases You can validate our EDI connector. Our updates are protected by a signature. See: https://github.com/myopenfactory/client

Interface-Login credentials

The EDI connector requires a username and password as well as process-IDs to establish a connection. You can obtain this data from your myOpenFactory contact person.

1.9.3 Installation

1. Please select your installation language and confirm with “Next”.

A. Leave the field blank and simply click ‘Next.’. The EDI connector will then create a local user in the Active Directory of this domain.

B. However, for correct operation, a separate user with appropriate rights should be created in Active Directory for each service. Once this has been done, the relevant details can be entered here. This is particularly important because it enables the EDI connector to access folders on remote servers..

A. If you have a configuration file, select the second option, “Use predefined configuration.” This activates the “Browse” button, allowing you to navigate to the folder where the configuration file is located. Once you have navigated to the correct folder, you will see a file named config.json. Select this file and click “Open.” The file path will then be displayed in the mask, see screenshot below..

B. If you now click “Continue,” the EDI connector will be installed according to the defined configuration of the json file. Now continue reading under point 11..

8. Configuration-window - Inbound:

A. Configuration-id: This field corresponds to the process ID in the myOpenFactory portal under “My company/Incoming documents” or “Outgoing documents.” However, your myOpenFactory contact person will usually provide you with the IDs. Please enter the corresponding value.

B. Folder: Here, use the “Browse” button to navigate to the folder where you expect the incoming EDI files to be stored.

C. Attachments: If you are expecting attachments, you can use the “Browse” button to navigate to the folder where you expect the incoming attachments to be stored.

D. Attachment file extensions: Here you can specify which file extension the attachments will have.

For the “Test Incoming” tab, repeat the process.

There are two additional elements in the “Outbound” tab

A. File extension: Enter the file extension of the EDI files you will be sending here. If you do not use a file extension, you can leave this field blank.

B. Error folder: Use the “Browse” button to navigate to an error folder and confirm your selection. If the connection to our server is interrupted, all failed EDI files that could not be sent are copied to this error folder. Once communication has been restored, simply move the files from the error folder to the outbound directory and they will be transmitted to the myOpenFactory EDI platform.

For the “Outbound test” tab, repeat the process.

A. Add or remove features

B. Repair

C. Remove

1.9.4 Configuration

The configuration file is located in the installation directory of the EDI connector. By default, this is located at: ProgramData / myOpenFactory Software GmbH / EDI-Connector

The configuration file is a YAML file and can be opened and edited with any text editor.

Some of the following elements can be found in the original file, while others are extensions, e.g. for attachments, which are shown here as examples:

{
  "instancePort": 9643,                                // Default value - Mutex-Port
  "proxy": null,                                       // Proxy-Configuration - URL and port
  "runWaitTime": "1m0s",                               // Default value - lap time
  "log": {
    "level": "info",                                   // Default value - Loglevel
    "type": "EVENT",                                   // Default value - FILE/EVENT/STDOUT_TEXT/STDOUT_JSON
    "folder": null,                                    // Default value - Folder for log files of type 'FILE'
  },  
  "url": "https://rest.ediplatform.services",          // Default value - Basis URL for the rest interface
  "caFile": null,                                      // Root-Certificate for the platform
  "inbounds": [{                                       // DIRECTION INBOUND Client
    "id": "nBjCkM",                                    // myOF process ID - inbound
    "type": "FILE",                                    // file type
    "authName": null,                                  // authentication names "EDI-Connector/[Name]"
    "settings": {
      "path": "C:/edi/inbound",                        // Directory - Test inbound
      "attachmentPath": "C:/edi/attachments_inbound",  // 
      "attachmentWhitelist": [                         // Default value - From which domain can attachments be downloaded
        "https://myopenfactory.net",                   // Platform
      ],
      "mode": "create"                                 // Default value - create/append
    }
  }], 
  "outbounds": [{                                      // DIRECTION OUTBOUND Client
    "id": "0T6Qgn",                                    // myOF process ID - outbound productive
    "type": "FILE",                                    // file type
    "authName": null,                                  // authentication names "EDI-Connector/[Name]"
    "settings": {
      "message": {
        "path": "C:/edi/outbound",                     // Directory - productive outbound
        "extensions": [                                // File name extension
          "csv"                                        // Value of file name extension
        ],
        "waitTime": "1m0s"                             // Default value lap time
      }, 
      "attachment": {                                  // ATTACHMENTS
        "path": "C:/edi/outbound/attachments",         // Directory - productive outbound - Attachments
        "extensions": [                                // File name extension
          "pdf",                                       // Value of file name extension
          "step"                                       // Value of file name extension
        ],
        "waitTime": "15s"                              // Default value lap time - Attachments
      },
      "errorPath": "C:/edi/outbound/error",            // Directory - Error folder outbound
      "successPath": "C:/edi/outbound/success"         // Directory - Success folder outbound
    }
  }]
}

1.9.5 EDI connector controls

If you have EDI Connector 2.0 or higher installed, an EDI Connector directory will be created in the Microsoft Start menu.

There are two menu items here:

A. EDI Connector: This will restart the installer, which will then offer you the menu items described under Installation / Point 14.

B. Updater: This checks whether a more recent version of the EDI connector is available. If so, you will be offered the option to update.

Of course, the EDI connector can also be accessed and controlled in the list of Windows services.

In addition, the client can be run without an installer via the Windows command prompt (CMD).

1.9.6 Error handling

• If the EDI connector is not working properly, it may help to stop and restart the service. The service is called EDI Connector.

• If restarting the EDI connector does not result in proper operation, you can view the log files. The EDI connector writes its logs to the Windows event logs. These can be checked using the event viewer..

Right-click on the Windows icon and select “Event Viewer” from the menu. You can also open the program via the “Run” window. [Windows] + [R] : Here, enter the command “eventvwr.exe” and confirm with “OK”.

Event logs can be monitored automatically using Windows on-board tools or specialized software.

2 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.

3 Newsletter

Current participant list