Command-Line EDI Converter Documentation
Our CLI tool converts 837 and 835 transactions to comma-separated values (CSV) format or any EDI transaction to JSON.
The 837/835 conversion output is easy to understand and requires no EDI knowledge.
You can see examples of the CSV output here
To see examples of JSON output, navigate to any claim or payment example on the site, click on “Export,” select “JSON.”
For JSON conversions, the converter supports JSON Lines format with line-separated JSON objects. This provided an alternative to well-formed JSON with enclosing arrays, which are inefficient with large files.
This option is recommended for converting large EDI files.
The conversion is performed locally on your machine; your data never leaves your network.
The converter’s only dependency is Java. Windows, Linux, and macOS are all supported.
Installation Instructions
- Download and install Java. Java 17 or higher is required. You can also install Java using sdkman or a package manager on Linux or macOS. Once you install Java, verify the Java’s version by running
java -versioncommand from the terminal/command line window. - Download the converter (as a zip file) from this link
- Unzip the converter’s zip file
- Add the “bin” directory of the distribution to the path, e.g.,
export PATH=$PATH:ediconvert-2.8/bin. On Windows, go to “Settings/Advanced system settings”, “Advanced” tab, click “Environment Variables…”, click a variable called “Path” and click “Edit…”. Create a new entry with the absolute path to thebinfolder.
You need a license key to run the converter. Request your trial license key here.
Your license file will be named edi-license.bin. Save this file into the installation folder, e.g., into ediconvert-2.8. Alternatively, you can save the license file in a different location; then you need to create an environment variable that points at it.
Run ediconvert -V to view the license information.
Running the Converter
To run the converter, simply provide a path to the EDI file and the output directory. The output directory must exist. Otherwise, the converter assumes that the value of the -o option is the file name:
mkdir json
./ediconvert edi/837/my_edi_file.edi -o json
Do not prepend “./” on Windows, type just “ediconvert” instead
You can also supply patterns to convert multiple files in one go:
./ediconvert edi/837 -p "*.edi" -o json
If you provide a directory for the output, the converter will convert each file from the input into this directory. If the output is a file, the converter converts all EDI files into one.
CSV mode always converts multiple files into a single output:
./ediconvert edi/835/ -p "*" -o csv/combined-835 -m csv
Converting Large Files and Large Transactions
By default, the converter reads an entire EDI transaction, or a batch of transactions, as defined by the --chunk-size option. This may not work if a single transaction contains many claims or payments or other items.
The --spit-tran option forces the converter to read a batch of claims or payments instead of a batch of transactions. We recommend always using this option with 837/835 transactions. This option is set by default when converting to CSV but must be set explicitly when converting to JSON.
Example:
./ediconvert edi/837/edi_file_large_transaction.edi -m jsonl --split-tran
Conversion to CSV
By default, the converter creates two output files in CSV format, one for header-level data (claim or payment) and one for line-level data.
The internally generated ID, the patient control number, and the payer control number (for 835) fields are repeated for each line:
You can produce a single file using the --single-csv option. In this case, the converter will duplicate the header-level data for every line:
Converting to Standard Out
You can run the converter in the JSON Lines or in the CSV mode and pipe its output to another process, e.g.:
./ediconvert edi/837/my_edi_file.edi -m jsonl --suppress-progress | grep '"zipCode":"37232"'
Make sure to use --suppress-progress option when converting to standard out.
CLI Options
Usage: ediconvert [-hrV] [--format-json] [--single-csv] [--split-tran]
[--suppress-progress] [--chunk-size=<chunkSize>]
[--csv-config=<csvConversionSchemaFileName>]
[-m=<outputFormat>] [-o=<outFile>] [-p=<filePatterns>]
<ediFileOrDir>
Converts X12 EDI files to JSON or CSV
<ediFileOrDir> EDI file or a directory containing EDI files
-p, --patterns=<filePatterns>
File patterns to match in the directory, e.g., '*.
edi'. Required if ediFileOrDir is a directory
-r, --recurse Recursively search for matching files in all
subdirectories
-o, --out=<outFile> Output file or directory. Defaults to the name of
the EDI file + the extension depending on the
output format;'.json', '.jsonl' or '.csv'. If
omitted, the converted will write to standard
out, which can be used for piping/streaming the
output.
-m, --mode=<outputFormat> Output format. Acceptable values: JSON, JSONL, CSV.
Defaults to JSON
--format-json Format JSON with indentation and new lines. Ignored
for CSV and JSONL.
--single-csv Convert into a single CSV file with header data
repeated for each line. By default, service
line-level fields are saved into a separate file.
Ignored for non-CSV modes
--chunk-size=<chunkSize>
How many items (transactions or claims/payments) to
parse and convert at once. This option determines
the memory footprint and can be used for
fine-tuning. Ignored for JSON mode. Defaults to
200 when --split-tran is set, otherwise defaults
to 5 transactions. Higher value improves
performance but consumes more memory.
--split-tran Split large transactions. By default, the converter
parses the entire transaction at once. For large
transactions, this can be slow. When this option
is set, the converter will break up transactions
into individual items, such as a claim or a
payment. Currently supported for 835 and 837
transactions. This is the default for CSV output.
--csv-config=<csvConversionSchemaFileName>
Name of the config file for CSV conversion
--suppress-progress Suppress logging progress; use this option when
converting to standard out
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
License File Location
The default location of the license file is the installation folder of the converter.
Alternatively, you can save the license file anywhere and define the environment variable EDI_LICENSE with the path to the license file:
For Linux/macOS, add the variable to your profile:
export EDI_LICENSE=<absolute path to the file>
For Windows, create a new environment variable EDI_LICENSE from “Settings/Advanced system settings.”
Run ediconvert -V to view the license information and the location of the license file.
Logging
The converter creates logs with information and diagnostic messages in the “logs” directory. These logs are useful when routing the output to standard out.
The default location of the logs folder is the directory where the converter is executed. It can be changed by defining the ediconvert_logs_dir environment variable, e.g.,
export ediconvert_logs_dir=ediconverter_logs