CLINICALCCN
07/28/2000
Freemed-YiRC Beta 0.13
----------------------

CLINICAL CASENOTE FORMS DESIGNER
--------------------------------

======================================
TABLE OF CONTENTS:
------------------
1. NOTE
2. BACKGROUND ON CLINICAL CASENOTES
3. QUITTING ANYWHERE IN THE DESIGN PROCESS
4. CLINICAL CASENOTE DESIGN MENU
5. NOTE IDENTIFIERS (NIDs)
6. BACKGROUND ON SQL DATA MODELS FOR CLINICAL CASENOTE DESIGN
7. FORM ELEMENTS
8. BACK TO FORM ELEMENTS
9. HIDDEN FIELDS
10. WHEN YOU ARE DONE ADDING ELEMENTS
11. SQL TABLE CREATION
12. WHEN YOU ARE REALLY DONE
13. IMPORTING/EXPORTING CASENOTE FORMATS
14. WHAT'S NEXT???
15. I NEED FEEDBACK
======================================


1. NOTE:  The Clinical Casenote Forms Designer in Beta0.13 should be
	relatively complete!  Only some minor bug checking is left out, but
	for the most, part, it should be rather complete!  You can also now
	edit Clinical CaseNotes, too!


2. BACKGROUND ON CLINICAL CASENOTES:

At my agency we started about 2-3 years ago getting into 'Mental Health' 
services.  We've been paying for it ever since :).  We currently have a 
contract to do four types of Medicaid services: Individual Counseling,
Group Counseling, Medication/Somatic reviews, and Diagnostic Assessment.  I've
looked at the full manual for Medicaid Services and was overwhelmed at the 
number of different types of services.

In any case, it seemed for ever that every week we had to change the way we
collected this information due to goverment (and/or Medicaid and/or HCFA)
regulations.  Then we got hit with the fact that our state Medicare computer
system wasn't Y2K compliant, so they invented this big, huge, complicated system
and they named it MACSIS.  This is in Ohio.  I know other states must be doing
similar things.  MACSIS ---REQUIRES--- all claims to be submitted electronically
using the HCFA-1500 V2 NSF file format.

Now here is the kicker.   I said electronically.  But you have to either MAIL
the disk or HAND DELIVER it to the local Mental Health board!  They WILL NOT
LET you send it over the Internet or any other electronic means.  And they
FAX the MACSIS Remittance Advise back to you in some cases?  If they are SO
worried about someone eavesdropping, then don't they know that a fax is MUCH
more interceptable than encryped e-mail or encryped file transfer!  But I will
continue...

Since they started to require this, we were faced with a challenge.   There
was NO free software to do this!!!  Nothing that I could find GPL'd in any
case.  And the software that I did find that was relatively inexpensive (~$200) 
to do electronic claims sucked.   To add insult to injury, I could not find ANY
package that would import our EXTENSIVE EXISTING claims library.  All those
pages (thousands upon thousands) of pieces of paper would have to be manually
inputted into any software we created.  To hell with that!

So I created a C++ program, called it NSFGEN, and GPL'd it!  This nice little
utility would take data from NEARLY ANY database or data source (any source
that could be converted to ASCII!!!) and spit the data out into HCFA-1500 V2
NSF files!!!  I spent LONG days and nights agonizing over the HCFA-1500 V2
NSF and MACSIS requirement manuals (techie books).  It doesn't make for good
toilet reading, either :).  In any case, this little program has served us well.
It's not easy to use and by no means user friendly, but it will do the job,
and it will do it for free.

But then I discovered the joys of PHP and SQL databases and I was engulfed,
eaten alive by it.  So now you have before you Freemed-YiRC... the fruits of
my ongoing labor...

And what I'm trying to do is to MAKE LIFE A LITTLE BIT MORE EASIER for claims
managers and computer geeks alike.

OK... enough about my struggle and back to Clinical Casenotes... :)

As I said before, there are MANY different types of clinical casenotes.  But
I've only had experience with 4.  But from my experience, I've found that
nearly all casenotes share some BASIC, CORE information.  Things such as the
Resident's name, Staff name, title of the casenote, POS/Modifer/Diagnosis code
info, etc...

