Improved Error Handling in EDI Converter (Release 2.11.2)

February 28, 2025

We’re pleased to announce the release 2.11.2 of our EDI Converter.

This release improves the handling of X12 EDI parsing issues (warnings and errors). It introduces an ability to receive the parser’s warnings in the converter’s output (JSON or CSV file).

We’ve also implemented a more detailed way of reporting parsing warnings and errors. All warnings and errors now contain the segment number, the line number, and the EDI loop ID.

For example:

Seg. number:3 Line:3 Loop:2300: Element: discharge_time: Unable to convert string 13XX to time. Expected time format: HHmm. EDI string: DTP*096*TM*13XX

We’ve also fixed several bugs related to parsing dates and numbers in EDI files.

Parser Warnings in Output Files

Our X12 EDI parser runs in a “lenient” mode, meaning it does not stop when encountering a non-fatal issue with EDI.

If a parser cannot fully parse an EDI segment, it will flag it and attempt to proceed to the next one.

For example, if a date in a DTP segment is invalid, the parser will set the appropriate value to “null” (blank value). It will also produce a warning describing the issue.

By default, all warnings are written to the log file. In the case of the command-line tool, warnings are also written to the console (standard out).

This release introduces an API parameter and a command-line option directing the parser to write warnings to the output file in JSON or CSV format.

You can then log warnings on the client side, review them, and potentially correct issues in your EDI files.

To turn on writing warnings to the output, use warningsInResponse=True in your API calls.

For the CLI converter, use the --out-parsing-warnings option.

Since the converter always streams output to the client, warnings are included in the stream as objects or type “WARNING.” In other words, the output can contain “claim” objects followed by “warnings” and, again, claims.

Example:

{
  "objectType": "WARNING",
  "message": "Seg. number:16 Line:17 Loop:2010AB: Unexpected segment 'REF' for this EDI loop. EDI string: REF*G2*KA6663",
  "fileName": "unexpected_segments.dat"
}

See this Python example illustrating the logic for capturing warnings on the client side.

In CSV format, a line with a warning consists of only one column containing the warning’s text. This line starts with the “WARNING:” prefix.

Other Changes

ediFileName API parameter

You can now provide the original name of the EDI file when you use the “post” conversion API. This file name will be propagated to the JSON and CSV output. In JSON, it will be the value of the transaction.fileInfo.name field, and in CSV, it will be used to populate the fileName column.

If not provided, the converter will generate a file name.

This parameter is ignored for multipart upload API since the converter can deduce the file name directly from the request.

maxWarnings API Parameter and max-warnings CLI Option

The converter will raise an exception if there are more than 50 parsing warnings in one file.

You can change this behavior by providing the maximum number of warnings using the maxWarnings parameter for the API or the --max-warnings option for the command line tool. ‘-1’ suppresses raising an exception completely.

Changes to the Data Model

The type of the adjustment quantity field was changed to float; it was previously integer.

How to Upgrade

API Docker container

Update the image tag to repo.datainsight.health/ediconvert:2.11 and pull the new image.

The latest docker-compose file is always available in our GitHub repo.

To see the version number, invoke the about endpoint, e.g., curl http://localhost:5080/api/about.

CLI tool

Download the new version from this link, unzip.
Replace the content of your existing installation with the files from the new version, including lib and conf folders. Do not delete your license file.
Run ediconvert -V to view the version number; the output should contain the ediconvert 2.11.2 line.

EDI Parser for Java

Update the version number of the “edi” dependency in your build.gradle or pom.xml:

implementation "hdi:edi:2.11.2"