Merge pull request #8 from Chemaclass/extend-docu

Added docu about EDIFACT and Service Segments Spec

README.md

@@ -15,9 +15,11 @@ Ok, but... [What is EDIFACT?](/docu/what-is-edifact.md)
 ## Format of an EDIFACT file
 
 * Each line of the file consists of a set of data that belongs to a specific segment of a message.
-* A segment is defined by its name (the first 3chars of the line), following up by the "sub-segment-key". 
-Following the rest of the data that belongs to that segment. See more about segments [here](/docu/segments.md).
+
+* A segment is defined by a tag. Following the rest of the data that belongs to that segment. More about segments [here](/docu/segments/README.md).
+
 * A message is a list of segments. Usually, all segments between the UNH and UNT segments compound a message.
+
 * A transaction is the list of messages that belongs to a file. 
 
 ## Installation as vendor

docu/README.md

@@ -0,0 +1,119 @@
+# EDIFACT
+
+* Segments in EDIFACT?
+* Service Segments Specification
+  * UNA (separators, delimiters...) 
+  * UNB (file header)
+  * UNG (group start)
+  * UNH (message header)
+  * UNT (message end)
+  * UNE (group end)
+  * UNZ (file end)
+
+## What is EDIFACT?
+
+The UN/EDIFACT Syntax Rules were approved in 1987 as the "ISO 9735" by the 
+International Organization for Standardization.
+
+`EDIFACT` stands for "Electronic Data Interchange For Administration, Commerce and Transport". 
+
+The `EDIFACT` standard provides:
+
+* a set of syntax rules to structure data
+* an interactive exchange protocol (I-EDI)
+* standard messages which allow multi-country and multi-industry exchange
+
+The `EDIFACT` standards cover transaction sets (the business documents that you wish to transmit), 
+data element directories and syntax rules which cover delimiter characters etc.
+
+* An `EDIFACT` electronic transmission consists of one or more Interchanges. 
+* Each Interchange may consist of one or more Messages. 
+* These Messages contain segments of data relating to the business transaction. 
+* At each level, a series of enveloping data pairs keep track of the exchange structure.
+
+## Service Segments
+
+All of these `EDIFACT` messages have the same basic structure, consisting of a sequence of segments:
+
+```
+UNA – separators, delimiters and special characters are defined for the interpreting software 
+UNB – file header (with the file end "UNZ" this makes up the envelope, containing basic information)
+UNG – group start
+UNH – message header
+UNT – message end
+UNE – group end
+UNZ – file end
+```
+
+You can also visualize these lines as something like:
+
+```
+ |_Service String Advice              UNA  Optional
+ |____Interchange Header              UNB  Mandatory
+ :    |___Functional Group Header     UNG  Conditional
+ :    :   |___Message Header          UNH  Mandatory
+ :    :   :   |__ User Data Segments          As required
+ :    :   |__ Message Trailer         UNT  Mandatory
+ :    |__ Functional Group Trailer    UNE  Conditional
+ |___ Interchange Trailer             UNZ  Mandatory
+```
+
+## Structure
+
+`EDIFACT` has a hierarchical structure where the **top level is referred to as an interchange**, 
+and **lower levels contain multiple messages which consist of [segments](segments/README.md)**, which in turn consist 
+of composites. The final iteration is an element which is derived from the United Nations Trade 
+Data Element Directory (UNTDED); these are normalised throughout the `EDIFACT` standard.
+
+### Examples
+
+* An EDIFACT EDI Purchase Order [(source)](https://www.edi-plus.com/resources/message-formats/edifact/)
+
+```
+UNB+UNOA:1+US::US+50138::THEM+140531:0305+001934++ORDERS'
+UNH+1+ORDERS:91:2:UN'
+BGM+220+A761902+4:20140530:102+9'
+RFF+CT:EUA01349'
+RFF+AAV::C'
+TXT+THIS IS WHAT AN EDI MESSAGE WOULD LOOK LIKE... '
+NAD+BY++OUR NAME PLC::::+++++EW4 34J'
+CTA+PD'
+COM+01752 253939:TE+01752 253939:FX+0:TL'
+CTA+OC+:A.SURNAME'
+COM+2407:EX'
+CTA+TI+:B.BROWN'
+COM+0:EX'
+CTA+SU'
+COM+0161 4297476:TE+01752 670633:FX'
+UNT+15+1'
+UNZ+1+001934'
+```
+
+* Used to answer a flight ticket (FRA-JFK-MIA) availability request [(source)](https://en.wikipedia.org/wiki/EDIFACT)
+
+```
+UNA:+.? '
+UNB+IATB:1+6XPPC:ZZ+LHPPC:ZZ+940101:0950+1'
+UNH+1+PAORES:93:1:IA'
+MSG+1:45'
+IFT+3+XYZCOMPANY AVAILABILITY'
+ERC+A7V:1:AMD'
+IFT+3+NO MORE FLIGHTS'
+ODI'
+TVL+240493:1000::1220+FRA+JFK+DL+400+C'
+PDI++C:3+Y::3+F::1'
+APD+74C:0:::6++++++6X'
+TVL+240493:1740::2030+JFK+MIA+DL+081+C'
+PDI++C:4'
+APD+EM2:0:1630::6+++++++DA'
+UNT+13+1'
+UNZ+1+1'
+```
+
+## References
+
+* [EDIFACT | Wikipedia](https://en.wikipedia.org/wiki/EDIFACT)
+* [Message formats | Edi-plus](https://www.edi-plus.com/resources/message-formats/edifact/)
+* [Edifile formats explained | ecosio](https://ecosio.com/en/blog/edi-file-formats-explained/)
+* [Structure of an Edifact file | unece](https://ecosio.com/en/blog/edi-standards-overview-structure-of-an-edifact-file/)
+* [Syntax Rules | unece](http://www.unece.org/fileadmin/DAM/trade/edifact/untdid/d422_s.htm)

docu/segments/README.md

@@ -0,0 +1,141 @@
+# Segments
+
+## EDIFACT Segment Definition
+
+EDIFACT Segment is a collection of logically-related data elements in a fixed, defined sequence. 
+
+### EDIFACT provides a hierarchical structure for messages
+
+EDIFACT messages begin with the `Message Header Segment` (UNH) and end with the` Message Trailer Segment` (UNT). 
+These two segments are the first, and innermost, level of the three levels of “electronic envelopes” within EDIFACT.
+
+EDIFACT Segment contains:
+
+* A **three-character alphanumeric** code that identifies the segment. This is called the segment tag.
+* Variable length data elements. These can be either simple or composite.
+
+Segments must be separated by a **data element separator/delimiter**, which is normally `+` and `:`, and 
+terminated by a segment terminator, normally `'`.
+
+Good to know: 
+
+> Each EDIFACT Segment is fully documented in the "United Nations Trade Data Interchange Directory" (UNTDID). 
+These tables list the segment position, segment tag and segment name. 
+EDIFACT Segment tables also specify if a segment must appear in a message using the requirements' designator
+`M` (Mandatory) or `C` (Conditional), and how many times a particular segment may repeat (repetition field).
+
+### There are two kinds of segments
+
+* [Service Segments](service-segments-spec.md)
+* Generic Segments
+
+#### Service Segments
+
+* Envelopes (`UNB`-`UNZ`, `UNG`-`UNE`, `UNH`-`UNT`)
+* Delimiter String Advice (`UNA`)
+* Section Separator (`UNS`)
+
+#### Generic Segments
+
+* `DOC` to identify and specify documents
+* `MOA` for monetary amounts
+* `DTM` for dates and times
+* `NAD` for name and address data
+* And others...
+
+#### EDIFACT Segment Terminators and Delimiters
+
+The end of each segment is determined by the Data Segment Terminator. 
+In EDIFACT the standard data segment terminator is `'`.
+
+---
+## Structure
+
+![Image of the EDIFACT structure](EDIFACT-structure.png)
+
+An interchange consists of:
+
+```
+            Service String Advice     UNA   Conditional
+     _____  Interchange Header        UNB   Mandatory
+    |  ___  Functional Group Header   UNG   Conditional
+    | |  _  Message Header            UNH   Mandatory
+    | | |   User Data Segments              As required
+    | | |_  Message Trailer           UNT   Mandatory
+    | |___  Functional Group Trailer  UNE   Conditional
+    |_____  Interchange Trailer       UNZ   Mandatory
+
+In addition to the above service segments, the service
+segment UNS can, when required, be used to divide a message
+into sections. See annex B.
+
+
+-----------------------------------------
+|Establishment |CONNECTION| Termination |  A CONNECTION contains one
+--------------------|--------------------  or more interchanges. The
+                    |                      technical protocols for
+                    |                      for establishment
+                    |                      maintenance and
+                    |                      termination etc.are not
++-------------------+-------------------+  part of this standard.
+|                                       |
+-----------------------------------------
+|Interchange |INTERCHANGE |Interchange  |  An INTERCHANGE contains:
+-------------------|---------------------  - UNA, Service string advice, if used
+                   |                       - UNB, Interchange header
+                   |                       - Either only Functional groups, 
+                   |                         if used, or only Messages
+                   |
+.....--------------+--------------------+  - UNZ, Interchange trailer
+.   |                                   |
+-----------------------------------------
+|UNA|UNB|'|    Either   |or only  |UNZ|'|  A FUNCTIONAL GROUP contains
+|   |   | |FUNCTION.GRPS|MESSAGES |   | |  - UNG, Functional group
+-----------------|----------.------------    header
+                 |          .              - Messages of the same
+                 |          .                type
++----------------+----------.-----------+  - UNE, Functional group
+|               +........+..+           |    trailer
+|               .        .              |
+-----------------------------------------
+|UNG |'|Message |MESSAGE |Message |UNE|'|  A MESSAGE contains:
+--------------------|--------------------  - UNH, Message header
+                    |                      - Data segments
++-------------------+-------------------+  - UNT, Message trailer
+|                                       |
+-----------------------------------------
+|UNH |'|Data    |DATA    |Data    |UNT|'|  A SEGMENT contains:
+|    | |segment |SEGMENT |segment |   | |  - A Segment TAG
+-------------------|---------------------  - Simple data elements or
+                   |                       - Composite data elements
++------------------+-------------------+     or both as applicable
+|                                      |
+----------------------------------------
+|TAG |+|SIMPLE       |+|COMPOSITE    |'|   A SEGMENT TAG contains:
+|    | |DATA ELEMENT | |DATA ELEMENT | |   - A segment code and,
+---|--------------|----------|-----|----     if explicit indication,
+   |              |          |     |         repeating and nesting
+   |              |          |     |         value(s). 
+   |              |          |     |
+   |              |          |     |       A SIMPLE DATA ELEMENT contains
+--------------   -------   -------------   - A single data element
+|Code|:|Value|   |Value|   |COMP|:|COMP|     value
+--------------   -------   |D/E | |D/E |   A COMPOSITE DATA ELEMENT
+                           |    | |    |   contains:
+                           --|------|---   - Component data elements
+                             |      |
+                         ------- -------   A COMPONENT DATA ELEMENT
+                         |     | |     |   contains:
+                         |Value| |Value|   - A single data element
+                         ------- -------     value
+
+  --.--                  --|--
+    . means alternative to |
+```
+
+## References
+
+* [Edifact | Wikipedia](https://en.wikipedia.org/wiki/EDIFACT)
+* [Edifact Segment | Ediacademy](https://ediacademy.com/blog/edifact-segment/)
+* [Structure of an Edifact file | ecosio](https://ecosio.com/en/blog/edi-standards-overview-structure-of-an-edifact-file/)
+* [Structures | unece](http://www.unece.org/fileadmin/DAM/trade/edifact/untdid/d422_s.htm#structures)

docu/segments/service-segments-spec.md

@@ -0,0 +1,56 @@
+# Service Segments Specifications
+
+[Segments in EDIFACT?](README.md)
+
+The full description of the data elements in the service
+segments is part of ISO 7372 Trade Data Elements Directory
+(UNTDED).
+
+* [UNA](una.md) (separators, delimiters...) 
+* [UNB](unb.md) (file header)
+* [UNG](ung.md) (group start)
+* [UNH](unh.md) (message header)
+* [UNT](unt.md) (message end)
+* [UNE](une.md) (group end)
+* [UNZ](unz.md) (file end)
+* [UNS](uns.md) (section control)
+* [TXT](txt.md) (additional info)
+
+Legend:
+
+```
+Ref.   The numeric reference tag for the data element as
+       stated in ISO 7372/UNTDED and, when preceded by S,
+       reference for a composite data element used in service
+       segments
+
+Name   Name of COMPOSITE DATA ELEMENT in capital letters
+       Name of DATA ELEMENT in capital letters
+       Name of Component data element in small letters
+
+Repr.  Data value representation:
+       a       alphabetic characters
+       n       numeric characters
+       an      alpha-numeric characters
+       a3      3 alphabetic characters, fixed length
+       n3      3 numeric characters, fixed length
+       an3     3 alpha-numeric characters, fixed length
+       a..3    up to 3 alphabetic characters
+       n..3    up to 3 numeric characters
+       an..3   up to 3 alpha-numeric characters
+
+       M       Mandatory element
+       C       Conditional element.
+
+       Note that a mandatory component data element in a
+       conditional composite data element must appear when the
+       composite data element is used
+
+
+Remarks IA    Interchange Agreement between interchanging
+              partners
+```
+
+## References
+
+* [Structures | unece](http://www.unece.org/fileadmin/DAM/trade/edifact/untdid/d422_s.htm#structures)