Command-line X12 EDI Converter Documentation on Healthcare Data Insight

EDI Converter CLI Installation

Mon, 01 Jan 0001 00:00:00 +0000

EDI Converter Command Line Tool Installation

Installation Steps

You will need a license to use the EDI Converter CLI. Request a trial license and save the edi-license.txt license file.

Download and install Java from the Oracle website. You can also use OpenJDK. Java 17 or higher is required. We recommend installing the latest long-term support (LTS) release of Java (Java 25). You can also install Java using sdkman or a package manager on Linux or macOS. Once you install Java, verify the version by running java -version in a terminal.
If Java is already installed on your system, verify that you have the correct version by running java -version; it must be version 17 or higher.
If you have JAVA_HOME environment variable defined, make sure that it points to Java 17 or higher. Alternatively, you can delete the JAVA_HOME variable. To view environment variables on Windows, go to “Settings/Advanced system settings”, “Advanced” tab, click “Environment Variables…”.
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.
(Optional) Install autocompletion (bash and zsh). Download the completion script, save it to a location of your choice, and source it from your shell configuration file (e.g., ~/.bashrc or ~/.zshrc). If you have bash_completion installed, place it in the appropriate location, such as /etc/bash_completion.d. You can find more details here.

Many Windows systems have Java 8 pre-installed. The converter requires Java 17 or later; it will fail when Java 8 is used. Follow the steps above to ensure that you have the correct version of Java.

EDI Converter CLI Option Reference

Mon, 01 Jan 0001 00:00:00 +0000

EDI Converter CLI Options

Usage

ediconvert [-hqrV] [--format-json] [--[no-]out-control-segments]
  [--out-segments] [--single-csv] [--[no-]transaction-top-level] [--[no-]validate]
  [--chunk-size=<chunkSize>] [--csv-config=<csvConversionSchemaFileName>]
  [--csv-schema-name=<csvConversionSchemaName>] [-m=<outputFormat>]
  [-o=outputFileOrDirectory] [-p=<filePatterns>]
  [--progress-chunk-size=<loggingChunkSize>]
  [--tran-type=<transactionTypeFilter>] ediFilesOrDirectories...

Converts X12 EDI files to JSON, newline-delimited JSON (JSONL/NDJSON), or CSV/Excel.

General Options

Option	Description
`ediFilesOrDirectories...`	X12 EDI files or directories containing X12 EDI files. You can supply multiple space-separated files or directories. You can also use the `*` and `?` wildcards to convert all matching files. For a directory, all files in that directory will be converted.
`-p` `--patterns=<filePatterns>`	Filename patterns to match in the root directory, for example `837P.edi`. You can specify multiple comma-separated patterns, for example `837.edi, 837.txt`. Defaults to `` (all files) if `ediFilesOrDirectories` is a directory. Enclose patterns in single quotes on Windows or double quotes on Linux. Patterns match only filenames, not directory names.
`-r` `--recurse`	Recursively search for matching files in all subdirectories.
`-o` `--out=outputFileOrDirectory`	Output file or directory in which to save the converted files. An output file will be created if it does not exist, and all input files will be converted into it. An output directory must already exist or its path must end with a slash. Each output file will use the EDI filename with an extension based on the output format. If omitted, the converter writes to the console (standard output), which can be piped to another program.
`-m` `--mode=<outputFormat>`	Output format. Acceptable values: `CSV`, `EXCEL`, `JSON`, `JSONL`. Defaults to `JSON`.
`--[no-]validate`	Validate EDI files. Validation messages are logged. For JSON or JSONL output, validation messages are written to the output file as `VALIDATION` objects. See EDI validation for details. Defaults to `false` or the value of the `EDI_VALIDATE` environment variable.
`--chunk-size=<chunkSize>`	Number of items to parse and convert at once. Items are EDI transactions or, for 837, 835, and 834 transactions, claims, payments, or members. This option determines the memory footprint and can be used for fine-tuning. Defaults to `50`. Higher values improve performance but consume more memory.
`--progress-chunk-size=<loggingChunkSize>`	How often to log progress. By default, conversion progress is logged every 1,000 items (claims, members, or transactions). You can change the default by setting the `EDI_LOG_CHUNK_SIZE` environment variable.
`-q` `--quiet` `--suppress-progress`	Suppress logging of filenames and conversion progress to the console. Use this option when writing converted data to standard output.
`-h` `--help`	Show help and exit.
`-V` `--version`	Print version information and exit.

JSON/JSONL-specific Options

Option	Description
`--format-json`	Format JSON with indentation and newlines. Ignored for JSONL.
`--[no-]transaction-top-level`	Write EDI transactions at the top level of the response as `TRANSACTION` objects. If not set, the EDI transaction is repeated in each claim, payment, or member object. Setting this option reduces the size of the response. Defaults to `false` or the value of the `EDI_TRANSACTION_TOP_LEVEL` environment variable.
`--[no-]out-control-segments`	Write control segments (`ISA` and `GS`) to the output file as JSON objects. Defaults to `false` or the value of the `EDI_CONVERT_CONTROL_SEGMENTS` environment variable.
`--out-segments`	Convert to the X12 EDI loop and segment tree format rather than a list of claims, payments, and other objects. Converting to this format can be slow for large transactions.

CSV-specific Options

Option	Description
`--csv-schema-name=<csvConversionSchemaName>`	Name of the schema (configuration) in the CSV config file, for example `key-fields`. The schema determines the layout of the CSV file. See 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 files containing transactions of this type. All other files will be ignored. Acceptable values: `835`, `837P`, `837I`, `837D`, `834`.
`--single-csv`	Convert all EDI files into a single CSV file containing claim-level and service-line-level fields for 837 and 835 transactions. If not provided, the converter writes claim-level and service-line-level data to separate files. Equivalent to specifying `--csv-schema-name=single-file`. A single file is the default for 834.

EDI Converter CLI Output Examples

Mon, 01 Jan 0001 00:00:00 +0000

EDI Converter CLI Output Examples

To familiarize yourself with the output formats, review our introduction to JSON format and the CSV format.

Examples by Transaction Type

835: CSV, Excel, JSON
837P: CSV, Excel, JSON
837I: CSV, Excel, JSON
837D: JSON
277CA: JSON
834: CSV, Excel, JSON

For more examples, go to our list of sample EDI files, select any sample, and click Export.

You can also use our free EDI Viewer to convert small files (up to three claims). Upload your file and export your data as CSV or JSON from the UI.

EDI Converter CLI User Guide

Mon, 01 Jan 0001 00:00:00 +0000

EDI Converter CLI User Guide

Running the Converter

All examples assume that the converter is installed and available in your PATH as documented here.

To run the converter, provide a path to an EDI file and an output directory (folder) or a file name. You can use backslash on Windows.

mkdir json
ediconvert edi/837/my_837_file.edi -o converted-files/ -m json

All examples in this document follow the Linux path convention with forward slash. You can use forward slash or backslash on Windows.