EDI to JSON or XML conversion with EDI Generator | Aayu Technologies
Home Blog EDI to JSON or XML conversion with EDI Generator

EDI to JSON or XML conversion with EDI Generator

EDI is a cryptic format which is difficult to decipher and process. But EDI Generator can assist you to convert them to simpler formats such as JSON or XML.

17 Jul 2023 by Udith Gunaratna

EDI (Electronic Data Interchange) is a widely used standard across many domains such as retail, logistics, pharmaceuticals, etc. for exchanging business-to-business data. Some of the large organizations such as Walmart have even mandated EDI as the preferred data interchange format for their suppliers and logistic partners.

But one of the pain points when working with EDIs is that it is very hard to understand the data or the structural semantics of an EDI by just looking at it alone. To correctly understand those, it is required to refer to a separate document which is generally called the “EDI Specification” corresponding to that EDI type, which defines the EDI’s data structure and the details/definitions of the included data segments and elements. Similarly, when composing an EDI to be sent out, again the “EDI Specification” document should be referred to in order to include the data within the correct loops, segments, and elements so that the receiving party could process them correctly.

If you are a small business that receives and sends a handful of EDIs per month, you may be able to somehow manage this manually, although it is still a very time-consuming and exhausting task. But if you are a large business using CRM software and other automated processes in place, integrating EDIs with those systems can be a nightmare. But if there is a way for you to convert these EDIs you receive into a simpler format such as JSON or XML, they will be much easier to integrate with your systems. Similarly, if there is a way to convert the JSON or XML files generated by your systems to the corresponding EDIs and sent to your EDI partners, that would also make your life easier.

How EDI Generator can help?

EDI Generator is a revolutionary new product we introduced a couple of years ago initially to help small to medium-scale businesses to become EDI-ready within a short time. The earlier versions of the EDI Generator only provided UI-based EDI features, where you can view the received EDIs in user-friendly formats and also compose EDIs easily through a form-based UI, after which you can validate them and send them out to the partners.

But the EDI Generator has evolved since, so it now has the capability to automatically convert the receiving EDIs to a pre-decided JSON or XML format and submit them to systems running in your organization. Also, EDI Generator can accept a pre-decided JSON or XML format from your systems, generate the corresponding EDI, and send them to the relevant partner as a fully automated process.

This is usually done by the EDI Generator team deploying a custom adapter application between your EDI Generator account and your own systems. The main responsibility of this application is to convert between the internal JSON format used by EDI Generator and the customized JSON or XML format expected/supported by your systems. Since an independent adapter application is deployed for each organization that requires this functionality, it can be easily customized to match the exact requirements of your existing systems and processes. Also, the usage of serverless functions for this application brings additional benefits to the table such as high scalability, no single point of failure, and also cost efficiency.

Incoming EDIs

Incoming EDI Processing Flow Open image on lightbox

The processing flow of an incoming EDI can be summarized as follows.

  1. MFT Gateway internally routes the EDI file it received over AS2 to EDI Generator.
  2. EDI Generator processes the EDI, generates the corresponding JSON (in EDI Generator’s internal JSON format) and forwards that JSON to the custom function.
  3. The custom function converts the received JSON to the JSON/XML format expected from the client system and dispatches it to an HTTP/S endpoint on the client system.
Client system endpoint

The client system endpoint in step 3 must be a publicly accessible HTTP/S endpoint which accepts a JSON or XML payload depending on the expected format. In case of successful acceptance, the endpoint is expected to return a 2XX response status. Also, it is highly recommended to have some form of authentication enabled for the endpoint to prevent malicious requests from external parties. The custom function can implement any authentication mechanism preferred ranging from basic authentication to more complex ones such as Netsuite token-based authentication.

Dispatch status and failure handling

In case of dispatch failure, EDI Generator automatically retries the dispatch up to 3 times. The final dispatch status will be shown on the Inbox view of the EDI Generator, and it is possible to manually re-dispatch any EDI, irrespective of whether it was already successfully dispatched or not. Also, you can enable email, SMS, or Slack notifications for dispatch failures, so that you will be alerted when an EDI could not be dispatched even after exhausting all automatic retry attempts.

Inbox Dispatch Status Open image on lightbox

Customized JSON

The following is a sample of a customized JSON corresponding to an 850 EDI (Purchase order) which will be sent to the client system after the conversion. This format can be customized to cater the exact requirements of the client.

{
    "Header": {
        "OrderHeader": {
            "TransactionPurposeCode": "00",
            "PurchaseOrderType": "SA",
            "PurchaseOrderNumber": "312312414",
            "PurchaseOrderDate": "2023-06-24"
        },
        "Contacts": [
            {
                "ContactFunctionCode": "IC",
                "Name": "john.doe@acme.com"
            }
        ],
        "Address": [
            {
                "AddressTypeCode": "ST",
                "Name": "Buy More Inc.",
                "IDCodeQualifier": "92",
                "IDCode": "22234223",
                "Address1": "123",
                "City": "Burbank",
                "State": "CA",
                "PostalCode": "424224",
                "Country": "US"
            },
            {
                "AddressTypeCode": "SF",
                "Name": "Future Electronics",
                "IDCodeQualifier": "92",
                "IDCode": "23424",
                "Address1": "5644 OLD DOBBIN LANE",
                "City": "COLUMBIA",
                "State": "MD",
                "PostalCode": "21045",
                "Country": "US"
            }
        ]
    },
    "Structure": {
        "LineItem": [
            {
                "OrderLine": {
                    "LineNumber": "1",
                    "OrderQty": 30,
                    "OrderQtyUOM": "EA",
                    "UnitPrice": 200,
                    "VendorPartNumber": "476001000",
                    "BuyerPartNumber": "100020840",
                    "ManufacturerPartNumber": "476001000"
                },
                "ProductOrItemDescription": {
                    "ProductDescription": "43-inch LED TV"
                }
            },
            {
                "OrderLine": {
                    "LineNumber": "2",
                    "OrderQty": 50,
                    "OrderQtyUOM": "EA",
                    "UnitPrice": 150,
                    "VendorPartNumber": "52242422",
                    "BuyerPartNumber": "24424242",
                    "ManufacturerPartNumber": "52242422"
                },
                "ProductOrItemDescription": {
                    "ProductDescription": "Noice cancellation headphone"
                }
            }
        ]
    },
    "Summary": {
        "TotalLineItems": 2
    }
}

