Idgen Module

Overview

The idgen module provides a facility for managing identifier generation and allocation within an OpenMRS implementation. Below is an overview of the primary components and how they are meant to be used.

Manage Identifier Sources

An identifier source is a configurable component which is capable of generating identifiers of a given Patient Identifier Type. An identifier source comes in 3 different flavors, a Local Identifier Generator, a Remote Identifier Source, and a Local Identifier Pool, which are described in more detail below. In some circumstances a single Patient Identifier Type may have 2 Identifier Sources on the same server - a Local Identifier Generator which produces new sequential identifiers, and then an associated Identifier Pool which is populated with batches of these identifiers to support random allocation.

Adding new Identifier Sources is done by first choosing the Patient Identifier Type and the Identifier Source Type, and then configuring additional options. Editing an existing Identifier Source is done by clicking the "Configure" button next to the Identifier Source. It is not possible to change from one type of source to another after it has first been created. It may or may not be possible to change various configuration options, depending on whether or not the Identifier Source has generated any identifiers yet. The options are:

Local Identifier Generator

This source generates new, sequential identifiers based on it's configuration. To create one of these, you must specify the first valid identifier in the sequence and the supported character set. You may also specify an optional length, prefix and suffix.

The simplest example would be a sequential numeric identifier, starting at 1, which generated identifiers as 1,2,3,4,5,6... Configuration of this would be:

• Base Character Set: 0123456789

• First Identifier Base: 1

• Prefix: <Empty>

• Suffix: <Empty>

• Length: <Empty>

A more complex example would be an alphanumeric identifier, 6 characters long, prefixed with 'U' in order to generate identifiers as 'U12000', 'U12001', 'U12002'. Configuration of this would be:

• Base Character Set: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ

• First Identifier Base: 12000

• Prefix: U

• Suffix: <Empty>

• Length: 6

It is important to note that the generator will add a check digit (and possibly a separator character) depending on whether or not this is configured on the Patient Identifier Type itself. This, along with the regex format, needs to be factored in when setting up the generator configuration.

Remote Identifier Source

This identifier source enables for the use of http to connect to a remote URL and receive back generated identifiers as the response. This is fairly prototypical at present. It should be configured by specifying a remote url which is capable of returning one or more generated identifiers as a response document. Currently, the response format is expected to be a text document with one identifier per line.

The special {batchSize} variable should be specified in the configured URL. This variable will be replaced by the actual number of identifiers to generate at run time. For example, you might configure your server with a url such as http://country.gov/idgen/moh_id?batchSize=\{batchSize\} in order to connect to a Ministry of Health web service for ID allocation. Then, when a user wants to request 10 new identifiers, the number 10 will be substituted for the batchSize parameter for this request.

Local Pool of Identifiers

A local pool of identifiers should be used in the circumstance where actual identifier generation isn't appropriate, but a pool of pre-defined available identifiers is required. A common example might be an institution that has a universal patient identifier, but which has several disconnected OpenMRS instances serving remote locations and which are synched up with each other at a later point in time. In this case, it would be appropriate to configure a single parent server with a Local Identifier Generator which actually produced new identifiers in sequence, and then configure each other server with a Pool of Identifiers which is populated with identifiers generated by the parent source. This would ensure that each server has it's own allocation of identifiers to give out, and none of these overlap with one another.

When creating a new Pool of Identifiers, the most important fields to configure are the associated identifier source and whether the pool is sequential or random in it's distribution of identifiers.

In the future, it is intended that the minimum pool size, batch size, and associated identifier source will be used together to drive an advanced workflow where the pool can alert administrators when it is running low and/or auto-fill itself with the configured batch size from the associated identifier source. These features have not yet been implemented, so these configuration options do not yet hold any real significance.

Generation and Management of Identifiers

Each type of Identifier Source allows for batch generation of identifiers to a file. This is done by first going to the "Manage Identifier Sources" page, and then clicking the "View" button next to the Identifier Source you wish to use. This page will provide a summary of how the Identifier Source is configured and will provide a small form at the bottom which can be used to batch export identifiers. Simply enter the number you wish to generate, and an optional comment which will be added to the log for future reference, and a text file with one identifier per line will be returned for download.