But I did not want to create a static form for EACH AND EVERY TYPE OF clinical
service!!!  That could take years.  The other thing was, I don't want to limit
what it looks like for everyone who uses Freemed-YiRC.  Now, for the tech savvy
they can modify Freemed-YiRC to look like whatever they wanted to, but that
leaves the little guy to conform to what I think is the way things should be.
And we all know that FREE and OPEN SOURCE software is all about non-conformism
:) :) :).

So, to make a short story long, I'm working on a utility that would enable 
each person who uses Freemed-YiRC to make their Clinical Casenotes in
Freemed-YiRC to at least resemble what they 'used to look like' on paper.

What I want to cover in this document is some basics.  Again, I am BY NO MEANS
AN EXPERT OF MEDICAID/CLINICAL BILLING!  And If I say something stupid or 
something that is OUTRIGHT WRONG, then please let me know!!!  I NEED INPUT
from the community in order to make Freemed-YiRC AS WIDELY USABLE AS POSSIBLE!


3. QUITTING ANYWHERE IN THE DESIGN PROCESS

If you made a mistake you can't recover from and have to start over, or if you
just want to quit the design process, you can hit the 'CANCEL' link at the 
bottom of the page at any time at nearly any point in the design process.  

Doing so will bring you to a delete screen which will ask if you're sure you
want to do this.  If not, it will inform you to use your browsers 'BACK' 
button to return to the point at which you had just left.  If you do want
to cancel, then click on 'YES'.  This will destroy any work related to the
NID you've been working on, including the form itself and any SQL table you
may have created.  Be careful with it!!!


4. CLINICAL CASENOTE DESIGN MENU

To get access to the Clinical Casenote design menu, one must first have
two types of security permissions.  The first is 'Clinical_DB'.  This gives you
access to all the different Clinical related databases.  The second is 
'Clinical_CCN', also known as 'Clinical CCN Design'.  This will give you access
to the forms designer.

Once these permissions are granted, you can now access 'Clinical Databases'
from the main menu.  That will bring you to the list of Clinical Database
functions.  One of them should say 'Clinical Casenote Design'.  Click on that.

When you first go there, it should say 'No Casenote Types Listed', and give
you a link to 'Add new clinical casenote'.  Let's go ahead and do that...


5. NOTE IDENTIFIERS (NIDs)

NID stands for Note IDentifier.  You know that there are many different types
of clinical services.  I mentioned 4 eariler.  But from my experience at my
agency, we might have two or three different types of clinical casenotes PER
clinical service type!!!  For instance, my agency offers several types of 
Group Couseling.  One of them is 'Family Council'.  Another is for Sexual
Offenders.  And yet another is for 'Therapeutic Processing'.  But each form
has different fields related to it in addition to the standard information.
What to do?  Well, I use NIDs.  For each type of clinical casenote we have,
I assign each a letter which differentiates one type of clinical service from
another.  For example, I use 'c' for an Individual Counseling note.  I use 
'f' for a Group Counseling/Family Council note.  And I use 'd' for diagnostic
assessment.  You could use 's' for Group Counseling/Sexual Offender notes.

When you click on 'Add new clinical casenote', you are asked four questsions.
The first one lists the service types that you have configured Freemed-YiRC
for.  Our agency has the aforementioned 4.  The next field is the NID.  The
third field is the title of the clinical casenote.  Some examples would be:
"Individual Counseling/Psychotherapy"
"Group Counseling/Family Council"
"Medication Somatic"
etc...

And finally, the fourth field indicates whether or not this type of clinical
casenote is generally billable.  NOTE:  Individual notes may also be marked
as 'NOT BILABLLE' as well.  But some medicaid services can not be billed for,
but are required to be documented!  This is a general indicator for this type
of Clinical Casenote.  Again, if you say 'yes' in this field, then the 
individual notes can still be marked as 'NOT BILLABLE'.  But if you say 'no',
then NO note will be billed for in this category you're creating.  OK???

On my form I'm choosing 'Individual Counseling' in the first field,
'c' in the second field, "Individual Counseling/Psychotherapy" in the 'Form
Title' field, and "YES" in the 'Billable' field.

Click 'Next' to continue...


6. BACKGROUND ON SQL DATA MODELS FOR CLINICAL CASENOTE DESIGN

