EDI

General description of EDI

• EDI (Electronic Data Interchange) is a set of electronic transfer methods and standardised data formats allowing data transfer between carriers and their customers as well as existing data management systems and Freecargo.
• EDI consists of formatted data files sent per email, http upload and other transfer methods EDI files can contain shipment data, distributed between partners in a supply chain. This can either be complete shipments or just status updates of earlier communicated shipments.
• Additionally, Freecargo can output formatted data and send it over the internet for onward processing.

Freecargo will accept and output data files formatted in a number of standard ways per default. This is described below in section Standard EDI formats.
Customized solutions can be provided on request, the procedure is described below in section Special EDI formats.

Standard EDI formats

Standard EDI is limited to:

• Communication through email and http upload
• The use of standardized data formats (csv, xml, xls)

Anything outside these limitations automatically results in a 'Special EDI format' described below under 'Special EDI formats'.

The CSV format (Comma Separated Values)

Although CSV formatted files can be written by most spreadsheet and database programs, there is no general standard for the format. The Freecargo CSV parser can handle files as described below.

• The file is a normal ascii encoded file.
• Lines are terminated by a newline character.
• Fields within a line are separated by commas ',' or semicolons ';' and (optionally) delimited by double(") or single (') quotes. The same separator must be used throughout the whole file.
• If quotes are part of the data itself, they must be escaped by a second quote and the whole field element must be quoted.
• The fist line ('header line') must contain the field names. This line describes the layout of the following data lines.
  Alternatively, the layout of files without a header line can be stored in cargooffice->orderentry->settings->edilayout. This parameter must contain 1 fieldname per line terminated by a separator character. It must be set specifically for each customerID. CSV files without a headerline must be named: NOHEAD.csv in order to be processed correctly.
• There is no particular order for the fields within a line, as long as the data in each line corresponds to the field names given in the header line.
• Csv files must contain a customerID field in order to be processed
• Records containing a shipmentID or orderID will update existing records if they can be found or create new records.
• Records without a shipmentID or orderID will always create new records with a unique (system-generated) shipmentID.

Freecargo differentiates between two sections within a record:

• 1. Order section
• 2. Shipment section
• 3. Goods section

An order can contain shipments and a shipment can contain several goods lines. For a data line in a csv file to be interpreted as a 'goods line' a number of conditions must be met:

• goods lines must directly follow order lines or other goods lines belonging to the same order.
• in a goods line all order fields must either be empty or contain exactly the same value as the order line it belongs to.

Note:

• In a csv file, all fields that are not defined as belonging to a goods line will be interpreted as order fields.
• Separate shipments lines are not yet implemented for csv format uploads.

A list of fieldnames and their properties can be found at TransportorderFields.

The general idea of EDI is to send as little information as possible and send only those fields which are absolutely necessary for the job. For sending shipment information it is a good idea to look at the order entry form of the party you are sending information to, this usually gives a good idea of what the other party needs to know.

A CSV example can be found here: http://www.loginet.nl/XML/layoutStd.csv

The XML EDI format

The separation of order, shipment and goods details is much easier this format. XML tends to be self explanatory:

<transportOrder> contains one or more
    <shipments> containing one or more
       <goodsLines>

Please consult the data definition sheet at http://www.loginet.nl/XML/xmlEdi.dtd and the example file at http://www.loginet.nl/XML/transportOrderXMLv21.xml

Data layout in Excel spreadsheets

Although Excel is deprecated as a format because it is proprietary to Microsoft and somewhat unpredictable, Freecargo's EDI interface will parse Excel spreadsheets. The data layout is is comparable to the one in csv files as described above:

• The first row will contain field definitions, an empty cell is considered a terminator for this header row.
• All following rows will contain the corresponding data.
• example can be found here: http://www.loginet.nl/XML/layoutStd.xls

Note:

• To avoid mentioned compatibility problems it is advisable to export such a spreadsheet as CSV file (a standard Excel function) and send that rather than the Excel spreadsheet itself.
• Please note that the XLS parser is provided 'as is' and no additional support will be given to the handling of Excel spreadsheets.
• For detailed information on the content see the description of "CSV example" above.

Data transfer methods:

Email:

• Transport order information can be sent per email to Freecargo and will be processed automatically. Data files must be added as MIME encoded attachments. The extension of the attached data files must indicate their format (.csv , .xml , .xls).
• Mail must be sent to stdedi@.cargooffice.com .
  For instance mail sent to stdedi@virtex.cargooffice.com will be processed as transport orders for carrier Virtex.
• Processed orders will be visible through the track & trace website. In case a parse error occurs, an error message will be mailed back to the originating mail address along with the file sent.
• Note that it can take a few minutes before orders are processed and appear on the webpage.

Http uploads:

• Files as mentioned above can be uploaded via the cargoOffice website. Clicking 'Overview of Batch Orders' in the frontoffice will spawn an extra window displaying orders entered as a batch. On top of the page there is a form element, allowing to upload files to CargoOffice.
• Orders from the uploaded files will per default be stored as batch orders (status 'batchentry') and appear in the list below the upload form directly after. Orders can than be edited and set to 'sent' for further processing.

FTP uploads:

• For FTP-upload, please contact us by sending us a request (see BugtrackingDocumentation).

Special EDI formats

It is important to understand that every 'Special EDI format' is a tailor made solution.
It is not standard software and not part of the Freecargo software. Special directories are created, containing special files, special programs and special scripts for exclusive use by that particular Carrier or that particular customer of that particular Carrier.

EDI solutions might look simple from the outside but they usually aren't.
Reading an Excel file for example is indeed very simple, yet the content of the file might be TIR (totally incompatible rubbish). And very often it is rubbish, or it will be rubbish sooner or later as people tend to become less disciplined in providing accurate data in these files.

There is no such thing as a simple EDI solution.

The 'Special Edi formats' program needs the involvement of a consultant who supervises the project and initiates the various steps of the project:

• 1. brief investigation
• 2. assessment and decision making
• 3. detailed report and cost estimation
• 4. development
• 5. test
• 6. acceptance and implementation

Detailed report
This report addresses the following issues:

• 1. An overview of the system (parties involved, general flow of data between parties)
• 2. Communication capabilities of the parties (type of connection, protocols, required equipment)
• 3. Files, file-formats (ascii, xls, csv, xml) and file layout (record types, etc.)
• 4. Field contents and field analysis (length, type, format, precision)
• 5. A mapping of fields to the shipment entry form found in the Carriers cargoOffice
• 6. An estimate on the number of files and the total number of bytes per day
• 7. Required level of security (authentication, encryption etc.)
• 8. Required feedback (logging, notifications, warnings, error reports)
• 9. Assignment of a contact person at the Carrier's office for first line support to customers.

Mapping
An important part of EDI is mapping. The picture below shows a standard order entry form together with their fieldnames.

• Start your mapping from this screen, check correct namegiving in TransportorderFields.
• If you use other fields, check them with the fieldnames in TransportorderFields.
• A mapping document like this is absolutely necessary to successfully complete an EDI project.

 

 

 

-- KarlGorz - 08 Nov 2005