This file contains notes and hints for developing and using the files and scripts in this "EDI History" project.
The purpose of the project is to gain ready access to edi claim information, quickly identify submits, rejects, denials, payments, etc. and have the information in a "big picture" format as well as the information needed to spot problems. It is a work-in-progress, unfinished, and will hopefully be improved upon. This phase is oriented to correctly parsing the x12 files, doing basic useful things with the data, and having acceptable html output. The next phase is improved integration with OpenEMR database information.
Nearly all the information that is important to this project is initially found in the user's personal directories where the downloaded edi files are stored. These are response files from payers or clearinghouses, such as claim status or ERA files. There is at present no interaction with the OpenEMR database. Therefore, while I find this project helpful, its usefulness to others depends on the kind of edi files they have. That said, these scripts should be able to parse 837, 835, 277, and 999 x12 files from any source.
I use Availity, LLC as the clearinghouse for nearly all edi transfers so these scripts are definitely oriented to Availity practices. In particular, you may want to look at your Availity EDI Preferences setup so you are getting the types of files these scripts can read.
You should select Include TA1 in the Availity preferences for .997 and .999 files in order for the scripts to be able to match these response files with the corresponding claims batch file you submitted. Also, Availity provides x12 277CA files, the .277 type for unsolicited claim responses, i.e. Availity checks the claims and the payers also check the claims and return the results in a .277 file. Importantly, file name practices of your clearinghouse or payer must be taken into account because uploaded files are categorized by file name patterns. The patterns are found in csv_record_include.php in the function csv_parameters().
One Availity setting that may be important is the grouping of ERA responses. Mine are grouped by checks from a particular payer, so my ERA files will have responses from only one payer, with perhaps more than one "transaction" in each file. Also, the "multipayer" options help to reduce the number of Availity files one has to download.
Access control is entirely under the OpenEMR scheme and will likely require the access permissions of "accounting."
Since the information in the EDI files is likely HIPAA protected, do not use these scripts on a public server!
The installed directory tree would be:
Installed files:
In addition, the project uses javascript libraries and related css already included in OpenEMR:
The scripts create a temporary uploads directory: /tmp/edihist
The csv_setup() function creates a file storage directory tree: openemr/sites/default/edi/history with subdirectories: ack csv dpr ebr era f277 f997 ibr text
and these csv files under: /openemr/sites/[site]/edi/history/csv claims_277.csv claims_ebr.csv claims_ibr.csv files_277.csv files_ebr.csv files_ibr.csv claims_997.csv claims_era.csv claims_dpr.csv files_997.csv files_era.csv
The path to these files set by csv_edih_basedir() based upon the OpenEMR directory paths.
Note: I suggest the following edit to the OpenEMR billing_process.php script:
In the file openemr/interface/billing/billing_process.php
in "function append_claim(&$segs)" near line 82 (after the "if (elems[0] == 'ST') { }" block)
// add this mod
if ($elems[0] == 'BHT') {
// give each claim a unique BHT number, used in x12 277 files : isa-control-num and st-num are concatenated
//
$bat_content .= str_replace("*0123*", sprintf("*%s%04d*", $bat_icn, $bat_stcount), $seg) . "~";
continue;
}
Once installed correctly, you begin usage by uploading your edi response files.
On the first usage the setup function will be activated and the log file will be created. It will write the directory paths and create the csv files. If this fails, the script will terminate and nothing more will happen. Failure is probably caused by file permissions problems.
The EDI History project features a tab format and the "New Files" tab is where we begin. You can select one or more files or upload a zip archive. The batch files are saved in the /openemr/sites/[site]/edi directory by OpenEMR when they are created, so you should not need to upload batch files. Note the web server configuration will likely have a maximum for the number of files and the size of the upload. The steps for uploading your response files are:
If you have batch files already stored in your /sites/[site]/edi directory, there may be a large amount of output listing the batch files. You can uncheck "HTML Output?" to avoid this. Also, if you wish to upload a large quantity of existing files, you can put then in a zip archive (no subdirectories) and upload the zip file.
In ordinary usage, the "New Files" tab is intended to handle uploads and give a summary of the information in your new response files. You will see output for each type of file, giving some particulars and listing claim information when problems are indicated. Links allow more detailed views.
Each file is checked when uploaded and files that do not meet the criteria will not be accepted. : ( If an uploaded file is already present, it will be discarded. So, you can upload duplicates without worrying about whether it is already there. Once a file is uploaded and stored, it is not overwritten or modified in any way, though the files are read to extract information or the contents are formatted for viewing.
The "CSV Tables" tab is useful after the EDI History page is reloaded in your browser, by clicking the left_nav entry, since it checks the csv table files and adds them to the list of available tables if they have the minimum size. The "CSV Tables" tab allows you to locate particular claims or files with the sort and search features of the DataTables javascript plugin.
The "ERA Files" tab is intended to allow you to see an RA style output of ERA files in your personal directory, as well as to see RA style output for a patient ID, encounter number, or trace (check) number from ERA files that have been uploaded.
The "X12 Text" tab allows you to see the contents of a response file in your personal directory. The "Notes" tab allows you to view the log file and have a plain text notes file.
The EDI methods and files are cryptic and mysterious. The formats are definitely not what I would call user-friendly. The contents and meaning of the various files, loops, and segments may be better understood with serious research. There are so called "Companion Documents" published by some insurance companies and possibly by your clearinghouse. Search for "X12 835 837 277 999 Companion Document" and see if you find anything useful. Another good source is the CMS/Medicare side-by-side comparisons, put out to aid the transition from the 4010 to the 5010 standard, e.g. ProfessionalClaim4010A1to5010.pdf.
Hopefully, the EDI History project will help you solve billing problems and have a better grasp of your billing and collection process. Note however, no accounting functions are included in the scripts, so whatever accounting process you use remain necessary. These scripts are basically for information only.
There is the thought that there may eventually be so many response files that older ones are no longer wanted. There is a draft script for archiving files and table contents into a zip file, but it is not well tested and there is no button to run it.
Although there is a script for reading x12 271 files (eligibility), it is only a draft and does not do anything. Since OpenEMR does not have the present ability to submit eligibility requests, I have no 271 response files to decipher so as to finish the script.