edi-parser-cg-lib (EDI Parser lib)

1. Introduction

The purpose of this library is to analyze, generate and map ASC X12 EID files, the library used is node-x12, it is important mention that this library is only for Nodejs.

2. Library Objects and Methods

The library can be installed from npm page with some of the following commands:

npm install edi-parser-cg-lib, npm i edi-parser-cg-lib or yarn install edi-parser-cg-lib

* ### 2.1. Methods

The following methods are available in the library:

processEdiToJSON: This method will convert the content of an EDI file to a JSON format
>The JSON output format will come out with the JSEDINotation format, for more information about this output the next URL can be reviewed here.

>Before returning the response, the method will validate that the output JSON is a correct JSON, if it is correct the flow will continue the method will return the result otherwise the method will send an exception and the flow will stop.

processJSToEDI: This method transforms a JSON object into JSEDINotation format and from this information creates valid content for an "__.edi__" file.
>Before executing the conversion, the method checks that the content property contains a valid JSON (remember that the content property can come in any valid encoding, already described above), if content does not have a valid JSON object, it will throw an exception and the flow will stop. stop, otherwise the process will continue.

processMapToJSON: This method expects to receive a JSON object and the output of this method will be the same object received.
>Before executing the conversion, the method checks that the mapping property contains a valid JSON, if mapping does not have a valid JSON object, it will throw an exception and the flow will stop. stop, otherwise the process will continue.

>Before returning the response, the method will validate that the output JSON is a correct JSON, if it is correct the flow will continue the method will return the result otherwise the method will send an exception and the flow will stop.


>All three methods are asynchronous, then use async/await


* ### 2.2. Objects and properties

These are the following objects and properties available in the library

* ### 2.2.1 Objects

objectEdiToJson*: it only has the content property, this object is used all methods.
objectJsonToEdi*: contains the functionalGroups and header properties, this object is used in the processJSToEDI method
objectMapToJson*: it has the content and mapping properties, this object is used in the processMapToJSON method
optProps*: contains the properties segmentTerminator, subElementDelimiter elementDelimiter and endOfLine, this object contains optional properties that may or may not be sent, it is used in the processEdiToJSON and processJSToEDI methods

* ### 2.2.2 Properties

`js
{
content: null
}
`
The content property should have the information of the EDI file, it can come with some of the following encoding:
- ascii, base64, base64url, binary, latin1, utf-8, utf8.

> This property is required and is used in the all transformations

`json
{
"elementDelimiter": "*",
"endOfLine": "\n",
"format": true,
"segmentTerminator": "~",
"subElementDelimiter": ">"
}
`
These are optional properties used in the processEdiToJSON and processJSToEDI methods.

The elementDelimiter property indicates the symbol that separates or will separate the values of each element in the EDI document, by default the value is .
* The endOfLine property indicates the symbol to separate each segment, by default it is a line break \n.
* The format property indicates if the EDI content is formatted or not, by default is true.
* The segmentTerminator property indicates the symbol to delimit each segment, by default it is the ~ symbol.
* The subElementDelimiter property indicates the symbol to delimit sub-elements, by default it is the > symbol.

_3. Examples_

For the three methods the data should be obtained by the following way.

- Arguments:
1. The first argument is the message (msg) that will come from the EDI component, the property contains the data to be processed (the EDI file or JSON file according with the type of transformation required).
2. The second parameter is the configuration (cfg) that will also come from the EDI component.
3. The third argument is only to know if the library is going to be used in test mode, by default it is false. If it is required to test the methods of this library to be used out of a component this flag must be in true.

### 3.1. processEdiToJSON

- Description: This method will convert the content of an EDI file to a JSON output, remember that the JSON output format is a custom format called JavaScript EDI Notation, for more information about this format click here
- Object and Properties: To use this method, the use of the object called objectEdiToJson is mandatory and, if required, the optProps object to send and replace the default values.

- Example

In this first example is configured the information using the objectEdiToJson and optProps objects.

>If the EDI file is not formatted, the property format must be set in false.