NOTE: CARE SHOULD BE TAKEN TO ENSURE THAT EACH EXPORT IS DONE MEANINGFULLY, AS EACH EXPORT REMOVES IDENTIFIERS FROM THE SOURCE AND WILL NOT BE RE-ALLOCATED AGAIN IN FUTURE EXPORTS.

For Identifier Pools, the facility also exists to upload a new batch of identifiers into the pool. So, a typical use case would have one or more periodic batch exports from a Local Identifier Generator on a particular server, and then an import of this exported file into a Local Pool of Identifiers on the same or different server.

Auto-Generation Configuration

Kept deliberately separate from the notion of Identifier Sources is the ability to enable auto-generation and allocation of a Patient Identifier from a particular source. This can be managed by going to the "Auto-Generation Options" screen. If one or more Identifier Sources is configured for an Identifier Type, then you can add a Auto Generation Option for that Identifier Source. For each Identifier Source, you are able to configure the following options:

• Source to Auto-generate From: Choose from each Identifier Source configured for this type

• Location (optional): Add this if you want to limit a source to patient identifiers assigned for a specific location (this option is not compatible with the IDGen integration with the OpenMRS 1.0 patient dasboard, but does work with the Paper Record module)

• Automatic Generation Enabled?: Set to true if you want to allow users to auto-generate identifiers of this type for patients

• Manual Entry Enabled?: Set to true if you want to allow users to manually enter identifiers of this type for patients

Currently, these options affect a single place in OpenMRS - the create patient and edit patient (short) pages. Screenshots to follow...

Viewing Log of Identifier Generation Activity

A final section that is available is a feature that allows for searching through a log of all identifier generation for the server. This should be fairly self-explanatory, and is accessed via clicking into the "View Log Entries" section.

Fetching IDs via REST Web Services

There is a new module underway called idgenws.  This module exposes a rest url on the server running idgen that allows for remote sites to ping the server to get a new identifier.  This is a WIP, please see TRUNK-345

Download

• Download the idgen module

Release Notes

Version 2.2 and above

See changelog

Older versions:

Version 2.1

• Incremented minimum OpenMRS version to 1.6 to ease maintenance requirements

• Added support for OpenMRS 1.8 and 1.9

Version 2.0

• Add reserved identifiers and compatibility with OpenMRS 1.6+

Version 1.4.0.2

• Initial alpha release

Required Privileges

The following privileges may be necessary for various activities. It may be necessary to create them manually, and add them to your user's role.

• Manage Identifier Sources: Allows user add, edit, and remove identifier sources

• Manage Auto Generation Options: Allows user add, edit, and remove auto-generation options

• Generate Batch of Identifiers: Allows user to generate a batch of identifiers to a file for offline use

• Upload Batch of Identifiers: Allows user to upload a batch of identifiers

Troubleshooting

Problem: An error occurs when submitting the "Create Patient" form and a blank page is displayed. (OpenMRS 1.6.x, tribe-module not installed)

Solution:

Make sure the global properties value of use_patient_attribute.tribe is set to false.

Problem:

You've created an identifier type and an identifier source.  You create or edit the patient and attempt to add a new identifier. The new identifier type appears in the dropdown list, but there's no checkbox to auto-generate it.

Solution:

Confirm that you enabled auto-generation. See the "Auto Generation Configuration" section of this page.

The long edit patient form doesn't currently have a checkbox. Use the short patient edit form to add the new identifier.

Problem:

You've created an identifier type and enabled automatic generation. When you add the new identifier to a patient, the "generate" checkbox appears but nothing happens when you click it. The Identifier field remains blank. When you save, there's an error message that patients must have at least one identifier.

Solution:

Is ID Gen able to generate new identifiers? To diagnose, open the URL that the add identifier javascript calls.

First, you must find the id number of your identifier source through the admin page. Go to Admin > Patients > Manage Patient Identifier Sources . Click the View button, which appears next to your identifier source. Look at the URL that opens. It will end in "source=" and the identifier source id number.

Then point your browser to the IDGen generate ID url.
http://<your_host_name_here>/openmrs/module/idgen/generateIdentifier.form?source=<your_identifier_source_id_here>

If IDGen is able to generate IDs, your browser will download a text file containing the next identifier.

If you get an error or a blank page, IDGen is unable to generate an ID. Look at the Tomcat logs for clues, and consult the Implementers mailing list for further help.