ID Cards Module

Owned by Former user (Deleted)
Last updated: Dec 17, 2017 by Fawwaz YusranVersion comment
5 min read

Table of Contents

Overview

Adds ability to design and print identification cards.

Download

Administration

  • Generate id numbers
    • By default, feature is enabled. Hide this feature by toggling the setting (formerly  global property from platform 1.8 downwards): idcards.enableIdentifierGeneration = false.
    • Allows an admin to create a list of numbers to be used when printing "empty id cards".
    • Page options:
      • Start value: The first number to start with
      • Size: The number of identifiers to generate
    • Requires privilege "Pre-Generate Random Patient Identifiers"
  • Print Empty Id Cards
    • This page has two sections that can be enabled. The first section is enabled by default, and allows for new cards to be printed from identifiers generated by the module. The next section is not enabled by default, and allows for cards to be printed from identifiers uploaded from file.
    • if idcards.enableIdentifierGeneration = true
      • Allows a user to put generated identifiers onto cards without putting names onto them. This is useful when cards will be distributed to remote locations.
      • Page Options:
        • Number: The total number of cards to print
        • Id numbers
          • None – all identifiers printed will be zeros
          • Pregenerated – numbers will be taken from identifiers that were created with the 'Generate id numbers' page
          • Range – Random identifiers taken from within the range defined in the global properties (see below)
        • The template with which to print the id cards (Only templates with type of "Print New Identifiers" or "Blank" or "" will be listed here)
        • A password that the output pdf will be encrypted with (used to try to prevent duplicate printing of the pdf files)
      • Requires "Print Id Cards" privilege
    • If idcards.enablePrintingUploadedIdentifiers = true;
      • Specify a file of identifiers (one identifier per line).
      • Specify a password as above
  • Reprint Id Cards
    • Allows a user to print cards for patients' current identifier
    • Requires the "Reprint Id Cards" privilege
  • Manage Templates
    • Allows an admin to edit what the cards look like
    • Requires the "Manage Id Card Templates" privilege
  • Global property settings
    • idcards.generateMin
      • The lower bound number used when "Printing Empty Id Cards"
    • idcards.generateMax
      • The upper bound number used when "Printing Empty Id Cards"
    • idcards.enableIdentifierGeneration
      • Hides / displays all UI elements which do identifier generation in the idcards module
    • idcards.enablePrintingUploadedIdentifiers
      • Hides / displays a new form for printing identifiers that are uploaded from a file
    • idcards.fopConfigFilePath ( as of 1.3.2)
      • The absolute file path for the Apache FOP configuration file. 

Examples

An AMPATH generated card:

SQL for very Basic id cards: Example_idcards_template.sql.zip

A archive:python script for generating large sql insert files for the idcards_generated_identifier table.

Printing with Custom Fonts

ID Cards uses the Apache FOP library version 1.0 to create the PDF.  PDF tools have a few fonts available by default, such as Helvetica and Times New Roman.  These aren't sufficient to print all languages.

To make additional fonts available, you must do the following:

1)  Install the font on the OpenMRS server, in whatever way necessary for your operating system.  (This is not part of OpenMRS.)

Example: I want to print Cambodian characters. I've found the Kh Battambang font. I follow the instructions to download and install it on my Mac, which is where I run OpenMRS. The fonts are installed to /Library/Fonts/Kh-Battambang.ttf  and /Library/Fonts/Kh-Battambangb.ttf on my Mac.

2) Create an Apache FOP configuration file.  Add the new fonts to the renderer section for pdfs. (This is not part of OpenMRS.)

The fastest method is to use the example config file included in  Apache FOP 1.0, which may be downloaded here.  The example config file is located in conf/fop.xconf . Copy it to conf/openmrs_fop.conf , or whatever filename you prefer.

Find the <fonts> section inside  <renderer mime="application/pdf"> .    Add your custom fonts, following the directions at http://xmlgraphics.apache.org/fop/1.0/fonts.html .

Note that there were major differences between Apache FOP versions 0.9x and 1.0 . Be sure to follow the 1.0 style of configuration.

Example:  I create font metrics files following the Apache FOP documentation.  In my fop config file, I add entries for normal and bold Kh Battambang fonts. The font might not be installed on the desktop machine at the registration desk, so I include the embed-url, so the font information is included in the PDF file.

        <font metrics-file="file:///Library/Fonts/Kh-Battambang-metrics.xml" embed-url="file:///Library/Fonts/Kh-Battambang.ttf" kerning="no" encoding-mode>
           <font-triplet name="Kh Battambang" style="normal" weight="normal"/>
         </font>
         <font metrics-file="file:///Library/Fonts/Kh-Battambangb-metrics.xml" embed-url="file:///Library/Fonts/Kh-Battambangb.ttf" kerning="no">
           <font-triplet name="Kh Battambangb" style="normal" weight="bold"/>
         </font>

3) Set the OpenMRS global property idcards.fopConfigFilePath  with the absolute filepath to your new FOP config file.

Example:  I saved my config file at /usr/local/apache-fop/conf/openmrs_fop.conf .

4)  In your XSLT,  mark the fields containing the custom characters with the font-family attribute.

Example:  I want the patient's name to be printed in Cambodian characters.  In Admin > Id Cards > Manage Templates, I edited the xslt for my card to say

<fo:block font-family="Kh Battambang" font-weight="normal">
<xsl:value-of select="name"/>
 </fo:block>

Troubleshooting

If the PDF doesn't render correctly, check the following:

  • If it doesn't render at all, is the XSLT correct?  Make a very simple test xslt with Western characters. If that renders correctly, add in your custom characters.
  • Check the logs.  There will be an error message if the config file couldn't be found (wrong location or no read permissions), or if the config file couldn't be parsed. If it couldn't be parsed, you can work directly with Apache FOP and the example files it came with, directing it to use your config file.  This removes OpenMRS from the equation and gives you better feedback about what's wrong with the config file. If it doesn't work from the command line, it won't work for Id Cards.
  • There are no errors in the log, but the PDF shows ####  where the custom characters should be.  This means FOP wasn't able to find that character in the font family it was using.  Did you specify the font-family attribute, exactly as it appears in your config file?   Has this custom font ever worked on this machine?  Confirm that the font is correctly installed by adding a few custom characters to a FOP example file and run FOP from the command line. 

Release Notes

  • 1.3.2 (pending)
    The PDF generator (Apache FOP) will read the config file specified in global property idcards.fopConfigFilePath . PDFs can include non-default fonts.
  • 1.3.1
    Added ability to integrate with an external identifier generation facility. This adds two new global properties
    • idcards.enableIdentifierGeneration:  Hides / displays all UI elements which do identifier generation in the idcards module
    • idcards.enablePrintingUploadedIdentifiers: Hides / displays a new form for printing identifiers that are uploaded from a file
  • 1.3
  • Added checkdigit generation back into Print New Id Cards process
  • 1.2.2
  • Added ability to generate random identifiers on the fly instead of having to pregenerate the entire spectrum of identifiers
  • 1.2.1
  • Made log of printed identifiers an optional step to speed up page load
  • 1.2
  • Initial release

Developers