`javascript
let properties = {
...objectEdiToJson
};
properties.content = fs.readFileSync(path.join(__dirname, 'Sample_850_01.edi'), {
encoding: 'binary'
});
let optsP = {
...optProps
};
optsP.elementDelimiter = '/';
properties = {
...properties,
...optsP
};
const _data = await processJSToEDI({
data: properties
}, {}, true);
console.log(_data);
`
In this second example it is set the information without using the objects described above, that only uses the properties:
`js
let properties = {
elementDelimiter: '/',
endOfLine: '\n',
};
properties.content = fs.readFileSync(tempFilePath, {
encoding: 'base64'
});
const _data = await processEdiToJSON({
data: properties
}, {}, true);
console.log(_data)
`

Result:
In both examples (the first and second) the result will be the same:

`json
{
"header":[
"01",
"0000000000",
"01",
"0000000000",
"ZZ",
"ABCDEFGHIJKLMNO",
"ZZ",
"123456789012345",
"101127",
"1719",
"U",
"00400",
"3438",
"0",
"P",
">"
],
"options":{
"elementDelimiter":"/",
"endOfLine":"\n",
"format":false,
"segmentTerminator":"~",
"subElementDelimiter":">",
"repetitionDelimiter":"^",
"segmentHeaders":[
{
"tag":"GS",
"trailer":"GE",
"layout":{
"GS01":2,
"GS02":15,
"GS02_MIN":2,
"GS03":15,
"GS03_MIN":2,
"GS04":8,
"GS05":8,
"GS05_MIN":4,
"GS06":9,
"GS06_MIN":1,
"GS07":2,
"GS07_MIN":1,
"GS08":12,
"GS08_MIN":1,
"COUNT":8,
"PADDING":false
}
},
{
"tag":"ISA",
"trailer":"IEA",
"layout":{
"ISA01":2,
"ISA02":10,
"ISA03":2,
"ISA04":10,
"ISA05":2,
"ISA06":15,
"ISA07":2,
"ISA08":15,
"ISA09":6,
"ISA10":4,
"ISA11":1,
"ISA12":5,
"ISA13":9,
"ISA14":1,
"ISA15":1,
"ISA16":1,
"COUNT":16,
"PADDING":true
}
},
{
"tag":"ST",
"trailer":"SE",
"layout":{
"ST01":3,
"ST02":9,
"ST02_MIN":4,
"ST03":35,
"ST03_MIN":1,
"COUNT":3,
"COUNT_MIN":2,
"PADDING":false
}
}
],
"txEngine":"internal"
},
"functionalGroups":[
{
"header":[
"PO",
"4405197800",
"999999999",
"20101127",
"1719",
"1421",
"X",
"004010VICS"
],
"transactions":[
{
"header":[
"810",
"0001"
],
"segments":[
{
"tag":"BIG",
"elements":[
"20000513",
"SG427254",
"20000506",
"508517",
"1001"
]
},
{
"tag":"N1",
"elements":[
"ST",
"ABC AEROSPACE CORPORATION",
"9",
"123456789-0101"
]
},
{
"tag":"N3",
"elements":[
"1000 BOARDWALK DRIVE"
]
},
{
"tag":"N4",
"elements":[
"SOMEWHERE",
"CA",
"98898"
]
},
{
"tag":"ITD",
"elements":[
"05",
"3",
"",
"",
"",
"",
"30",
"",
"",
"",
"",
"",
"",
"E"
]
},
{
"tag":"IT1",
"elements":[
"1",
"48",
"EA",
"1",
"",
"MG",
"R5656-2"
]
},
{
"tag":"TDS",
"elements":[
"14400"
]
},
{
"tag":"CTT",
"elements":[
"1"
]
}
]
}
]
}
]
}
`

### 3.2. processJSToEDI

- Description: This method will convert a formatted JSON in JSEDINotation to the content of an EDI file.
- Object and Properties: To use this method, the object called objectJsonToEdi must be used.
>Remember that this JSON must go in the content property
- Notes:
* The JSEDINotation format uses a property called options that is not mandatory, but if required the optional properties can be set in the optProps object.
* Also, the "options" property also uses the repetitionDelimiter, segmentHeaders and txEngine properties, but these are not mandatory.
* Lastly, the functionalGroups property of the objectJsonToEdi object uses contains required properties, so it is recommended to read the documentation for the JSEDINotation.

