NOTE: if you are running your server on Linux, please see the documentation about Installing An OpenMRS Server On Linux.

Form Design Process

Define/Locate Concepts

The concept dictionary is a central part of OpenMRS. Concepts can commonly be thought of as questions and possible answers which are on forms (although they have other uses too).

The first step in designing forms is working out what data needs to be collected and how the form will look on paper. From there, building forms in OpenMRS is a gradual process that involves identifying/constructing concepts within your concept dictionary corresponding to the questions and possible answers on your form.

To identify concepts

  1. Review your existing paper form.

  2. Log into OpenMRS.

  3. Go to the concept dictionary

  4. For each field on the paper form, search the Concept Dictionary to locate an existing concept.

    1. If a concept already exists, it is helpful to mark the concept ID on the paper form or keep a list of form questions and corresponding concept IDs for your future reference.

    2. If a corresponding concept does not exist, add it to the concept dictionary.

Concepts have a number of possible data types. The most common are:

When setting up a concept, you will notice there is a tick box called "is set". This is useful for grouping observations together, by putting concepts together in sets. For example, one question may be "what are the reasons for poor adherence". This can be a concept with a coded data type, and several possible reasons can be set up as answers. However, the form can also have an "other, specify" space which is a concept with a text answer.

In order to gather information correctly, you should set up a third concept "combined reasons for poor adherence" which includes both the coded concept "reasons for poor adherence" and the "other specify" concept. When the user enters text for "other specify" the system will know that this particular "other specify" is referring to the "combined reasons for poor adherence" as it is in that set.

Create Form MetaData

After creating concepts, you must now set up your form in OpenMRS. This process involves using the OpenMRS application to populate the metadata related to your form. You can create a new form or duplicate an existing form (which allows you to reuse an existing form's metadata and, more importantly, its schema).


To view all forms in the system

  1. Log into OpenMRS as an administrator.

  2. Select the Administration link in the top navigation menu.

  3. Select Manage Forms under the Forms link section.


To create a new form, follow these instructions:

  1. Select the Add Form link at the top of the page

    NOTE: currently, the form submission engine requires encounter-based forms with a specific hierarchy (contained in the Basic Form definition); therefore, you should start new forms by copying the Basic Form and adding observations to that foundation.

    To duplicate an existing form, follow these instructions:

  2. Select an existing form from the Duplicate Form field —

    Example: The Basic Form contains all of the currently required fields in the proper hierarchy to be handled properly by the FormEntry engine.

  3. Click the Duplicate button.

  4. Update the form metadata, including the form name.

NOTE: While editing the form schema, ensure that the Published checkbox is unchecked. When we are ready to make the form available through the Form Entry module, we will need to check this checkbox.

Design Schema

This process involves using the OpenMRS application to create a schema for your form. This means telling OpenMRS which concepts are on your form.

To add new concepts to a form schema:

  1. Choose the Design Schema use case.

  2. Type the desired concept into the Find Field Elements search box (consult Define Concept section above). The search results should automatically display in the area below the search box.

  3. Press the Enter key. The search box and search result index (i.e. the number to the left of the search result) should now be highlighted in gold.

  4. Type the search result index in the search box.

  5. Press the Enter key.

NOTE: You can also drag n' drop the desired field element from the search result box to the form schema. However, when starting with a blank form schema it is difficult to locate the place to "drop" the field element. You can also double-click the desired field element, but this requires you to "update" the its metadata.

To move form elements within the form schema:

  1. Click the concept in the form schema

  2. Move the mouse to the desired location.

  3. Drop the form element into the desired location in the form element tree.

To update form element metadata:

  1. Right-click the desired form element in the schema.

  2. Click 'Edit Field'.

  3. Select 'Edit for this form only' to edit the form element for the current form.

  4. Enter the appropriate information (in most cases you will only need to change Multi?, Field #, Field Part, Page #, Min, Max, and Required).

To delete the form element from the schema:

  1. Select the X icon next to the form element name.

Default value

Form Schema Requirements

At this point, the form schema is fairly constrained by the XSLT that translates the submitted form data (within FormEntry) into HL7. So, if you are designing forms for FormEntry (for use with InfoPath), you must follow these guidelines. Initially, we thought we'd be making up a separate XSLT for every form; however, a single XSLT has gotten us much further than anticipated.

First of all, you want to start with the basic form schema. Here are some guides...

Other Resources