Page tree
Skip to end of metadata
Go to start of metadata

Structure of an encounter form

An encounter form has three main sections:

1. Demographics section:

Contains patient demographics (Non-Observations). The demographics fields are auto-populated by the app, and are set as read only. The reason for disabling editing is that data in this section is entered using a registration form, and according to the workflow, either a registration form is first filled for new patients before filling encounter forms, or patient demographics data is downloaded from the server side before filling the encounter form for pre-registered patients. This section is common to all encounter forms for a given project. Patient demographics include:

  • Patient Names
  • Patient Identifier
  • Gender
  • Date of Birth
  • Patient UUID

See Form Demographics Section

2. Encounter details section:

(Non-Observations: encounter date, encounter provider, encounter location, form uuid, system user). These section is common to all forms for a project. The fields may have different labels in respect to the use case, e.g 'Encounter location' may be labelled 'Hospital name' or 'Screening site', etc.

See Encounter Details Section

3. Observations:

A collection of questions, which keys should be tied to concept dictionary. While each Observation question is coded (has a concept ID), some questions may require Coded answers and others require Non-Coded answers.

  • Coded answers: The questions have a predefined set of possible answers, and therefore each of the answers is tied to a concept ID. Use Select, radio buttons, checkboxes or hidden input fields.
  • Non Coded questions: Answers have no concept IDs. Can take text, numerical or boolean values. Commonly use Select, radio buttons, checkboxes, text input fields.

Coded questions and answers are represented with the following notation:



Example 1

For example, to collect weight of a patient, if a concept with ID 5089 and name WEIGHT (KG) is defined in concept dictionary for that purpose, then the coded question can be represented as follows:

5089^WEIGHT (KG)^99DCT

Within the form, weight becomes Coded question with non coded answers, which can be scripted as follows:

<div class="form-group">
	<label for="obs.weight">Weight (KG) <span class="required">*</span></label>
	<input class="form-control" id="obs.weight" name="obs.weight"
		type="number" placeholder="Kilograms"
		data-concept="5089^WEIGHT (KG)^99DCT"

Note that we assign the coded value to the attribute data-concept

Example 2

If Yes/No answers are coded with the Concept IDs 1065 and 1066 respectively, a question requiring such coded answers can be scripted as follows:

<div class="form-group">
    <label>Are you currently on any treatment/ medication?
           <span class="required">*</span>
        <div class="form-group">
            <label class="font-normal">
                <input name="currently_on_medication" type="radio"
                       data-concept="1193^CURRENT MEDICATIONS^99DCT"
        <div class="form-group">
            <label class="font-normal">
                <input name="currently_on_medication" type="radio"
                       data-concept="1193^CURRENT MEDICATIONS^99DCT"

Note that for coded answers, the coded notations of the answers are assigned to the value attribute of input fields.

Repeated and nested questions

Some questions may be repeated in the sense that the form allows duplication of an input field or a set of input fields. For example, to record diseases reported by a patient, the following code snippet can be used:

<div class="repeat sub-section">
    <div class="form-group">
            Specify other reason/disease: <span class="required">*</span>
        <input class="form-control obs.other_admission_disease"
            name="obs.other_admission_disease" type="text"
            data-concept="1915^FREETEXT GENERAL^99DCT"

Some concepts may be nested as groups/concept sets, as per their definition in the concept dictionary. Questions related to such concepts should be scripted in a way that the answers shall be serialized into a structure that maintains their nested/grouping relationship. In such a case, each grouping for the concepts has a concept ID, and we assign the notation for the group to a data-concept attribute of the div element containing questions belonging to the group.

For more information and examples of how repeated and nested sections are created, See:

Encounter form payload

When form data is saved, data will be placed into a JSON payload with values under the three sections in corresponding objects. Example of JSON payload:

"patient": {
"encounter": {
    "encounter.location_id": "7",
    "encounter.provider_id": "3420-7",
    "encounter.encounter_datetime": "2016-02-02"
"observation": {
    "5089^WEIGHT (KG)^99DCT": "75",
    "5090^HEIGHT (CM)^99DCT": "173"


Encounter forms may also include Reminders, which are messages triggered based on some given logic, and on user inputs. For example,

<div class="form-group">
    <label for="obs.bmi">BMI (KG/M<sup>2</sup>)
          <span class="required">*</span>
    <input class="form-control" id="obs.bmi" name="obs.bmi"
            data-concept="1342^BODY MASS INDEX^99DCT"
<label id="bmi_above_threshold_message"
       class="alert alert-info">
    Advice on weight loss, check Random Blood Sugar

In this example, a reminder message has been provided to alert the user on what action to take if BMI value is above some threshold. The reminder is initially hidden. Based on BMI value that shall be inputted, a decision will be made on whether to display the reminder or not. Below is the javascript code to make this decision:

var show_message=function(element_id){
var hide_message=function(element_id){

var evaluate_bmi_logic = function(){

$('#obs\\.bmi').change( function(){

  • No labels