- Example

>If the EDI file output is not required to have format, the format property should be in false.

The value of input will be:

`json
{
"header": [
"01",
"0000000000",
"01",
"0000000000",
"ZZ",
"ABCDEFGHIJKLMNO",
"ZZ",
"123456789012345",
"101127",
"1719",
"U",
"00400",
"3438",
"0",
"P",
">"
],
"options": {
"elementDelimiter": "/",
"endOfLine": "\n"
},
"functionalGroups": [
{
"header": [
"PO",
"4405197800",
"999999999",
"20101127",
"1719",
"1421",
"X",
"004010VICS"
],
"transactions": [
{
"header": [
"277",
"0003",
"005010X364"
],
"segments": [
{
"tag": "BHT",
"elements": [
"0085",
"08",
"0000221",
"20190221",
"1025"
]
},
{
"tag": "HL",
"elements": [
"1",
"",
"20",
"1"
]
},
{
"tag": "NM1",
"elements": [
"ACV",
"2",
"ALL PAYER CLAIMS DATABASE",
"",
"",
"",
"",
"46",
"APCD01"
]
},
{
"tag": "TRN",
"elements": [
"1",
"ABC12345"
]
},
{
"tag": "DTP",
"elements": [
"050",
"D8",
"20190220"
]
},
{
"tag": "DTP",
"elements": [
"009",
"D8",
"20190221"
]
},
{
"tag": "HL",
"elements": [
"2",
"1",
"21",
"1"
]
},
{
"tag": "NM1",
"elements": [
"40",
"2",
"YOUR INSURANCE COMPANY",
"",
"",
"",
"",
"46",
"S00003"
]
},
{
"tag": "TRN",
"elements": [
"2",
"206438976580901"
]
},
{
"tag": "STC",
"elements": [
"DR02:20",
"20190221",
"WQ",
"365.5"
]
},
{
"tag": "QTY",
"elements": [
"90",
"3"
]
},
{
"tag": "QTY",
"elements": [
"AA",
"2"
]
},
{
"tag": "AMT",
"elements": [
"YU",
"200.5"
]
},
{
"tag": "AMT",
"elements": [
"YY",
"165"
]
},
{
"tag": "HL",
"elements": [
"3",
"2",
"19",
"1"
]
},
{
"tag": "NM1",
"elements": [
"85",
"1",
"JONES",
"HARRY",
"B",
"",
"MD",
"XX",
"1546326897"
]
},
{
"tag": "HL",
"elements": [
"4",
"3",
"PT"
]
},
{
"tag": "NM1",
"elements": [
"QC",
"1",
"PATIENT",
"FEMALE",
"",
"",
"",
"MI",
"2222222222"
]
},
{
"tag": "TRN",
"elements": [
"2",
"PATIENT22222"
]
},
{
"tag": "STC",
"elements": [
"DR02:20:PR",
"20190221",
"WQ",
"100"
]
},
{
"tag": "REF",
"elements": [
"F8",
"IC847502"
]
},
{
"tag": "REF",
"elements": [
"1K",
"220216359803X"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190214"
]
},
{
"tag": "HL",
"elements": [
"5",
"3",
"PT"
]
},
{
"tag": "NM1",
"elements": [
"QC",
"1",
"PATIENT",
"MALE",
"",
"",
"",
"MI",
"3333333333"
]
},
{
"tag": "TRN",
"elements": [
"2",
"PATIENT33333"
]
},
{
"tag": "STC",
"elements": [
"DR06:21",
"20190221",
"U",
"65",
"",
"",
"",
"",
"",
"DR06:255"
]
},
{
"tag": "REF",
"elements": [
"F8",
"IC429783"
]
},
{
"tag": "REF",
"elements": [
"1K",
"220216359954X"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190121"
]
},
{
"tag": "HL",
"elements": [
"6",
"3",
"PT"
]
},
{
"tag": "NM1",
"elements": [
"QC",
"1",
"JONES",
"LARRY",
"",
"",
"",
"MI",
"4444444444"
]
},
{
"tag": "TRN",
"elements": [
"2",
"JONES44444"
]
},
{
"tag": "STC",
"elements": [
"DR03:26:77",
"20190221",
"U",
"100"
]
},
{
"tag": "REF",
"elements": [
"F8",
"IC429805"
]
},
{
"tag": "REF",
"elements": [
"1K",
"220216359964X"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190211"
]
},
{
"tag": "HL",
"elements": [
"7",
"2",
"19",
"1"
]
},
{
"tag": "NM1",
"elements": [
"85",
"1",
"SMITH",
"JOHN",
"C",
"",
"MD",
"XX",
"1546326780"
]
},
{
"tag": "TRN",
"elements": [
"1",
"0"
]
},
{
"tag": "REF",
"elements": [
"LU",
"AB142"
]
},
{
"tag": "QTY",
"elements": [
"QA",
"2"
]
},
{
"tag": "AMT",
"elements": [
"YU",
"100.5"
]
},
{
"tag": "HL",
"elements": [
"8",
"7",
"PT"
]
},
{
"tag": "NM1",
"elements": [
"QC",
"1",
"JOHNSON",
"MARY",
"",
"",
"",
"MI",
"5555555555"
]
},
{
"tag": "TRN",
"elements": [
"2",
"JOHNSON55555"
]
},
{
"tag": "STC",
"elements": [
"DR08:20:PR",
"20190221",
"EZ",
"50.5"
]
},
{
"tag": "REF",
"elements": [
"F8",
"IC429888"
]
},
{
"tag": "REF",
"elements": [
"1K",
"220216359806X"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190210"
]
},
{
"tag": "SVC",
"elements": [
"HC:G9938",
"50.5",
"",
"",
"",
"",
"1"
]
},
{
"tag": "STC",
"elements": [
"DR08:475",
"",
"EZ"
]
},
{
"tag": "REF",
"elements": [
"6R",
"1"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190210"
]
},
{
"tag": "HL",
"elements": [
"9",
"7",
"PT"
]
},
{
"tag": "NM1",
"elements": [
"QC",
"1",
"MILLS",
"HARRIETT",
"",
"",
"",
"MI",
"6666666666"
]
},
{
"tag": "TRN",
"elements": [
"2",
"MILLS66666"
]
},
{
"tag": "STC",
"elements": [
"DR02:20:PR",
"20190221",
"WQ",
"50"
]
},
{
"tag": "REF",
"elements": [
"F8",
"IC429956"
]
},
{
"tag": "REF",
"elements": [
"1K",
"220216359807X"
]
},
{
"tag": "DTP",
"elements": [
"472",
"D8",
"20190205"
]
}
]
}
]
}
]
}
`

