Paperwork handling in GNUmed
Concepts
Reports
Reports typically are letters written to accompany the patient to and from hospital stays or consultant visits. They are compiled from templates into a final non-recomputable format. That final format is then usually presented for post-processing with a text editor or word processor right before printing. The report will then usually be printed onto plain, blank or special, pre-printed business letterhead paper.
Forms
Forms, as opposed to reports, are often used for requesting particular therapies or diagnostic procedures. They are typically printed onto pre-printed forms with lines, boxes, and fields. Thus forms are best implemented with a dedicated on-screen mask to fill in which is then compiled and printed onto the paper form. As opposed to reports it is often not useful to make the compiled form editable before printing.
There is limited forms support in GNUmed so far.
Templates
A template is a file which contains the constant parts of a document interspersed with placeholders for patient data.
Form engines
A form engine is code inside the GNUmed used to turn a template into a printable output format. Currently GNUmed knows three such engines, each driving external software to create output: the Openoffice.org engine, the
LaTeX engine, the XeLaTeX? engine, the AbiWord engine, the plain-text generic engine, and the PDF-form (FDF) engine.
Placeholders
Placeholders are usually category words that will be replaced by specific instances of that category for the current patient, say
lastname is replaced by
Kirk
.
Placeholders come in the format
$<placeholder-name::usually-optional-arguments::usually-optional-maximum-length>$
. Where arguments are not provided, and no length limit is desired, the separators
::
and
::
must still be supplied, e.g.
$<lastname::::>$
. So,
$<soap::ap::25>$
is valid, as is
$<soap::ap::>$
, as is
$<soap::::>$
, as is
$<soap::::25>$
, but
not $<soap::ap>$
or
$$
.
Exactly what can be put into the arguments field will depend on the placeholder in question. More examples include:
- date of birth:
$<date_of_birth::%Y-%m-%d::>$
- show date of birth formatted Year-Month-Day
- %Y %m %d (and alternative format string elements) are listed in the table found at Python documentation
- progress notes:
$<soap::ap::300>$
- show the 'a' and 'p' rows from among (i.e.) soAP notes, to a maximum of 300 characters
- GNUmed will let the user select which soAP rows, from which encounters
All data is passed to placeholder handlers 'as is'.
More detail on using many of the placeholders is provided on the page
Placeholder Reference. The full set of what has been programmed can be found within
this source file.
Ask for more placeholders on the
mailing list as you need them.
Future placeholders might consider those utilized in other systems, for example
in Oscar EMR.
Theory of Operation
GNUmed uses engines to drive external programs to combine templates holding placeholders with data for those placeholders into instances of a template and compile that into an output format. Currently, the supported engines are
OpenOffice, PDF forms, XeLaTeX, AbiWord, Text, and
LaTeX (there are two more:
gnuplot
and
image_editor
but they are not used to create reports of forms).
When generating a letter/form GNUmed will export the template from the paperwork template definition record inside the backend into a temporary file. That file will be scanned for known placeholders which are then replaced by their respective data values with regard to the active patient. Some of those replacements may require user interaction (such as selection of which progress notes to actually include). Next, GNUmed will open the substituted file in an editor suitable for the file type in order to facilitate further editing. Depending on the external program the finalized template will then either be printed directly via that application (OOo) or be compiled into PDF (
LaTeX, PDF forms). The resulting PDF is then printed using any number of methods (
Acrobat Reader,
gtklp
,
os.startfile
,
Internet Explorer, MacOSX?
open
,
gsprint.exe
, or the shell script
gm-print_doc
). Eventually, the user is asked which episode to file the new document under (which can be aborted to not file the document). If possible, a re-editable version of the document is filed alongside the finalized non-editable version.
Depending on the exact purpose of the above process some steps will be skipped. For example, printing a medication list will not open the substituted
LaTeX file in a text editor before printing.
OOo template specifics
Letter definitions are stored in the database in the form of an OOo template file (.ott) along with some metadata (see table
ref.paperwork_templates
). Upon opening the document in OOo GNUmed sets up a callback in OOo in order to be notified about closure of the document. It then reads back the current filename of the document and uses that to import it into GNUmed. That way, the correct document is imported even if the user saved it under a different name meanwhile.
- in OpenOffice open a new document
- design the letter template as you please
- where appropriate include placeholders within the document
- placeholders can simply be written into the text
- placeholder can also be added via the Insert / Field menu
- save it as an .ott OpenOffice document template
There is one caveat with placeholders in OOo: With placeholders simply written into the flow of text you cannot put two of them onto the same line (perhaps even the same logical paragraph). The reason is that the OOo search-and-replace function does not support non-greedy regular expression searches
Their advantage is, however, that they automatically inherit the properties of their surrounding text which is not the case with placeholders explicitely declared via
Insert /
Field. Those, on the other hand, do properly work on the same line ... So, pick your poison (or choose
LaTeX )
LaTeX/XeLaTeX template specifics
These templates are written in the
LaTeX document preparation language. The templates as such will not be fully valid
LaTeX code because placeholder definitions start and end with the
$
sign which has a special meaning in TeX. Many other characters also have a TeX meaning (
_
,
\
,
%
etc) such that they may need to be escaped if you want them to appear as-is in the final PDF Output.
If you are using
LyX or another TeX-aware editor to create templates make sure to check the template file for special characters having been helpfully escaped by the editor but thus rendering invalid your placeholder definitions. This particularly applies to
$
,
%
, and
_
as they frequently occur in date/string formatting and placeholder names.
Have a look at the
existing templates to see how to achieve things like
LaTeX list item generation,
LaTeX table generation, or smart list item separators (eg. no trailing separator after the last item or no singular separator when the list is empty).
Use
.tex
as the filename extension for
LaTeX templates.
PDF form template specifics
Such templates are created by taking a PDF form, inserting placeholders into the form fields, and importing this partially pre-filled form into the database as the template file. For use as a template do
not flatten the PDF when saving the partially pre-filled form.
You will need to install both a PDF viewer capable of form filling as well as
pdftk.
Adding a new letter template
With the template prepared as describe above follow this procedure:
- in the GNUmed menu go to Manage Master Data
- use the menu item paperwork templates
- in the dialog fill in the fields as needed and select the template file you created
- save the new template
The new template should now be available from within GNUmed.
Debugging / Troubleshooting
When working through a misbehaving document template it can be helpful, after perusing any available logs, to consider the use of a minimal example of the kind described
here and elsewhere.
Next: Test Result Management