Detailed Technical Implementation of the HIV CT Package within the O3 Reference Application

Forking the reference application

The Reference Application can be easily set up on an instance using Docker by cloning the repository - https://github.com/openmrs/openmrs-distro-referenceapplication. However, since the PATH DRC project had custom requirements and customizations to metadata, we opted to fork the Reference Application repository - https://github.com/openmrs/path-drc-emr and use the docker approach instead of using the SDK. This approach allowed us to make the customizations iteratively, test our changes locally and deploy them to the instance.

To set up the instance with Docker, the detailed instructions are provided in the Development Guide.- https://openmrs.atlassian.net/wiki/spaces/docs/pages/150930190/Set+Up+an+Instance+of+O3#Using-Docker

Configuring branding

The navbar logo, login page logo, and favicon were configured to feature the logo of the DRC’s Ministry of Health.

1. How to change the navbar logo - https://openmrs.atlassian.net/wiki/spaces/docs/pages/151060758/Configure+Branding#Changing-the-logo-used-on-the-navbar

2. How to change the login page logo - https://openmrs.atlassian.net/wiki/spaces/docs/pages/151060758/Configure+Branding#Changing-the-logo-used-on-the-login-page

3. How to change the favicon - https://openmrs.atlassian.net/wiki/spaces/docs/pages/151060758/Configure+Branding#Changing-the-favicon

Configuring Metadata

The instance's metadata was configured and customized to meet PATH DRC-specific requirements and to support the HIV CT package developed by OHRI.

Configuring DRC specific metadata

1. Address template

   • The address template displayed in the patient registration form needed to be customized.

   • How to customize the address template - https://openmrs.atlassian.net/wiki/spaces/docs/pages/185565250/Configuring+Metadata#Updating-the-address-template

     Open

     

     PATH DRC address template
     Open

     

     Default address template

2. Default locale

   • The default locale was made to French - https://github.com/openmrs/path-drc-emr/blob/d5bd17d2448725f78415b3c032fb7bed72ab5d03/distro/configuration/globalproperties/i18n-core_demo.xml#L8

3. Visit types

   • The visit types were configured in the distro/configuration/visittypes/visittypes-core_data.csv - https://github.com/openmrs/path-drc-emr/pull/20 .

4. Relationship types

   • The relationship types were configured in distro/configuration/relationshiptypes/relationshiptypes-core_demo.csv - https://github.com/openmrs/path-drc-emr/pull/21

5. Locations

   • The login locations were customized according to the DRC specific requirements in distro/configuration/locations/locations-core_demo.csv - https://github.com/openmrs/path-drc-emr/pull/19

6. Forms

   • Given the forms that PATH DRC provided in their requirements, the form DRC Mini Dossier was made - https://github.com/openmrs/path-drc-emr/blob/main/distro/configuration/ampathforms/DRC%20Mini%20Dossier.json

   • French translations for the form were also added to the instance - https://github.com/openmrs/path-drc-emr/blob/main/distro/configuration/ampathformstranslations/drc_mini_dossier_form_translations_fr-core_demo.json

7. Concepts

   • https://app.openconceptlab.org/#/orgs/openmrs/collections/DRCHIV2024/ - a custom OCL collection to facilitate concepts for the custom forms and to use standard CIEL concepts in the HIV CT forms.

Configuring HIV CT package specific metadata

Backend Config

All the content found in https://github.com/openmrs/openmrs-content-hiv/tree/main/configs/backend_config were added to the respective folders within distro/configuration. These are the configurations that would get picked up the initializer module.

1. Forms

   • A list of all the HIV CT forms that were added to the instance - https://openmrs.atlassian.net/wiki/x/A4AwDQ

   • The forms can be found in https://github.com/openmrs/openmrs-content-hiv/tree/main/configs/backend_config/ampathforms and were added to distro/configuration/ampathforms

     • Some of these forms were customized to better fit the requirements (e.g - DRC HIV Enrollment form is an customized version of the Service Enrollment Form of the content package)

   • To provide translations for a form, check the guidelines on how to do so - https://github.com/mekomsolutions/openmrs-module-initializer/blob/main/readme/ampathformstranslations.md

2. Encounter types

   • A list of all the encounter types necessary for the HIV CT package that were added into the instance - https://openmrs.atlassian.net/wiki/x/B4AvDQ

   • The encounter types found from https://github.com/openmrs/openmrs-content-hiv/blob/main/configs/backend_config/encountertypes/encountertypes.csv were added to the existing encounter types into distro/configuration/encountertypes/encountertypes_core-demo.csv.

   • It is crucial to add these encounter types to the configuration for the initializer to load in the forms HIV CT forms.

3. Concepts

   • The following OCL collections were added to the instance at distro/configuration/ocl-

     • https://github.com/openmrs/openmrs-content-hiv/blob/main/configs/backend_config/ocl/OHRITechGroup_OCT_v202310241547.2023-10-24_124407.zip. This is regularly looked at manually for updates and the updated zip is added to the PATH DRC instance.

4. Concept sources

   • The concept sources found in https://github.com/openmrs/openmrs-content-hiv/blob/main/configs/backend_config/conceptsources/conceptsources.csv but not in the O3 Reference Application’s default concept sources were added to the distro/configuration/conceptsources/conceptsources-core_data.csv file.

5. Patient Identifier types

   • The patient identifier type found in https://github.com/openmrs/openmrs-content-hiv/blob/main/configs/backend_config/patientidentifiertypes/patientidentifiertypes.csv was added to the already existing list in the distro/configuration/patientidentifiertypes/patientidentifiertypes-core_demo.csv file.

Frontend Config

1. Frontend modules

   • Added the OHRI HIV CT frontend modules to the O3 Reference Application by adding the package names to the frontend/spa-assemble-config.json file - https://github.com/openmrs/path-drc-emr/blob/main/frontend/spa-assemble-config.json. The modules that were added:

2. Overriding forms

   • To override the Service Enrollment Form and the Clinical Visits form in the HIV CT package Program Management, the formUuids of clinicalVisitFormUuid and serviceEnrolmentFormUuid were updated to be the UUIDs of the custom forms in frontend/config-core_demo.json - https://github.com/openmrs/path-drc-emr/blob/b15209f258e915fc0ede5e8435e591d3a7438371/frontend/config-core_demo.json#L74

   • The formNames needed to be updated as well to match the form name of the replaced forms. The formNames of all the forms needed in addition to the changed ones or else they could not be found.

3. Translation overrides

   • Translations for strings in the HIV CT package were added as Translation overrides to the frontend/config-core_demo.json - https://github.com/openmrs/path-drc-emr/blob/b15209f258e915fc0ede5e8435e591d3a7438371/frontend/config-core_demo.json#L78