There are three tables in the data models relating to Clinical Casenote design.

The first is fy_clinical_forms.   This is a general database which will have
one record per Clinical Casenote type (i.e. one record per NID).  It has the
info you've just entered... Service Type, NID, Form Title, and Billabality (:)).

The second is fy_clinical_formsdata.  This is what you're about to do.

The third and last is fy_clinical_stdform.  This will be explained in a minute.


7. FORM ELEMENTS

A form is made up of a bunch of 'elements'.  Now, and element can either be
a database field, an image, a string of text, or an HTML element.  

What you're going to do is design a form from the ground up.  It's nice to
have the paper form in front of you to kind of get an idea of what's going on.

There are three sections to the 'CLINICAL CASENOTE DESIGN MENU ADD ELEMENT' 
screen, the screen you should be looking at.  The first is the 'PREVIEW' 
section.  This shows you what your form will look like when it's printed.
The next is the 'PREVIEW W/HTML' field.  This helps you figure out what's
going on 'behind the sceens' with the form.

When I was in the brainstorming stage for the forms designer, I wanted to have
a way to let the end user spice up their document. But at the same time, I
didn't want to have to learn new commands and functions to do so.  There was
already a language to do that... HTML!  

In the third section you have the 5 different types of elements, including
an HTML section.  This is where you choose what comes next on your forms.

The first thing I usually do on a form is the form title.  And I like to make
that bold (as in a bolded font), so it stands out.  How do I do that?  EASY!
USE HTML!

IMPORTANT INFO ABOUT USING HTML IN FORMS:
It is VERY IMPORTANT that you specify EACH HTML element as a separate form
element.  For example, let's say that you want to make the BOLD and in ITALICS.
Well in HTML you'd say <B><I>, right?  And then at the end of the title you'd
say </I></B>...  To mose people that's two separate strings.  But to 
Freemed-YiRC that's FOUR strings <B>, <I>, </I>, and </B>.  Actually it's FIVE
if you put the text title in the middle.  So it's to your advantage to specify
the HTML element <B>, the HTML element, <I>, the text element YOUR TITLE, the
HTML element </I>, and the HTML element </B>.  BUT WHY SHOULD I DO THIS WHEN
I CAN JUST USE THE HTML ELEMENT "<B><I>YOUR TITLE</I></B>"???   Simple.
In one word: upgradability.  I want to make sure Freemed-YiRC is software for
the future.  An open-source solution that will last for years and won't be
obsolete by next month.  If you specify EACH ELEMENT INDIVIDUALLY, then your
form can be run through different types of 'filters' so it can be made to
instantly come out in HTML, XML, plain text, HDML, and even VRML !!!!!  It's
a write once, read many (WORM) scenario.  Every time the form will be viewed
it will be generated by Freemed-YiRC instead of just read from a plain text
file.  If 'filtering modules' are added to Freemed-YiRC later, then you're
form is INSTANTLY UPGRADEABLE.  The data is in SQL tables so you can get that
out in whatever format you want, but with the form format ALSO in an SQL table,
then that's another dimension, another level of reporting!  SO PLEASE, if you
get only one thing out of this document, please make it to use INDIVIDUAL HTML
ELEMENTS IN FORM ELEMENTS!!!  It is time consuming and can be a little tedious,
but in the long run it will save you A LOT OF TIME.

8. BACK TO FORM ELEMENTS

OK.  So you're looking at the screen with three sections.  Like I said, I 
like to start out with the form title, and I like it bolded.  So the first
thing I would do is go down to the button before HTML and click on it.  What
this does it tell the forms designer that you're going to be using an HTML
element (as opposed to a field, image, or text).  Then in the pull down field
next to 'HTML' I'd choose the "Start Bold (<B>)" element.  Then I'd click
"NEXT".

Now, I've got a list of the most commonly used HTML tags in the list, but I
do recognize that you may want to use other not-so-common tags (or common tags
that I may have forgotten),  so if you choose 'Other', then you can specify
the HTML tag or statement you want to use in the 'Other' field below the HTML
tag pull-down box!

