Command-Line X12 EDI Converter

Overview

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.

To familiarize yourself with the output formats, review our intro to the JSON format and the intro to the CSV format. To see examples, navigate to any claim or payment example on the site, click “Export,” select “JSON” or “CSV (All Fields).”

The CLI tool produces the exact same output as our API server, except code descriptions.

To view schemas of the output, navigate to our API Reference Guide and expand the “200” response.

For JSON conversion, the tool supports NDJSON (a.k.a. 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 Steps

Download and install Java. Java 17 or higher is required. We recommend using the latest long-term support release of Java. 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 -version command 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.10/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 into the installation folder, e.g., into ediconvert-2.10. 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, 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 input 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

Converting to CSV

Some column names in the last release have been changed. Several new columns have been added. See this post for details.

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.

To view field names and types, navigate to our API Reference Guide and expand the “200” response.

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:

The CSV output format is governed by a configuration file containing several pre-defined configurations (conversion schemas) for 835 and 837 transactions.

The conversion schemas define what fields to include in the CSV file and how many times to repeat columns for repeating groups, such as adjustments or diagnosis codes.

You can create your custom conversion schemas or select from several built-in schemas.

Please follow this document for more details.

Converting to the Console (Standard Output Stream)

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 -q | grep '"zipCode":"37232"'

Make sure to use -q option when converting to the console.

Command-line Options

Usage: ediconvert [-hqrV] [--format-json] [--single-csv] [--split-tran]
                  [--chunk-size=<chunkSize>]
                  [--csv-config=<csvConversionSchemaFileName>]
                  [--csv-schema-name=<csvConversionSchemaName>]
                  [-m=<outputFormat>] [-o=<outFile>] [-p=<filePatterns>]
                  [--tran-type=<transactionTypeFilter>] <ediFileOrDir>
Converts X12 EDI files to JSON or CSV
      <ediFileOrDir>    EDI file or directory containing EDI files
  -p, --patterns=<filePatterns>
                        File patterns to match in the directory, e.g., '*.edi'.
                          You can specify multiple comma-delimited patterns, e.
                          g., '*837*.edi, *837*.txt'. Required if ediFileOrDir
                          is a directory. For CSV conversion, all files must
                          contain transactions of the same type, e.g., 835.
  -r, --recurse         Recursively search for matching files in all
                          subdirectories
  -o, --out=<outFile>   Output file or existing directory where to save output
                          files. Must be a file for CSV conversion. The file
                          will be created if it doesn't exist. In the case of a
                          directory, the output file name will be the name of
                          the EDI file + the extension depending on the
                          format;'.json', or '.jsonl'. If omitted, the
                          converted will write to the console (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.
      --chunk-size=<chunkSize>
                         How many items (transactions or claims/payments) can
                          be parsed and converted at once. This option
                          determines the memory footprint and can be used for
                          fine-tuning. 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 option is set by default for CSV output, but not
                          for JSON.
  -q, --quiet, --suppress-progress
                        Suppress logging file names and conversion progress to
                          the console; use this option when converting to
                          standard out
  -h, --help            Show this help message and exit.
  -V, --version         Print version information and exit.
  
Options for CSV conversion:
      --csv-schema-name=<csvConversionSchemaName>
                        Name of the 'schema' (configuration) in the CSV config
                          file, such as 'key-fields'. The schema determines the
                          layout of the CSV file. See https://datainsight.
                          health/docs/csv/schemas for more details.
      --csv-config, --csv-schema-file=<csvConversionSchemaFileName>
                        Name of the file containing CSV conversion schemas in
                          the 'conf' directory. Defaults to
                          'conf/csv_conversion.yaml'.
      --tran-type=<transactionTypeFilter>
                        Convert only the files that contain transactions of
                          this type, e.g., 835 or 837P. All other files will be
                          ignored.
      --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.
                          Same as providing
                          '--csv-schema-name=lines-with-header-repeat-first-row'.

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 converter always logs to the file, even when the --quiet option was set.

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