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
  1. placeholders can simply be written into the text
  2. 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