Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


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


How to access the cohort builder:

  • Click on the Cohort Builder button on the homepage of the OpenMRS application after logging in.


About the OpenMRS cohort-builder OWA

The OpenMRS cohort-builder OWA is used to make search queries against a dataset of patients with different query options, the cohort-builder currently has 5 active tabs each offering the user with different option and parameters to make search queries.

These are :-

  1. The Concept / Observation tab

  2. The Patient Attributes tab

  3. The Encounter tab

  4. The Composition tab

  5. The Saved  tab


The Concept / Observation tab

This tab gives the user the option to search via concepts or observations existing in the system.

Concepts are the individual data points collected from a population of patients.  They include both questions and answers. An example here would be whole blood sample, with the question; Does the patient value have a whole blood sample?


Observations denote anything actively measured or observed during an encounter. For example a patient's weight, age or blood pressure.


The Patient Attributes tab

This tab gives the user the option to search via demographics and a person attributes

    1. Search by demographicThis allows you search for patients with a descriptive characteristic, in a particular sector of a population
      There are 5 search options namely:- 
      1. Gender - Search by gender option i. e Male or Female
      2. Age -  Filter patient search results by age range i.e. 0-14
      3. Birthdate - Filter patient search results by birthdate range ie  -   
      4. Alive - Search only for patients who are alive.
      5. Dead - Search for deceased patients.

    2. Search by person attribute: This allows you search for patients with specific information that further describes them

      There are numerous search options namely:-

      1. Birthplace filter by place of birth

      2. Citizenship - Filter patient results by specifying their country of origin

      3. Civil Status

      4. Health Center - Filter by details of health center attended by patients

      5. Health District allows you to to filter by similar health districts

      6. Mother’s Name - Filter by similar mother’s name

      7. Race - Filter results by the patients racial background

      8. Telephone number - Filter by similar phone numbers

      9. Unknown patient

      10. Test patient

The Encounter tab

An encounter is a single, specific interaction between the patient and a provider.

This tab gives the user the option to search via patients encounter and the location at which they interacted with the service provider.

    1. Search by Encounter: This searches for patients with a specific type of activity or encounter.  For example, check in, checkout, transfer, admission e.t.c

      There are numerous search options namely: -

      1. Of Type allows you to to filter by the type of the encounter

      2. Location allows you to to filter by the location of the encounter

      3. At least this many allows you to to filter by the minimum encounter count

      4. Upto this many allows you to to filter by the maximum encounter type

      5. From - To allows you to to filter by the date range in which the encounter(s) occurred.

    2. Search by LocationThis allows you search for patients by the encounter location e.t.c Amani hospital, inpatient ward, isolation ward e.t.c. 

      Here the filters are applied according to the following:-

      1. Patients belonging to a group of encounters from a specific location.

      2. According to the timeline of the encounter

The Composition tab

This tab  allows a user to combine multiple cohorts using the logical operators:- 'AND' 'OR', and 'NOT'.

To use this query, you need to have query results from the other queries in your search history. These are the queries which will then be combined to yeild new results.

Example: There is a cohort of patients who weigh less than 100 KG at #1, and a cohort of patients with ages between 23 and 35 years at #2 in the search history.
You can create a query with a composition '1 AND 2' and add a brief meaningful description for the new query. To view a result for the combined queries.

 There are two input boxes on this tab  namely:

  1. Composition: This is where the operations are entered e.g 1 AND 2 from the example above

  2. Description: This is a memorable name or description for the search composition that is being created. Eg. for the above example, we could add a description "Patients weight < 100, age 23 -35". (checkout image below for a visual sample).


The Saved tab

 This tab gives the user the option to search for a saved cohort or definition, it has two fields namely

    1. Search Saved Definitions allows the user search for a saved definition by it’s name

    2. Search Saved Cohort allows the user search for a saved cohort by it’s name


  • The Search history: This is where an history of executed searches are saved and displayed to the user, each search can be saved either as a cohort or as a definition. There are numerous fields under this component, namely

    1. Query: This is where the name or description of the query is displayed

    2. Query Definition Options

      1. Save: This saves a definition to the database

      2. Delete: This removes a definition from the search history

    3. Results: This contains a list of all the patients contained in the search result

    4. Query Definition Options

      1. Save: This saves a cohort to the database

      2. Delete: This removes a definition from the search history


To contribute or setup this open web app please visit this Link.

Frequently asked questions:

  • Is there a limit to the number of cohorts and definitions that can be saved?

    • No there is no limit to the amount of  cohorts and definitions that can be saved.

  • No labels

1 Comment

  1. Can you make the user guide be another link from this page? That way, this page just has the overview about the module and then links for other details. Here is an example XReports Module