After you click on NEXT you are brought to an 'ADD ELEMENT PREVIEW' screen.
This is functionally equivalent to the middle section of the screen you
were just looking at.  It provides a preview of your form, with HTML tags
highlighted to make for easier reading.  The highlighted (i.e. bolded and 
italicized) HTML tags will not show up in your form, of course, but are 
presented to give you a sense of direction.

If you are happy with the change then hit the "NEXT" button.  Otherwise, use
your browsers 'BACK' button to return to the screen you were just looking at.

Once you hit "NEXT" on this screen, this form element is entered into the
database.

The screen will flash (relatively, depending on server speed) quickly as it
appends the form element to the database.  Then you should be brought back
to the first screen, the one with the three sections.  Here you start the
cycle again.  

To continue, I'd click on the button in front of 'Text:'.  This tells the
forms designer that I want to add some text to the look of the note.

In the blank box to the right of 'Text:', I'd put in the form title of my
note, "Individual Counseling/Psychotherapy".  Then I'd hit "NEXT".

And there it is!  In bold too!

I'm happy with that, so I'd hit 'NEXT'.

I don't want anything else on the form bolded, so I want to stop bolding.  For
this I want to specify the HTML tag </B>, or end bolding.  So, I'd click on the
button to the left of HTML, choose "End Bold (</B>)" in the drop down box to
the right of 'HTML:', and click on "NEXT".

VIOLA!  It should read:
<B>Individual Counseling/Psychotherapy</B>

Of course, the <B> and </B> won't show up on the printed form, or on any 
data entry screen.  They're shown to let you know that everything went through
OK, and is asking for you validation.  It looks OK to me, I'd hit "NEXT".

Now in the "PREVIEW" section you should have the bolded title.  In the
"PREVIEW W/HTML" section you should have the bolded title with HTML tags 
highlighted.

The next thing to do is to skip down the next line.  Seems kind of tedious,
but it must be done with HTML or else everything will appear on ONE line!!!
So go down to HTML, click the button, and choose "Newline (<BR>)".  And click
"NEXT".

You should now see a <BR> behind the title.  Click "NEXT".

Now you have two options, you can either skip down another line, or start
putting the rest of your form directly underneath the title line.  I like to
skip a line.  If you do too, then go down the HTML, click the button, and
choose "Paragraph (<P>)".  Then click "NEXT".

You should see the <P> on the line underneath the title line.  Click "NEXT".

Now you can go about filling in the rest of your form.   In the coming weeks
I will update this document, but for right now, everything is in such an
alpha stage that if I do right documentation, it may be invalid by the next
release!!!  But as you can see, you can choose from a list of "Std. Fields"
or create your own type of field.   Again, I will cover this in detail later,
but for now you are completely free to play with it and see what you can do!
NOTE:  The 'image' form element is not functional as of yet.  I didn't have
time to implement it, but it will be functional soon!  


9. HIDDEN FIELDS

Just a quick note on hidden fields.  If you look at the list of Standard 
Fields, you will see several that have nothing behind them in perens "()"...
That means these fields will not show up on paper, but they are still on the
SQL form and SQL tables.  These fields might be such things as the Resident
SQL ID number, the Staff SQL ID number, the NID, or the service code.  These
are things you may not want on the paper form but DO WANT in the SQL table
for easy SQL querying.


10. WHEN YOU ARE DONE ADDING ELEMENTS

When you've entered the last form element and are at the first screen (the one
with the three elements), you can click on 'DONE' at the bottom of the screen.
This will bring you to an error checking script.  In Beta0.12 this script only
makes sure that the form has ALL THE REQUIRED FIELDS.  You can find a list of
these fields in fy_clinical_stdforms (where std='X') or in the CCNFORM1-3 files 
in the DATA MODELS.  If all of these fields are not found on the form, then
the user is alerted to this fact, and they must go back and fix it (which isn't
very easy at this point in time!).  If all the required fields are found, 
the user can proceed to the next point.  Click on 'NEXT'....


11. SQL TABLE CREATION

This will bring you to the 'SQL Table Creation' script.  This is a somewhat
complicated script and does a lot of things.  So, all being equal, there are
many points in this script where something can go wrong if the proper
precautions are not taken!  First and foremost, the DB subdirectory and each
subdirectory below that (i.e. postgresql and mysql) MUST BE world readable
and writable (i.e. chmod 777).  One of the functions on this script is to 
create a file in one of these directories.  If the script cannot do this, it
will error out and you will have a PROBLEM!  

