GSoC 2022: Redo Legacy UI Cohort Builder

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

• Milestones Doc

• Talk thread

• Epic

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
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

• 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

Medium Articles

Meeting Notes

24th of August 2022
Previous week:

• Fixed the UI after the 4.0 migration https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/22
• Sent a PR by fixing the unit tests that were skipped due to 4.0 migration https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/23
• Sent a PR for the cohort API memberId issue https://github.com/openmrs/openmrs-module-webservices.rest/pull/560

Next week:

• Find a way to get the cohort members
• Discuss the SQL query feature

17th of August 2022
Previous week:

• Finished the composition feature https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/20

Next week:

• Fix the cohort API issues
• Discuss the SQL query feature

10th of August 2022
Previous week:

• Finished the drug order feature  https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/19
• Reporting module issue is still there on the dev3

 Next week:

• Finish working on the query composition feature
• Start working on the SQL query feature

3rd of August 2022
Previous week:

• Reporting module PR is merged but seems to not have deployed
• Made a PR to improve the table and small desktop views https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/17
• Created the saved definitions feature https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/16
• An issue with the cohort members API: Does not returns saved the patients

 Next week:

• Finish working on the search by drug order feature

20th of July 2022
Previous week:

• Finished search by encounters feature https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/11
• Finished search by locations feature
• Changed to useSWR https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/12
• Found an issue with the reporting module https://issues.openmrs.org/browse/REPORT-890
• Created a draft PR for the reporting module issue https://github.com/openmrs/openmrs-module-reporting/pull/236

Next week:

• Finished search by enrollments feature

13th of July 2022
Previous week:

• Finished search by demographics feature
• Finished search by person attributes feature - https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/10
• Implemented the new UI - https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/9

Next week:

• Finish search by encounters feature
• Finish search by locations feature    

06th of July 2022
Previous week:

• Implemented the search history feature. https://github.com/openmrs/openmrs-esm-cohortbuilder/pull/8
• Updated unit tests of the search by concept feature
• Started working on implementing the new UI

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:

• Forked the ESM template and set up the dev environment
• Read the o3 documentation
• Created an epic with the relevant tickets: https://issues.openmrs.org/browse/O3-1299

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