This example uses the object objectJsonToEdi
`javascript
let properties = {
...objectJsonToEdi
};
properties.header = data.header;
properties.functionalGroups = data.functionalGroups;
const _data = await processJSToEDI({
data: properties
}, data);
console.log(_data);
`
In this second example the information is configured without the object described above, the properties used are:
`javascript
let properties = {
options:{
elementDelimiter: '/',
endOfLine: '\n'
};
properties.headers = data.headers;
properties.functionalGroups = data.functionalGroups;
};
const _data = await processEdiToJSON({
data: properties
}, {}, true);
console.log(_data)
`

Result:

`plaintext
ISA/01/0000000000/01/0000000000/ZZ/ABCDEFGHIJKLMNO/ZZ/123456789012345/101127/1719/U/00400/000003438/0/P/>~
GS/PO/4405197800/999999999/20101127/1719/1421/X/004010VICS~
ST/277/0003/005010X364~
BHT/0085/08/0000221/20190221/1025~
HL/1//20/1~
NM1/ACV/2/ALL PAYER CLAIMS DATABASE/////46/APCD01~
TRN/1/ABC12345~
DTP/050/D8/20190220~
DTP/009/D8/20190221~
HL/2/1/21/1~
NM1/40/2/YOUR INSURANCE COMPANY/////46/S00003~
TRN/2/206438976580901~
STC/DR02:20/20190221/WQ/365.5~
QTY/90/3~
QTY/AA/2~
AMT/YU/200.5~
AMT/YY/165~
HL/3/2/19/1~
NM1/85/1/JONES/HARRY/B//MD/XX/1546326897~
HL/4/3/PT~
NM1/QC/1/PATIENT/FEMALE////MI/2222222222~
TRN/2/PATIENT22222~
STC/DR02:20:PR/20190221/WQ/100~
REF/F8/IC847502~
REF/1K/220216359803X~
DTP/472/D8/20190214~
HL/5/3/PT~
NM1/QC/1/PATIENT/MALE////MI/3333333333~
TRN/2/PATIENT33333~
STC/DR06:21/20190221/U/65//////DR06:255~
REF/F8/IC429783~
REF/1K/220216359954X~
DTP/472/D8/20190121~
HL/6/3/PT~
NM1/QC/1/JONES/LARRY////MI/4444444444~
TRN/2/JONES44444~
STC/DR03:26:77/20190221/U/100~
REF/F8/IC429805~
REF/1K/220216359964X~
DTP/472/D8/20190211~
HL/7/2/19/1~
NM1/85/1/SMITH/JOHN/C//MD/XX/1546326780~
TRN/1/0~
REF/LU/AB142~
QTY/QA/2~
AMT/YU/100.5~
HL/8/7/PT~
NM1/QC/1/JOHNSON/MARY////MI/5555555555~
TRN/2/JOHNSON55555~
STC/DR08:20:PR/20190221/EZ/50.5~
REF/F8/IC429888~
REF/1K/220216359806X~
DTP/472/D8/20190210~
SVC/HC:G9938/50.5/////1~
STC/DR08:475//EZ~
REF/6R/1~
DTP/472/D8/20190210~
HL/9/7/PT~
NM1/QC/1/MILLS/HARRIETT////MI/6666666666~
TRN/2/MILLS66666~
STC/DR02:20:PR/20190221/WQ/50~
REF/F8/IC429956~
REF/1K/220216359807X~
DTP/472/D8/20190205~
SE/63/0003~
GE/1/1421~
IEA/1/000003438~
`

