GSoC 2022: Redo Legacy UI Cohort Builder

 

Primary mentor

 @Brandon Istenes                       

Backup mentor

@Jayasanka Weerasinghe 

Assigned to

@Anjula Samarasinghe 

Abstract

Re-do legacy UI cohort builder in 3. x. In addition to supporting all current functionality, would also like to be able to save search history.

 

Required Skills

React

JavaScript

Typescript

Jest

Project Rating and length

Medium

175 hours

Objectives

  • OpenMRS 1.0 has a wonderful cohort builder tool that allows a user to create a complex set of criteria to create cohorts of patients with particular characteristics

  • We would rebuild this functionality in OpenMR3.0

  • This will entail

    • creating a REST API on the backend to support the operations of the cohort

    • creating a frontend, essentially identical to the current version in 1.0

Documentation

Detailed Project Report

The Cohort Builder is a tool in OpenMRS 3.0 in the Reporting Compatibility module that lets the user perform ad-hoc queries for patients with defined characteristics, and combines multiple queries into more complex ones. The Cohort Builder 3.0 have the following features.

  • Search for patients using concepts 

Searching by observations gives the user the option to search via concepts or observations existing in the system. This component has an input to search and a to search including verbose or without verbose.


  • Ability to view the search history 

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

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

  2. Query Definition Options

  3.  

    1. Save: This saves a definition to the database

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

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

  5. Query Definition Options

  6.  

    1. Save: This saves a cohort to the database

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

  • Search for patients using demographics 

Searching by demographics is where the user can create cohorts using the demographics and patient attributes.

There are 5 demographic search options namely:

  1. Gender - Search by gender option

  2. Age - Filter patient search results by age range i.e. 0-14

  3. Birthdate - Filter patient search results by birthdate range ie 20 Feb 1988 - 03 May 2006

  4. Alive - Search only for patients who are alive.

  5. Dead - Search for deceased patients.



    Search for patients using personal attributes

There are 10 person attributes search options:

  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 centre attended by patients

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

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

  7. Race - Filter results by the patient's racial background

  8. Telephone number - Filter by similar phone numbers

  9.  Unknown patient

  10. Test patient

This allows the user to search for patients with specific information that further describes them.




  • Search for patients using encounters

Search by Encounter uses to search patients with a specific type of activity or encounter. For example, check-in, check-out, transfer, admission etc.

There are 5 search options namely: -

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

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

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

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

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

 

  • Search for patients using a location

Search by location allows the user to search for patients by the encounter location. Ex: Amani hospital, inpatient ward, isolation ward etc.

Here the filters will be applied according to the following:-

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

According to the timeline of the encounter




  • Search for patients using program enrolments

Searching by program enrollments has the following fields required by the user to perform the search.

Program:

Date Ranges for the following

In The Program

Enrolled in the program

Completed the program




  • Ability to save the cohorts and the definitions

Saved definitions search gives the user the option to search for a saved cohort or definition, it has two fields,

  1. Search Saved Definitions allows the user to search for a saved definition by its name

  2. Search Saved Cohort allows the user to search for a saved cohort by its name

  • Search for patients using drug orders 

Search for patients taking specific drugs

  1. Drugs

  2. Care setting

  3. When

  • Composition

    A composition query combines together the results of multiple cohorts using the logical operators: AND, OR and NOT.



Weekly Reports

Issues

Issue Number

Issue Link

Pull Request

Status

Issue Number

Issue Link

Pull Request

Status

O3-1311

https://issues.openmrs.org/browse/O3-1311

O3-1311: Initial setup of the project

Merged

O3-1300

https://issues.openmrs.org/browse/O3-1028

O3-1300: Implement search by concept component

Merged

O3-1385

https://issues.openmrs.org/browse/O3-1385

O3-1385: Write unit tests to test the components

Merged

O3-1302

https://issues.openmrs.org/browse/O3-1302

O3-1302: Implement the Search History component

Merged

O3-1394

https://issues.openmrs.org/browse/O3-1394

O3-1394: Update the UI according to the new design

