LinuxForHealth x12

LinuxForHealth x12 streams ASC 5010 X12 health care transactions into Pydantic Models for a pleasant pythonic parsing experience! Integration options include REST endpoints, CLI (command line), or direct access using the Python SDK.

Supported formats include:

005010X212 Claim Status
005010X221 Claim Payment
005010X222 Professional Claim
05010X223 Institutional Claim
005010X279 Eligibility
005010X220 Enrollment and Maintenance

Quickstart

Pre-requisites

The LinuxForHealth X12 development environment relies on the following software packages:

git for project version control
Python 3.8 or higher for runtime/coding support

Project Setup and Validation

pip install --upgrade pip setuptools

git clone https://github.com/LinuxForHealth/x12
cd x12

python3 -m venv venv && source venv/bin/activate && pip install --upgrade pip setuptools 
pip install -e .[dev, api] # installs dev packages and optional API endpoint
pytest

SDK

The X12 SDK provides an io package which supports streaming X12 segments or transaction models. Segment streaming parses each segment into a list containing the fields. Model streaming validates the X12 payload, and returns one or transaction models from the X12 message.

To stream segments, create a X12SegmentReader instance:

from linuxforhealth.x12.io import X12SegmentReader

with X12SegmentReader("/home/edi/270.x12") as r:
    # return the segment name and field list
    for segment_name, segment_fields in r.segments():
        print(segment_name)
        print(segment_fields)

To stream models, create a X12ModelReader instance:

from linuxforhealth.x12.io import X12ModelReader

with X12ModelReader("/home/edi/270.x12") as r:
    for model in r.models():
        # common model attributes include "header" and "footer"
        print(model.header)
        print(model.footer)
        
        # to convert back to X12
        model.x12()

CLI

The X12 CLI parses a X12 input file and returns either a list of X12 segments, or a list of X12 models based on the provided options.

To view help information

user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % lfhx12 --help
usage: LinuxForHealth X12 [-h] [-s | -m] [-x] [-p] file

The LinuxForHealth X12 CLI parses and validates X12 messages.
Messages are returned in JSON format in either a segment or transactional format.

positional arguments:
  file           The path to a ASC X12 file

optional arguments:
  -h, --help     show this help message and exit
  -s, --segment  Returns X12 segments
  -m, --model    Returns X12 models
  -x, --exclude  Exclude fields set to None in model output
  -p, --pretty   Pretty print output

To parse a X12 message into segments with pretty printing enabled

(venv) user@mbp x12 % lfhx12 -s -p demo-file/demo.270
[
    {
        "ISA00": "ISA",
        "ISA01": "03",
        "ISA02": "9876543210",
<etc, etc>

To parse a X12 message into models with pretty printing enabled

(venv) user@mbp x12 % lfhx12 -m -p demo-file/demo.270
[
    {
        "header": {
            "st_segment": {
                "delimiters": {
                    "element_separator": "*",
                    "repetition_separator": "^",
                    "segment_terminator": "~",
                    "component_separator": ":"
                },
                "segment_name": "ST",
                "transaction_set_identifier_code": "270",
                "transaction_set_control_number": "0001",
                "implementation_convention_reference": "005010X279A1"
            },
            "bht_segment": {
              <etc, etc>

In "model" mode, the -x option excludes None values from output.

API

LinuxForHealth X12 includes an experimental "api" setup "extra" which activates a Fast API endpoint used to submit X12 payloads.

user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % pip install -e ".[api]"
(venv) user@mbp x12 % lfhx12-api

Browse to http://localhost:5000/docs to view the Open API UI.

API server configurations are located in the config module. The X12ApiConfig model is a Pydantic Settings Model which can be configured using environment variables.

user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % export X12_UVICORN_PORT=5002
(venv) user@mbp x12 % lfhx12-api

Code Formatting

LinuxForHealth X12 adheres to the Black Code Style and Convention

The following command executes the black formatter with default options

user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % black ./src

Use the --help flag to view all available options for the black code formatter

(venv) user@mbp x12 % black --help

Building The Project

LinuxForHealth X12 is aligned, to a degree, with the PEP-517 standard. setup.cfg stores build metadata/configuration. pyproject.toml contains the build toolchain specification and black formatter configurations.

The commands below creates a source and wheel distribution within a clean build environment.

python3 -m venv build-venv && source build-venv/bin/activate && pip install --upgrade pip setuptools build wheel twine
python3 -m build --no-isolation

LinuxForHealth/x12