>__Note__: In this example / is used to indicate the separator of each element, however this symbol is replacing the default delimiter character *.

$3

- Description: This method will receive a JSON object as input, where the value of each property should be in a format of QUERY LANGUAGE, these QUERY LANGUAGE values will be used to take the information from the content of the EDI file, therefore the result of this method will be the same input JSON mapping but each property will have the value according to its QUERY defined.
- Object and Properties: To use this method, we must use the object called objectMapToJson, in the mapping property the JSON should be placed and in the content property should be the EDI file to process.

- Example

This is an input sample of the JSON object:

`json
{
"PONumber": "BEG03",
"PODate": "BEG05",
"POType": "BEG02",
"ISAControlNum": "ISA13",
"GSControlNum": "FOREACH(GS)=>GS06",
"BuyerName": "PER:PER02",
"BuyerTelephone": "PER:PER04",
"BuyerEmail": "PER:PER06",
"ShipTo": "N102['ST']",
"Warehouse": "N104['ST']",
"Total": "AMT02",
"TotalPP": "CTT01",
"LineItem": {
"Quantity": "FOREACH(PO1)=>PO102",
"Price": "FOREACH(PO1)=>PO104",
"PriceBasis": "FOREACH(PO1)=>PO105",
"ProductCode": "FOREACH(PO1)=>PO107",
"ProductDescr": "FOREACH(PID)=>PID05",
"RequiredDate": "DTM02"
}
}
`

This is the content of the EDI file