Merged

O3-1303

https://issues.openmrs.org/browse/O3-1303

O3-1303: Implement the search by demographics and person attributes feature

Merged

O3-1304

https://issues.openmrs.org/browse/O3-1304

O3-1304: Implement the search by encounters and search by location feature

Merged

O3-1417

https://issues.openmrs.org/browse/O3-1417

O3-1417: Use SWR for data fetching

Merged

O3-1305

https://issues.openmrs.org/browse/O3-1305

O3-1305: Implement the search by enrollments feature

Merged

O3-1427

https://issues.openmrs.org/browse/O3-1427

O3-1427: Add the deploy job to the workflow

Merged

REPORT-890

https://issues.openmrs.org/browse/REPORT-890

REPORT-890: Add the missing api module dependency

Merged

O3-1309

https://issues.openmrs.org/browse/O3-1309

O3-1309: Implement the search definitions feature

Merged

O3-1443

https://issues.openmrs.org/browse/O3-1443

O3-1443: Improve the tablet and small desktop layout

Merged

O3-1306

https://issues.openmrs.org/browse/O3-1306

O3-1306: Implement the search by drug order feature

Merged

O3-1445

https://issues.openmrs.org/browse/O3-1445

O3-1445: Add search composition feature

Merged

O3-1471

https://issues.openmrs.org/browse/O3-1471

O3-1471: Add css to fix the broken UI layout

Merged

O3-1472

https://issues.openmrs.org/browse/O3-1472

O3-1472: Fix the tests that were skipped due to the migration

Merged

O3-1482

https://issues.openmrs.org/browse/O3-1482

O3-1482: Wrap the global selectors with a custom class

Merged

Medium Articles

Meeting Notes

24th of August 2022
Previous week:

Next week:

  • Find a way to get the cohort members

  • Discuss the SQL query feature

 

17th of August 2022
Previous week:

Next week:

  • Fix the cohort API issues

  • Discuss the SQL query feature

 

10th of August 2022
Previous week:

 Next week:

  • Finish working on the query composition feature

  • Start working on the SQL query feature

 

3rd of August 2022
Previous week:

 Next week:

  • Finish working on the search by drug order feature

 

20th of July 2022
Previous week:

Next week:

  • Finished search by enrollments feature

 

13th of July 2022
Previous week:

Next week:

  • Finish search by encounters feature

  • Finish search by locations feature    

 

06th of July 2022
Previous week:

Next week:

  • Finish search by demographics feature


29th of June 2022
Previous week:

  • Worked on the requested changes on the PR

  • Added the translations 

  • Had a discussion with Ciaran regarding the UI

  • Translations are not working - Created a ticket https://issues.openmrs.org/browse/O3-1381

  • Started working search history

  • It's better to have the dev3 server running with the reporting and reportingrest. It's already installed it's not running because of some dependency modules are missing.

Next week:

  • Write the unit tests and send a PR

  • Continue working on the search history

 

22nd of June 2022
Previous week:

  • Had some problems with setting up the backend

  • Worked on the search by concepts milestone

Next week:

  • Send the search by concepts PR by the 23rd of June

  • Start working on the search by demographics milestone    

 

15th of June 2022
Previous week:

  • Still working on the search by concepts milestone there were some issues with the backend modules but was able to fix it by changing the backend server from dev3 to demo where the required modules were installed.

  • But after that still got a 500 from the adhoc API

  • Worked on the search by concept UI

Next week:

  • Send the initial PR

  • Finish the search by concept milestone

  • Finish the search by demographics UI   

 

08th of June 2022
Previous week:

  • Created the milestone document

Next week:

  • Finish working on the search by concepts feature

 

01st of June 2022
Previous week:

Next week:

  • Create the milestone document

  • Start working on the search by concepts feature

 

Final Presentation

Resources

Github Repository

https://guide.openmrs.org/en/Using%20Data/cohort-builder.html

OpenMRS 3.0: A Frontend Framework that enables collaboration and better User Experience

OpenMRS 3.0 Micro Frontend Demo Page