Outgoing EDIs

Outgoing EDI Processing Flow Open image on lightbox

The processing flow of an outgoing EDI can be summarized as follows.

  1. The client system sends a JSON/XML file to an HTTP/S endpoint exposed by the custom function, along with the other required query string parameters.
  2. The custom function converts the received JSON/XML to EDI Generator’s internal JSON format and forwards it to EDI Generator.
  3. EDI Generator generates the corresponding EDI, validates it against the EDI specification rules and then internally routes it to MFT Gateway.
  4. MFT Gateway sends the EDI to the relevant partner over AS2.

Following are the details related to the endpoint exposed by the custom function into which the client system should send the JSON/XML files.

URL and Method
  • URL - The URL will be a custom one specific to each client
  • Method - POST
Query Parameters
  • ediType (required) - Transaction type of the EDI JSON submitted (e.g. 856, 810)
  • as2id (required) - AS2 ID of the partner to whom this EDI should be sent (e.g. 08925485US00 for Walmart)
  • gsCode (optional) - GS Code of the partner to whom this EDI should be sent (e.g. 925485US00 for Walmart). This is only required if you need to distinguish partners based on their GS code instead of the AS2 ID.
Authentication

This endpoint will always have some form of authentication. The type of authentication can be decided based on the capabilities of the client system to support it.

Request Payload

Request payload will be either JSON or XML depending on the agreed-upon integration type and the format will be decided based on the data to be included and the client system’s supported formats.

The following is a sample of a customized JSON for an invoice which will be converted to an 810 EDI and sent to the partner after the conversion. This format can be customized to cater the exact requirements of the client.

{
    "Header": {
        "InvoiceHeader": {
            "InvoiceDate": "2023-07-10",
            "InvoiceNumber": "6010119813",
            "PurchaseOrderNumber": "312312414",
            "PurchaseOrderDate": "2023-06-24",
            "ShippedDate": "2023-07-03",
            "TransactionTypeCode": "DI"
        },
        "References": [
            {
                "ReferenceQualifier": "IA",
                "ReferenceID": "12345"
            }
        ],
        "Address": [
            {
                "AddressTypeCode": "ST",
                "Name": "Buy More Inc.",
                "IDCodeQualifier": "92",
                "IDCode": "22234223",
                "Address1": "123",
                "City": "Burbank",
                "State": "CA",
                "PostalCode": "424224",
                "Country": "US"
            },
            {
                "AddressTypeCode": "SF",
                "Name": "Future Electronics",
                "IDCodeQualifier": "92",
                "IDCode": "23424",
                "Address1": "5644 OLD DOBBIN LANE",
                "City": "COLUMBIA",
                "State": "MD",
                "PostalCode": "21045",
                "Country": "US"
            }
        ]
    },
    "Structure": {
        "LineItem": [
            {
                "InvoiceLine": {
                    "LineNumber": "1",
                    "InvoicedQty": 25,
                    "ItemUOM": "EA",
                    "UnitPrice": 200,
                    "VendorPartNumber": "476001000",
                    "BuyerPartNumber": "100020840",
                    "ManufacturerPartNumber": "476001000"
                },
                "ProductOrItemDescription": {                    
                    "ProductDescription": "43-inch LED TV"
                }
            },
            {
                "InvoiceLine": {
                    "LineNumber": "2",
                    "InvoicedQty": 40,
                    "ItemUOM": "EA",
                    "UnitPrice": 150,
                    "VendorPartNumber": "52242422",
                    "BuyerPartNumber": "24424242",
                    "ManufacturerPartNumber": "52242422"
                },
                "ProductOrItemDescription": {                    
                    "ProductDescription": "Noice cancellation headphone"
                }
            }
        ]
    },
    "Summary": {
        "TotalAmount": 11000.00,
        "TotalLineItems": 2
    }
}
Expected Responses

Successfully generated and submitted (202)

If the request is successfully mapped, converted to EDI and then submitted to the MFT Gateway for AS2 sending, you will receive a 202 response. The payload of the response will be a JSON/XML containing the following fields, in case you need them for any purpose.

  • txnNo - Unique transaction number used for the EDI
  • edi - actual 856 EDI content sent

Failures due to request errors (400)

If the processing failed due to some errors in the incoming request, you will receive a 400 response. The following are the most common scenarios that can cause this error.

  • The request does not include a payload or the required query parameters (ediType and as2id)
  • The provided ediType is not supported
  • The provided as2id cannot be matched to any of the configured partners on the EDI generator account
  • Validation errors occurred during the EDI generation

The response payload will be a JSON/XML containing the following 2 fields.

  • status - a message indicating what went wrong (e.g. “Failed to generate EDI”)
  • errors - an array of the errors that caused the failure. In the case of an EDI generation error, this will most probably contain validation errors.

Other Failures (500)

In other failure cases such as unexpected errors during mapping or EDI generation, or if the EDI generator failed to submit the generated EDI to MFT Gateway, you will receive a 500 response. Generally, the response payload will be plain text containing the error message.

Are you in need of a similar solution to process EDIs from your business partners? Feel free to reach out to us via support@edigenerator.com!