Documentation/Readme_edihistory.html

   1 <!--
   2    README_edihistory.html
   3
   4    Copyright 2016 Kevin McCormick <kevin@records>
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19    MA 02110-1301, USA.
  20
  21
  22 -->
  23
  24 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  25         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  26 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  27
  28 <head>
  29         <title>EDI History for x12 files</title>
  30         <meta http-equiv="content-type" content="text/html;charset=utf-8" />
  31         <meta name="generator" content="Bluefish 2.2.8" />
  32         <style>
  33                 body { background-color: #E6EDFA; max-width: 1024px; }
  34                 div#edih_readme { float: left;  padding: 2em; max-width: 800px; line-height: 1.2em;     background-color: #DCECE8; }
  35                 code { background-color: #FAF4E6; line-height: 1em; border-width: 1em; }
  36                 pre { background-color: #FAF4E6; line-height: 1em; border-width: 1em; }
  37         </style>
  38 </head>
  39
  40 <body>
  41 <div id="edih_readme">
  42 <h3>README Claim History Project</h3>
  43 <p>
  44 This file contains notes and hints for developing and using the files and scripts in this &quot;EDI History&quot; project.
  45 </p>
  46 <p>
  47 This applies to version 2 of my edi_history project. <strong>Use at your own risk.</strong> 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 &quot;Health Care&quot; types used for billing and insurance information. The prior version had scripts for certain proprietary formats, but this version is x12 format only.
  48 </p>
  49 <p>
  50 In order to best use these scripts, you must diligently upload all your edi files using the &quot;New Files&quot; 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).
  51 </p>
  52 <p>
  53 Since the information in the EDI files is <strong>HIPAA protected</strong>, 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 &quot;openemr/sites/[sitedir]/edi/history/&quot;  Use the OpenEMR access control scheme to determine which users can use the scripts, probably &quot;accounting&quot;. The files and contained information will be as secure as your OpenEMR installation.
  54 </p>
  55 <p><em>Upgrade</em><br />
  56 The &quot;upgrade&quot; process consists of renaming existing .csv files to <em>old_[files|claims]_[type].csv</em> and moving the existing &quot;era&quot; files to the newly created &quot;f835&quot; directory. This is handled by the <em>csv_setup()</em> function in <em>edih_csv_inc.php</em>. Otherwise, the only actons are the creation of the new directories. If you want the <em>/history/</em> directory to be clear of old cruft, then you can manually delete or move the &quot;old&quot; csv files under the <em>/csv</em> directory and also remove the <em>era</em>, <em>text</em>, <em>ibr</em>, <em>ebr</em>, and <em>dpr</em> directories, if present. Do not delete any of the following directories: archive, csv, f270, f271, f276, f277, f278, f835, f997, log, or tmp.
  57 </p>
  58 <p>
  59 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 &quot;/history&quot; 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 &gt; f835). Make sure the files ownership matches the OpenEMR ownershp. Then use the &quot;Process&quot; 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.
  60 <br />
  61 The [sitedir] is often called &quot;default&quot; and [/path/to/mydir] is your choice. Directory path details may vary.<br />
  62 <pre><code>
  63 cd /var/www/htdocs/openemr/sites/[sitedir]/edi<br />
  64 cp -a history [/path/to/mydir]<br />
  65 rm -rf history<br />
  66 </code></pre>
  67 Click EDI History in left nav (setup script will run. Check the log under the Notes tab)<br />
  68 Now copy your existing x12 edi files into their respective directories. Note [ftype] will be like f277, f835, f997, etc.<br />
  69 <pre><code>
  70 cp [/path/to/mydir]/history/[ftype]/* /var/www/htdocs/openemr/sites/[sitedir]/edi/history/[ftype]/<br />
  71 </code></pre>
  72 Repeat for each file type, but do not copy the csv files. <br />
  73 &nbsp;&nbsp;&ndash; the dpr, text, ebr, ibr types are no longer used, so don't bother.<br />
  74 &nbsp;&nbsp;&ndash; the era directory is now the f835 directory<br />
  75 Find your OpenEMR &quot;owner group&quot; with:<br />
  76 <pre><code>
  77 ls -l /var/www/htdocs/openemr<br />
  78 &nbsp;&nbsp;<samp>-rw-r--r--  1 apache apache   969 Mar 24 02:25 COPYRIGHT_AND_LICENSE</samp><br />
  79 </code></pre>
  80 Verify file ownership and permissions. (example: owner apache, group apache)<br />
  81 The directories permissions should be &quot;0755&quot; (&quot;drwxr-xr-x&quot;) and x12 files &quot;0400&quot; (&quot;-r--------&quot;)<br />
  82 <pre><code>
  83 cd /var/www/htdocs/openemr/sites/[sitedir]/edi/history<br />
  84 chown apache:apache [ftype]/*<br />
  85 chmod 0400 [ftype]/*<br />
  86 </code></pre>
  87 </p>
  88 <h3>Usage</h3>
  89 <p><em>New Files</em><br />
  90 &nbsp;-- Browse and Submit<br />
  91 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.<br />
  92 &nbsp;-- Process<br />
  93 After new files are uploaded, click the &quot;Process&quot; 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.
  94 </p>
  95 <p><em>CSV Tables</em><br />
  96 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 &quot;H&quot; link will open a formatted report of the data and the &quot;T&quot; link will open a rendition of the actual data segments from the edi file.  The &quot;Trace&quot; column generally has a reference to the transaction in another file, such as claim status tracing back to the submitted claim.  In the 835 &quot;Payment&quot; 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) <br />
  97 <em>Per Encounter</em><br />
  98 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.
  99 </p>
 100 <p><em>Notes</em><br />
 101 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 &quot;Archive&quot; button will cause log files older than 7 days to be put in a zip file.
 102 </p>
 103 <p><em>Archive</em><br />
 104 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 &quot;Report&quot; button will produce a report on your edi files and the &quot;Archive&quot; button will do the deed. There is also a &quot;Restore&quot; 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.
 105 </p>
 106 <p><em>General Thoughts</em><br />
 107 The 999/997 x12 type is the acknowledgment which lists submission errors.  It must include the <em>TA1</em> 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 <em>billing_process.php</em> 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.
 108 </p>
 109 <p>
 110 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 <em>edih_csv_inc.php</em> in the function <em>csv_parameters()</em>.
 111 </p>
 112 <p>
 113 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.
 114 </p>
 115 <p>
 116 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.
 117 </p>
 118
 119 <h3>OpenEMR Integration</h3>
 120
 121 <p>
 122 Access control is entirely under the OpenEMR scheme and will likely require the access permissions of &quot;accounting.&quot;
 123 </p>
 124 <p>
 125 Since the information in the EDI files is likely HIPAA protected, do not use these scripts on a public server!
 126 </p>
 127 <p>
 128 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 &quot;Trace&quot; numbers should identify all unprocessed payments and the files can be queued accordingly.<br />
 129 </p>
 130 <p>
 131 Secondly, the x12 batch files could be stored under designated directories to avoid a hodgepodge situation in the /edi directory.
 132 </p>
 133 </p>
 134 Thirdly, There is a rough draft script &quot;test_edih_sftp_files.php&quot; in the &quot;/openemr/library/edihistory/$quot; directory which outlines a possibility for automated file transfers using sftp.
 135 <p>
 136 <h3>File Locations:</h3>
 137 <p>
 138 The installed directory tree would be:
 139 </p>
 140 <ul>
 141         <li>/openemr/interface/billing </li>
 142         <li>/openemr/library/edihistory</li>
 143         <li>/openemr/library/css</li>
 144         <li>/openemr/library/js</li>
 145 </ul>
 146
 147 <p>
 148 Installed files:
 149 </p>
 150 <ul>
 151     <li>/openemr/Documentation
 152         <ul>
 153             <li>Readme_edihistory.html</li>
 154         </ul>
 155     </li>
 156         <li>/openemr/interface/billing </li>
 157                 <ul>
 158                         <li>edih_view.php</li>
 159                         <li>edih_main.php</li>
 160                 </ul>
 161         <li>/openemr/library/edihistory </li>
 162                 <ul>
 163                         <li>edih_archive.php</li>
 164                         <li>edih_csv_data.php</li>
 165                         <li>edih_csv_inc.php</li>
 166                         <li>edih_csv_parse.php</li>
 167                         <li>edih_io.php</li>
 168                         <li>edih_segments.php</li>
 169                         <li>edih_uploads.php</li>
 170                         <li>edih_x12file_class.php</li>
 171                         <li>edih_271_html.php</li>
 172                         <li>edih_277_html.php</li>
 173                         <li>edih_278_html.php</li>
 174                         <li>edih_835_html.php</li>
 175                         <li>edih_997_error.php</li>
 176                 </ul>
 177         <li>/openemr/library/edihistory/codes</li>
 178                 <ul>
 179                         <li>edih_271_code_class.php</li>
 180                         <li>edih_835_code_class.php</li>
 181                         <li>edih_997_codes.php</li>
 182            </ul>
 183         <li>/openemr/library/css</li>
 184         <ul>
 185       <li>edi_history_v2.css</li>
 186         </ul>
 187         <ul>
 188           <li>/openemr/library/js/DataTables-1.10.11</li>
 189           <ul>
 190                 <li>datatables.min.js</li>
 191       </ul>
 192     <li>/library/js/jquery-ui-1.10.4.custom/js/</li>
 193       <ul>
 194        <li>jquery-1.10.2.min.js</li>
 195        <li>jquery-ui-1.10.4.custom.min.js</li>
 196           </ul>
 197          <li>/library/js/jquery-ui-1.10.4.custom/custom-theme/css/</li>
 198            <ul>
 199                 <li>jquery-ui-1.10.4.custom.min.css</li>
 200            </ul>
 201          <li>/library/js/DataTables-1.10.11/DataTables-1.10.11/css/</li>
 202            <ul>
 203                 <li>jquery.dataTables.min.css</li>
 204                 <li>dataTables.jqueryui.min.css</li>
 205            </ul>
 206         </ul>
 207 </ul>
 208 <p>
 209 The <em>csv_setup()</em> function creates a file storage directory tree: </br>
 210 &nbsp;&nbsp; openemr/sites/[sitedir]/edi/history </br>
 211 with subdirectories: archive csv f270 f271 f276 f277 f278 f835 f997 log tmp
 212 </p>
 213 <p>
 214 and these csv files under: /openemr/sites/[sitedir]/edi/history/csv</br>
 215 &nbsp;&nbsp; claims_[ftype].csv  files_[ftype].csv tables are created for each file type on first appearance
 216 </p>
 217 <p>
 218 The path to these files is set by <em>csv_edih_basedir()</em> based upon the OpenEMR directory paths.
 219 </p>
 220 <p>
 221 Note:  I suggest the following edit to the OpenEMR <em>/interface/billing/billing_process.php</em> script:
 222 <br />
 223 &nbsp;  In the file openemr/interface/billing/billing_process.php<br />
 224 &nbsp;  in &quot;function append_claim(&amp;$segs)&quot;<br />
 225  near line 82  (after the &quot;if (elems[0] == 'ST') { }&quot; block)
 226 </p>
 227 <pre><code>
 228     // add this mod
 229     if ($elems[0] == 'BHT') {
 230        // give each claim a unique BHT number,: isa-control-num and st-num are concatenated
 231        //
 232        $bat_content .= str_replace("*0123*", sprintf("*%s%04d*", $bat_icn, $bat_stcount), $seg) . "~";
 233        continue;
 234     }
 235
 236 </code></pre>
 237 <p>
 238 The EDI methods and files are cryptic and mysterious.  The formats are definitely not what I would call
 239 user-friendly.  The contents and meaning of the various files, loops, and segments may be better understood
 240 with serious research.  There are so called &quot;Companion Documents&quot; published by some insurance companies
 241 and possibly by your clearinghouse.  Search for &quot;X12 835 837 277 999 Companion Document&quot; and see if you find
 242 anything useful.
 243 </p>
 244 </div>
 245 </body>
 246
 247 </html>