Freeb Install

From OpenEMR Project Wiki


FreeBInstall is the original HOWTO for FreeB 1.0.

This post is a quick overview about how to get OpenEMR working with FreeB. This is intended for developers and not meant as user documentation.

To start these instructions will assume that you have a working installation of OpenEMR available from the CVS repository at or a tar.gz version from

You will need a copy of FreeB 1.0 available by CVS at SourceForge:

cvs login

cvs -z3 co -P freeb

Freeb as a separate server and is usually installed in /usr/share:

mv freeb /usr/share/

Installing FreeB

You must install FreeB to /usr/share/freeb as root. FreeB is written in Perl so you will need to check that any necessary dependencies are installed. I find the easiest way is to try and run FreeB and work backward from the compilation error messages. Enter the freeb directory

cd /usr/share/freeb

Then execute the FreeB server script


Look at the output you should see

before server setup

If not you will probably see a compilation error message, follow the instructions below to resolve that. You can keep the FreeB Server running by starting it from the command line

./bin/ &

or by using the included init script, currently an init script is included for debian in the freeb.initd file. To use that copy it to /etc/init.d/freeb and run

/etc/init.d/freeb start

You can verify that FreeB is running by

ps ax | grep FreeB

You should see something like

[process id number] ? Ss 0:00 /usr/bin/perl /usr/share/freeb/bin/

Now that you have the server component running you need to check that the dependencies are present for the formatting scripts.


You will probably see a message like

Can't locate in @INC (@INC contains: /usr/share/freeb/lib /usr/lib/perl5/5.8.3/i386-linux-thread-multi .....

This means that you do not have the ConfigFile Perl module installed. Depending on your distribution there may be a package available that supplies this a safer bet is to use CPAN. If you have never used CPAN before you will need to run through its install process a tutorial is available from . With almost all distributions you can start at the "Installing" heading. Once CPAN is configured run

perl -MCPAN -e shell


cpan> install ConfigFile

This should be followed by some dependency resolution output, compilation and the installation of that module. Quite CPAN and try to run again. This time I got

Cannot Create : at ./formatbin/ line 7.

Which means that it successfully compiled and no further dependencies are needed for, now move on to


I got

Cannot Create : at ./formatbin/ line 7.

Which means compilation was also successful. If you got another compilation error go back into CPAN and try to install that module. Typically module names in CPAN will take the form of MainName::SubName. Repeat this process for ./targetbin/, ./targetbin/ and ./targetbin/ascii2pdf. For ascii2pdf I got

Can't locate PDF/ in @INC (@INC contains: /usr/lib/perl5/5.8.3/i386-linux-thread-multi /usr/lib/perl5/5.8.3 ......

I went back into CPAN and ran

cpan> install PDF::Create

Installation of that modules was successful and I ran ascii2pdf again and it compiled fine. You may now need to restart the FreeB_Server script in order for everything to work correctly.

Queuing bills for processing by FreeB

In OpenEMR you will need to create bills so that they appear in the billing screen. They are grouped by patient and encounter. Check the box to the right of the bills you want to process as a batch and then select from the dropdown list at the top.

Generate HCFA & Print causes the claim to be processed by FreeB and automatically printed after processing if a CUPS printer has been setup in the includes/config.php file. Generate HCFA causes the claim to be processed as a HCFA suitable for later printing manually from the PDF or as part of an electronic batch file Generate X12 causes the claim to be processed as X12 suitable for later inclusion into an electronic batch file

Currently Electronic HCFA batches have been tested with ZirMed and electronic X12 batches have been tested with ProxyMed

After clicking the Process button you will be taken to another screen which will show you the results of each queuing. All claims should queue unless you have database problems. If you return to the Billing screen you will see a message for each that that was queued that it is in the queue awaiting processing.

Claim Processing

The actual processing of claims is performed by running the process_bills.php script in the library/freeb directory of your OpenEMR installation. You can execute it by running

php -q process_bills.php bill

It will produce output telling you that is has started working on a particular claim and then when it has finished that claim. An average HCFA bill takes FreeB about 45 seconds to process, multi-page bills will take longer. An average X12 bill takes FreeB 30 seconds to process. After testing and becoming familiar with the system the process_bills script should be setup as a CRON job to execute automatically. Depending on your volume you can set it to run as often as you like but need to make sure that two processes do not run at the same time. This means that for high volumes (> 100 per day) you will most likely want it to run overnight.

Now when you go to the billing screen in OpenEMR you will see a message indicating that a claim file has been generated, you can view HCFA bills as PDF's and print them that way or by clicking the Print It link. The Print It link will print to the CUPS printer mentioned earlier. When printing as a PDF you will probably need to adjust the margins in your PDF application in order to have the fields align properly.

If you have a claim that has data problems (for instance you have not specified a billing location in the facility manager or you did not include any CPT codes) you will have a PDF with errors or a blank X12 file when you go to look at the claim.

There are a few tricks you can currently use to diagnose problems with a claim file. Take note of the billing key for the problem claim which is next to the patients name in the OpenEMR billing screen, it will be of the form [patient id]-[encounter id]. Enter the /usr/share/freeb directory and run

./bin/formatbin/ [billing key] /tmp/logfile


./bin/formatbin/ [billing key] /tmp/logfile

For the billing key 34-20040608 and to test an X12 file you would run

./bin/formatbin/ 34-20040608 /tmp/logfile

You will then be able to see the output of the billing process as it occurs as well as any errors it produces. If the billing mysteriously stops without an obvious error you may have found a bug in which case you will need to turn on the xmlrpc debugging. Goto the FreeB directory and edit the lib/FreeB/ file, several lines down (should be line 81) there is an entry

debug => 0,

change that to

debug => 1,

Now in addition to the billing output you will see the xmlrpc message as they move back and forth. Run the command again and pipe its output into less so you can search and scroll

./bin/formatbin/ 34-20040608 /tmp/logfile | less

Generate an Electronic Batch

Once you have successfully created several billing files and want to upload them to test with ProxyMed, ZirMed or another payer goto the billing screen and check the box the to right of the claims you want to include in the file. Select Generate Electronic Batch & Clear from the drop down and click process, you should received a file in your browser. Save that file and use the Payers web portal or ftp site to upload it. You can do this with either HCFA or X12 claims but you cannot mix and match unless your payer supports it, I don't know of any that do.

Fixing Claims

You can edit billings directly using phpMyAdmin in the billing table. Each claim is identified by the pid and encounter field. You can also fix claims by going back to the encounter, this would normally be the case to adjust codes for billing.