Command-Line X12 EDI Converter

Overview

Our command-line tool converts X12 EDI files to JSON or CSV/Excel. Conversion to CSV is supported for 837 (healthcare claim) and 835 (ERA) EDI formats.

The 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 tool produces the exact same output as our API server, except code descriptions.

See our data dictionary for the details about JSON fields and CSV columns. To view formal schemas of the output, navigate to our API Reference Guide and expand the “200” response.

The converter can efficiently handle large X12 EDI files with the special support for 837/835 files. See this section for more details.

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.

Current release: 2.11.2.

Installation Steps

  • Download and install Java from the Oracle website. You can also use OpenJDK. 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 -version command from the command line window/terminal.
  • If Java is already installed on your system, verify that you have the right version by running java -version command, it must be version 17 or higher.
  • Download the zip file with the converter from this link.
  • Unzip the converter’s zip file, the root folder/directory of the installation will be ediconvert.

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, i.e., into ediconvert. Alternatively, you can save the license file in a different location; then you need to create an environment variable that points to it.

You can run the converter by providing the full path, e.g., ediconvert\bin\ediconvert on Windows or ediconvert/bin/ediconvert on Linux/macOS.

We recommend adding the bin directory of the converter to the “Path” so you can run it from anywhere. 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. On Linux, append it to the PATH variable in your shell configuration file, e.g., for .bashrc: export PATH=$PATH:ediconvert/bin.

All examples in this document assume that you’ve added the converter to the path so we omit the full path to bin/ediconvert.

Run ediconvert -V to view license and version information.

Running the Converter

All examples use linux-style forward slashes; use backslash on Windows.

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

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 to CSV

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

By default, the converter creates two output files in CSV format, one for claim-level data and one for line-level data.

To view names and types of columns, 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:

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

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

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 one of the built-in schemas by providing --csv-schema-name option.

Please follow this document for more details.

Converting Large Files and Large EDI Transactions

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.

Use -m jsonl option to produce NDJSON files instead of well-formed JSON.

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 (CLM segment for 837) or payments (CLP segment for 835) 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 or NDJSON.

Example:

ediconvert edi/837/edi_file_large_transaction.edi -m jsonl --split-tran

Command-line Options

Usage: ediconvert [-hqrV] [--format-json] [--out-parsing-errors] [--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>         X12 EDI file or a directory containing X12 EDI
                               files
  -p, --patterns=<filePatterns>
                             File name patterns to match in the directory, e.
                               g., '*.edi'. You can specify multiple
                               comma-delimited patterns, e.g., '*837*.edi,
                               *837*.txt'. Defaults to '*' (all files) if
                               ediFileOrDir is a directory.
  -r, --recurse              Recursively search for matching files in all
                               subdirectories
  -o, --out=<outFile>        Output file or existing directory where to save
                               output files. It must be a file for CSV
                               conversion; all matching EDI files are converted
                               into a single CSV file. 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 + '.json', or '.jsonl' extension. If
                               omitted, the converted will output 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.
      --out-parsing-errors   Append EDI parsing errors and warnings to the
                               output. If not set, parsing errors and warnings
                               are only written to the logs.
      --chunk-size=<chunkSize>
                             The number of EDI transactions or claims/payments
                               for 837/835 that will 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 an 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 the
                               list of schemas.
      --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. All other files will be ignored.
                               Acceptable values: 835, 837P, 837I.
      --single-csv           Convert all EDI files into a single CSV file
                               containing the claim-level and the service
                               line-level fields. If not provided, the
                               converter will convert claim-level and
                               line-level data into separate files. Same as
                               providing
                               '--csv-schema-name=lines-with-header-repeat-first
                               -row'.

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.

Healthcare and X12 EDI Codes

The CLI tool does not provide descriptions for healthcare codes, such as ICD-10 and CPT. Use our API server product if you’re interested in getting descriptions along with the codes.

You can, however, obtain descriptions using our free code lookup. You can download all the descriptions for a specific code set in the CSV format or use the API call to get only the ones that you need.

The CLI converter converts some of the EDI codes, such as an “Entity Identifier code” to mnemonic constants, e.g., the code 77 is translated to SERVICE_FACILIY.

You can always find the code for the constant using the code lookup tool. Enter a name of any constant to see its description and the EDI code it corresponds to, e.g., SERVICE_FACILITY.

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