`plaintext
ISA010000000000010000000000ZZABCDEFGHIJKLMNOZZ1234567890123451011271719U004000000034380P>~
GSPO44051978009999999992010112717191421X004010~
ST850000000010~
BEG00SA0829223329420101127610385385~
REFDP038~
REFPSR~
PERAMNAME EXAMPLECP1-212-324-4152EMmail@mail.com~
ITD143*24546~
DTM00220101214~
PKGF68*PALLETIZE SHIPMENT~
PKGF66*REGULAR~
TD5A92P3*SEE XYZ RETAIL ROUTING GUIDE~
N1STXYZ RETAIL90003947268292~
N3*31875 SOLON RD~
N4SOLONOH*44139~
PO11120EA9.25TECB065322-117PRROVN*AB3542~
PIDF*SMALL WIDGET~
PO444EAPLT94*3LR15CT~
PO12220EA13.79TECB066850-116PRROVN*RD5322~
PIDF*MEDIUM WIDGET~
PO422*EA~
PO13126EA10.99TECB060733-110PRROVN*XY5266~
PIDF*LARGE WIDGET~
PO461EAPLT94*3LR12CT~
PO1476EA4.35TECB065308-116PRROVN*VX2332~
PIDF*NANO WIDGET~
PO444EAPLT94*6LR19CT~
PO1572EA7.5TECB065374-118PRROVN*RV0524~
PIDF*BLUE WIDGET~
PO444*EA~
PO16696EA9.55TECB067504-118PRROVN*DX1875~
PIDF*ORANGE WIDGET~
PO466EAPLT94*3LR10CT~
CTT*6~
AMT113045.94~
SE33000000010~
GE11421~
IEA1000003438~
`

The next is an example of the objectMapToJson object used in the mapping property where the JSON is placed and in the content file should be the content of the EDI file to be processed.

`javascript
let properties = {
...objectMapToJson
};
properties.mapping = data;
properties.content = fs.readFileSync(path.join(__dirname, 'Sample_850_01.edi'), {
encoding: 'binary'
});

const _data = await processMapToJSON({
data: properties
}, {}, true);
console.log(_data);
`
In this second example is set the information without using the object described above, only using the properties as follows:
`js
let properties = {
mapping: data,
content: fs.readFileSync(path.join(__dirname, 'Sample_850_01.edi'), {
encoding: 'base64'
}),
};

const _data = await processMapToJSON({
data: properties
}, {}, true);
console.log(_data)
`

Result:

`json
{
"PONumber": "08292233294",
"PODate": "20101127",
"POType": "SA",
"ISAControlNum": "000000000",
"GSControlNum": [
"1421"
],
"BuyerName": "NAME EXAMPLE",
"BuyerTelephone": "1-212-324-4152",
"BuyerEmail": "mail@mail.com",
"ShipTo": "XYZ RETAIL",
"Warehouse": "0003947268292",
"Total": "13045.94",
"TotalPP": "6",
"LineItem": [
{
"Quantity": "120",
"Price": "9.25",
"PriceBasis": "TE",
"ProductCode": "065322-117",
"ProductDescr": "SMALL WIDGET",
"RequiredDate": "20101214"
},
{
"Quantity": "220",
"Price": "13.79",
"PriceBasis": "TE",
"ProductCode": "066850-116",
"ProductDescr": "MEDIUM WIDGET",
"RequiredDate": "20101214"
},
{
"Quantity": "126",
"Price": "10.99",
"PriceBasis": "TE",
"ProductCode": "060733-110",
"ProductDescr": "LARGE WIDGET",
"RequiredDate": "20101214"
},
{
"Quantity": "76",
"Price": "4.35",
"PriceBasis": "TE",
"ProductCode": "065308-116",
"ProductDescr": "NANO WIDGET",
"RequiredDate": "20101214"
},
{
"Quantity": "72",
"Price": "7.5",
"PriceBasis": "TE",
"ProductCode": "065374-118",
"ProductDescr": "BLUE WIDGET",
"RequiredDate": "20101214"
},
{
"Quantity": "696",
"Price": "9.55",
"PriceBasis": "TE",
"ProductCode": "067504-118",
"ProductDescr": "ORANGE WIDGET",
"RequiredDate": "20101214"
}
]
}
`
> The resultant EDI file can be validated in this page

> If an error occur, the result will show one of the following messages:

`plaintext
Batch size exceeds the limit,
Error executing query,
Error missing property,
Error with the property
``