The first portion of the screen will have the SQL statements which are used
to create the SQL table for your custom designed Clinical CaseNote data.  The
table name varies depending on the NID selected.  The format of the table name
is: 'fy_clinicalnote_X', where X is the NID.  So, each type of casenote you
create will have it's own SQL table.  This makes reporting awesome because you
can use external tools like Crystal Reports or (Ugh!) <COUGH>MS Access</COUGH>
to get some really great reports on the data you NEEDED TWO DAYS AGO.  With
all of your data separated neatly (well... kind of neatly) into different
tables in a database, you'll be able to get UP TO THE MINUTE reports on what
is going on!!!

The SQL statements are simply For Your Information...  You don't need to do
anything with it, it's Freemed-YiRC showing off...

Next, Freemed-YiRC says it is "Opening the file DB/X/makedb_ccn_Y" where X
is the database (i.e. postgresql or mysql) and Y is the NID.  Freemed-YiRC
is going to write the above SQL statements to this file for backup purposes.
The file is named makedb_ccn_Y so it matches the format of the other 'makedb'
scripts.  You should NOT have to do anything with this file, it's simply more
FYI (but it may come in REAL handy in a bad situation some day!).

If the permissions aren't set correctly, you'll receive an error message, and
the script will fail at that point.  Please correct the permissions to DB
and below, and RELOAD the script.

After it opens the file, it will attempt to write to it.  If the file was 
opened without error, this should go rather smoothly as well.

Finally, it will create the SQL table using the SQL statements FOR YOU.  If
Freemed-YiRC works at all, this shouldn't fail.  However, for some reason 
if you already have a table named 'fy_clinicalnote_Y', then you'll have a 
problem!  But you shouldn't... and if you did, it should have been detected
and reported to you at the beginning of the process.  If you do have a problem
at this point it is probably due to someone else trying to create the same
form at the same time as you!  Very rare, I should think.

If all goes well, you will have a newly christened SQL table that contains
all the fields you've specified in the forms designer.  You should get a
blinking message that says "OPERATION COMPLETE NO ERRORS"... if all goes well.

If all does not go well, you will get a blinking red message that says
"OPERATION FAILED!! ERRORS WERE DETECTED!" and it will tell you to fix the
error and to then reload this page.  However, at this point in time (Beta0.12),
you cannot go back and modify the format.  You can delete it and start over,
but you can't go to the middle of the form and add or change something...
that piece is still yet to come (and will be a rather hard piece to do, too).
:(

You can now click on the 'BACK TO MENU' link.   CONGRATULATIONS!


12. WHEN YOU ARE REALLY DONE

This will bring you back to the Design Menu.  Now you should have one entry
with the NID you entered ('c' for mine), the Form Title, the Clinical Service
Code, and two other links which should say "View" and "Delete".  Clicking on
"View" will show you the form as it will look like just as you've printed it.
No HTML tags will show up, but the HTML will function exactly like it is 
supposed to.  All fields will show up with an 'X' for a character, a 'N' for
a number, a 'D' for a decimal, 'MM/DD/YYYY' for date, and 'HH:MM:SS' for time,
just like in the preview.  A hidden field will appear as "[name]" where name is
the name of the field.  "Delete" will do just that.  If you say "YES", then
it will delete the record in fy_clinical_forms with the NID you entered and
every record in fy_clinical_formdata with that NID.  Therefore wiping out
any data relating to this casenote type (NID).  Be careful with it!!!!
It will also delete any SQL table related to this Clinical CaseNote (NID).  So
if you spent a lot of time designing it, and you accidentially delete it, you're
going to be one angry person... :)


13. IMPORTING/EXPORTING CASENOTE FORMATS

Now that you have a finished design, you can save this to a file so you never
(HOPEFULLY) have to do this again!!!  Let's walk through the steps involved in
exporting and then importing a casenote design.

NOTE:  Before you do this, a backup would be wise!!!!

- Exporting Casenote Designs

