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 output for 837/835 conversion 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 and click on the “JSON” button.

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. It supports any Windows, Linux, or macOS OS that can run Java 17 or higher.

Installation Instructions

  • Download and install Java. Java 17 or higher is required. You can also install OpenJDK using a package manager on Linux or macOS. Once you install Java, verify the Java’s version by running java -version command from the terminal/command line windown.
  • 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 the bin folder.

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 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.

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:

Line Columns

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:

Line Columns

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.

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