This file contains notes and hints for developing and using the files and scripts in this "EDI History" project.
This applies to version 2 of my edi_history project. Use at your own risk. The intended use is for health care facilities only. The scripts in this project are intended to create a system for managing x12 edi files. These are the mysterious x12 format data files known as 837 Claim, 835 Payment, 270 Benefit Inquiry, 271 Benefit Response, 276 Claim Status Inquiry, 277/277CA Claim Status, and 278 Authorization; and do not forget 999 Acknowledgement. (The 824 type is not dealt with, but if anyone gets these, it should not be too hard to interpret.) These are the "Health Care" types used for billing and insurance information. The prior version had scripts for certain proprietary formats, but this version is x12 format only.
In order to best use these scripts, you must diligently upload all your edi files using the "New Files" tab. Of course, in order to upload you must first download. In order to download, you must complete some registrations, obtain accounts with usernames and passwords, and configure OpenEMR with the information for your x12 partner(s).
Since the information in the EDI files is HIPAA protected, do not use these scripts on a public server! (or any computer where access is not restricted) The files and tables are stored in the OpenEMR directory under "openemr/sites/[sitedir]/edi/history/" Use the OpenEMR access control scheme to determine which users can use the scripts, probably "accounting". The files and contained information will be as secure as your OpenEMR installation.
Upgrade
The "upgrade" process consists of renaming existing .csv files to old_[files|claims]_[type].csv and moving the existing "era" files to the newly created "f835" directory. This is handled by the csv_setup() function in edih_csv_inc.php. Otherwise, the only actons are the creation of the new directories. If you want the /history/ directory to be clear of old cruft, then you can manually delete or move the "old" csv files under the /csv directory and also remove the era, text, ibr, ebr, and dpr directories, if present. Do not delete any of the following directories: archive, csv, f270, f271, f276, f277, f278, f835, f997, log, or tmp.
If for some reason the scripted upgrade does not work, you may wish to manually upgrade. I suggest you make a copy of the existing /history directory tree. Then delete the "/history" tree (not the /edi, just the /history -- this leaves all the batch files under /edi/[name].batch.txt). Then select the EDI History module in the OpenEMR left nav, which will create the new /history tree. Then copy all the x12 files to their new directories (note: era > f835). Make sure the files ownership matches the OpenEMR ownershp. Then use the "Process" button on the New Files tab. De-select the html and errors output checkboxes. New csv tables will be created and all the files will be processed. You may have to upload one file to activate the Process button.
The [sitedir] is often called "default" and [/path/to/mydir] is your choice. Directory path details may vary.
cd /var/www/htdocs/openemr/sites/[sitedir]/edi
cp -a history [/path/to/mydir]
rm -rf history
cp [/path/to/mydir]/history/[ftype]/* /var/www/htdocs/openemr/sites/[sitedir]/documents/edi/history/[ftype]/
ls -l /var/www/htdocs/openemr
-rw-r--r-- 1 apache apache 969 Mar 24 02:25 COPYRIGHT_AND_LICENSE
cd /var/www/htdocs/openemr/sites/[sitedir]/documents/edi/history
chown apache:apache [ftype]/*
chmod 0400 [ftype]/*
New Files
-- Browse and Submit
Select multiple files from your user directory where you have downloaded the files from your x12 partner. If there is a limit on uploaded files, you should be notified so you can repeat the process and get all files uploaded. Each file is checked and classified. If a file is rejected, that is because it was not interpreted as an x12 format file or not a type the scripts can deal with (there are many types). The scripts should be able to parse any valid Health Care category x12 file, so please submit a comment on the OpenEMR forum if you have a valid x12 file that is rejected. For .zip files, there must not be sub directories, because the parsing script does not handle sub directories.
-- Process
After new files are uploaded, click the "Process" button. You can (de)select html and/or errors-only, but they are on by default, so you will see a listing of summary information about the files, with particular details where the script detected a possible problem, like a rejected claim.
CSV Tables
On this tab, there is a select list to choose a table to view. Also, select a period or date range to limit the response. The tables are rows of information intended to allow you to select files or transactions of interest. The jQuery DataTables plugin has sorting and searching capability. The "H" link will open a formatted report of the data and the "T" link will open a rendition of the actual data segments from the edi file. The "Trace" column generally has a reference to the transaction in another file, such as claim status tracing back to the submitted claim. In the 835 "Payment" tables, the trace is to the payment check/eft number. Unfortunately, in my opinion the standard OpemEMR claim generation file does not create a correct value in the BHT segment, so tracing to the exact claim submission is not reliable. (See note below)
Per Encounter
Enter the claim id (xxxx-xxxxx) (from the 837 CLM01 value). The csv tables will be searched and a dialog will open with links to the corresponding 837, 277, and 835 transactions, and 997/999 if the batch file was rejected.
Notes
Select a log file to view, or the notes file. The notes file is just a textbox you can use to make little reminders. The log files are daily records of actions done. The "Archive" button will cause log files older than 7 days to be put in a zip file.
Archive
The edi files are quite fascinating when they are new, but once the billing cycle is complete they may be of little interest. The idea of the Archive tab is to enable you to select an ageing period and put all the older files and their csv data rows into a zip archive stored under /history/archive. The batch files under the /sites/[sitedir]/edi directory are not archived, since I do not want to accidentally break anything. You can change the available periods by editing the edih_view.php file in the Archive div. The "Report" button will produce a report on your edi files and the "Archive" button will do the deed. There is also a "Restore" button which will unpack the selected archive file and replace the files and csv data rows. You will have to manually delete archive files that you no longer want. After you have performed an Archive, you will probably want to reload the EDI History page which will refresh the the select lists and clear the output under each tab.
General Thoughts
The 999/997 x12 type is the acknowledgment which lists submission errors. It must include the TA1 segment in order for the scripts to be able to match these response files with the corresponding batch file you submitted. I think it would be possible to edit the billing_process.php script to give a unique ID for the GS06 value, in which case the TA1 segment would probably not be required, but a few code edits would be needied in the edi_history scripts as well.
In the old version, I used file name patterns to classify files, but version 2 uses information in the GS segment for this purpose. If that fails for some reason, the file name pattern is tried. The patterns are found in edih_csv_inc.php in the function csv_parameters().
For 835 ERA files, I assume the internal grouping of the files is by check/eft from a particular payer. The 835 files table has a row for each check/eft number, so there are likely more rows than files.
It also happens that a clearinghouse will append several ISA--IEA envelopes into a single file. I assume they are all of the same type. Each ISA control number receives a line in the files table, so this is another reason there could be more rows than files in a files table.
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!
If this project proves to be useful and reliable, then I would suggest modifying the ERA batch posting script so it is activated from a tab button. A scan of database check numbers compared to a scan of files_f835.csv "Trace" numbers should identify all unprocessed payments and the files can be queued accordingly.
Secondly, the x12 batch files could be stored under designated directories to avoid a hodgepodge situation in the /edi directory.
Thirdly, There is a rough draft script "test_edih_sftp_files.php" in the "/openemr/library/edihistory/$quot; directory which outlines a possibility for automated file transfers using sftp.
The installed directory tree would be:
Installed files:
The csv_setup() function creates a file storage directory tree:
openemr/sites/[sitedir]/documents/edi/history
with subdirectories: archive csv f270 f271 f276 f277 f278 f835 f997 log tmp
and these csv files under: /openemr/sites/[sitedir]/documents/edi/history/csv
claims_[ftype].csv files_[ftype].csv tables are created for each file type on first appearance
The path to these files is set by csv_edih_basedir() based upon the OpenEMR directory paths.
Note: I suggest the following edit to the OpenEMR /interface/billing/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,: isa-control-num and st-num are concatenated
//
$bat_content .= str_replace("*0123*", sprintf("*%s%04d*", $bat_icn, $bat_stcount), $seg) . "~";
continue;
}
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.