To Export a Clinical CaseNote design, go to the Clinical Casenote Design Menu.
Your casenote format should be listed.  Next to it (on the right) you should
see 'View', 'Export', and 'Delete'.  Click on 'Export'.  It asks you if you're
sure... you're sure, aren't you???  If so, click 'Yes'.

It will then attempt to create a file named 'usr/export_ccn_X' where 'X' is
NID (i.e. 'c' for our example).  This in the Freemed-YiRC directory structure.
If all goes well, you should receive a message stating "OPERATION COMPLETE
NO ERRORS".  This is a good sign.  If you see this, then you're done, and
can click on the 'BACK' link.

However, if you get an error message (usually blinking RED) then you have 
a problem.  The most common problem is the 'usr' directory in the Freemed-YiRC
file structure isn't writable by a web-user (i.e. the user 'nobody').  If not,
you need to make sure it is by issuing the following command in Linux in the
Freemed-YiRC directory 'chmod 777 usr'.  That should do it.  Try hitting your
browser's 'reload' button and seeing if it works now.

The other problem may be that there is already a file by that name in the
'usr' directory, and you don't have permissions to overwrite it.  Remove the
file (or rename it if you don't want to remove it) and try again.

- Importing Casenote Designs

In order to import the design you just exported, you're going to have to delete
your current casenote type.  To do this, go to the 'Clinical Casenote Design
Menu' and hit 'Delete'.  This will ask if you're sure, as this is a rather
DANGEROUS operation.  Click 'YES'.  

You should be returned to the menu with it saying 'No Casenote Types Listed',
and an 'Import clinical casenote design' link near the bottom.  Click on the
'Import' link.

This will search the 'usr' directory for all files beginning with 'export_ccn_'.
You should be presented with a drop down list of these files.  However, you
should only have one choice if you're following this tutorial, 'export_ccn_c'.
Click on 'Import!'.  

It will attempt to open the file and read the initial configuration info.
Now, many things can go wrong here.  If the file is not web-user readable
(i.e. by the user 'nobody'), then you will get an error.  Please make sure this
file is readable by 'nobody' and try again (if the file was created by 'nobody',
then you should be able to read it just fine...).  

Now because this file can be shared between systems with different settings,
Freemed-YiRC checks to make sure everything looks OK.  For Instance, let's 
say that your system doesn't have 'Individual Counseling' in the Clinical
Services Database.  If not, Freemed-YiRC will alert you to this fact and ask
that you either add this type, or choose a different Service with which this
note will be associated.  Also, if the NID in the importted note is already
used in your system, then you will be asked for a new NID.  You can also
modify the title of the form, as well as select whether or not it should
be billable (in general). 

If all goes well and you receive no errors and wish not to change anything,
then click 'Next'.

Now Freemed-YiRC will attempt to open this file and import the form design.
Again, many things can go wrong here as this is a complicated feat.  Howerver,
if all goes well, you should receive an 'OPERATION COMPLETE NO ERRORS' message.
If so, click on the 'Next' link.

This next piece will actually create the SQL table for you.  Again the table
name will take the format of 'fy_clinicalnote_X', where X is the NID.  It
displays the SQL code for the curious.  It will also attempt to write this
SQL code to a file in case you ever need it.  It will attempt to write it
the directory 'DB/?db?/makedb_ccn_X', where ?db? is your database type
(postgresql for PostgreSQL, and mysql for MySQL), and X again is the NID.
Just as with the 'usr' directory, the 'DB' directory, and all of it's 
subdirectories should be readable and writable by the web-user 'nobody'.
If not, then you may receive an error message.

If everything goes according to plan, you should receive the 'OPERATION
COMPLETE NO ERRORS' message again.  This is a good thing.

Pat yourself on the back because if you click on the 'BACK TO MENU' link,
you're done!



14.  WHAT'S NEXT???

The Clinical CaseNote parts of Freemed-YiRC are still rather infantile, and
I'm sure there are many bugs and missing features.  If you see something
undesireable, or something desireable that you wish added, let me know!!!

For now, try out your new casenote and see how you like it!!!


15.  I NEED FEEDBACK

PLEASE LET ME KNOW IF YOU HAVE ANY COMMENTS/QUESTIONS/SUGGESTIONS!!!!
mailto: joethielen@familyandyouth.org
