Health Facility Address Bug: A Deep Dive

by Alex Johnson 41 views

Health facility address duplication is a common problem in the OpenCRVS system. This bug causes the facility's name to appear twice in the address structure. This results in a four-level hierarchy when it should be a three-level hierarchy. This issue has been identified during testing, which can lead to confusion and data integrity problems. Let's delve into the details of this bug, its root causes, and potential solutions. We'll also cover the impact this has on the data, the expected behavior, and the actual behavior.

The Bug: Duplicated Facility Names

The core of the problem lies in how the health facility addresses are handled. When you add a health facility for events like births or deaths, the system duplicates the facility name in the name/address structure. Instead of the expected format (State -> District -> Facility), the system produces a four-level hierarchy (State -> District -> Facility (duplicated) -> Facility). This leads to address entries such as: "Rarotonga Hospital, Rarotonga Hospital, Rarotonga, Cook Islands," when it should be "Rarotonga Hospital, Rarotonga, Cook Islands." This issue can compromise data accuracy and make it difficult to locate the correct health facility. This issue was picked up during in-country UAT testing by the testing team.

To illustrate the issue further, consider these examples. The intended structure should look like this:

  • State -> District -> Facility
  • Example: Central Rarotonga -> Rarotonga -> Rarotonga Hospital

However, the actual behavior presents a duplicated facility:

  • State -> District -> LocationLevel3 (duplicated facility) -> Facility
  • Example: Rarotonga Hospital, Rarotonga Hospital, Rarotonga, Cook Islands
  • Atiu Health Clinic, Atiu Health Clinic, Atiu, Cook Islands

This duplication creates unnecessary complexity and can lead to confusion when searching for or analyzing data related to health facilities.

Expected vs. Actual Behavior: A Clear Discrepancy

To understand the impact of this bug, let's compare the expected behavior with the actual result. The system should display the address in a clean, hierarchical format. For example, a birth at Rarotonga Hospital should be recorded as: "Rarotonga Hospital, Rarotonga, Cook Islands." Similarly, a birth at Atiu Health Clinic should show as "Atiu Health Clinic, Atiu, Cook Islands." This simple, three-level structure is essential for data clarity and easy retrieval. The actual behavior, however, deviates from this expected format. As we've seen, it duplicates the facility's name, creating a confusing four-level structure. This discrepancy can cause significant problems in data analysis and reporting. The incorrect addresses can skew statistics, and make it difficult to generate accurate reports.

Unveiling the Root Cause: Query Transformers

The root cause of this health facility address duplication bug has been identified by the Deloitte team. It's related to the query transformers that read event location data from FHIR and populate form fields. Specifically, two transformers are responsible for this issue:

  1. eventLocationAddressFHIRPropertyTemplateTransformer: This transformer extracts location data from the facility's partOf hierarchy. The enum SupportedFacilityFHIRProp includes locationLevel3, locationLevel4, locationLevel5, and locationLevel6. When a health facility is selected, the transformer extracts these location levels using the getLocationHierarchy() function. The root cause for this is that the facility name (or its parent location) gets populated into locationLevel3.
  2. eventLocationAddressLineTemplateTransformer: When the location parameter is set to locationLevel3/4/5, this transformer extracts those levels from the facility's hierarchy. This duplication arises because the transformers incorrectly extract and populate the facility's name into multiple levels of the address hierarchy.

File: packages/client/src/forms/register/mappings/query/field-mappings.ts

These transformers are critical for correctly capturing and displaying health facility addresses. The bug causes the facility name to be duplicated because the transformers are misinterpreting the facility's hierarchical structure. This leads to the repeated display of the facility name. The result is the creation of a 4-level hierarchy instead of the expected 3-level structure. The code in packages/client/src/forms/register/mappings/query/field-mappings.ts contains the faulty logic. The locationLevel3 and locationLevel4 fields are incorrectly populated with the facility name.

Impact of the Bug

The health facility address duplication bug has several implications for the OpenCRVS system and the data it manages. One of the main issues is data inaccuracy. The duplicated facility names lead to incorrect address entries. This can skew data analysis and reporting. For example, it might be challenging to accurately track the number of births or deaths at a specific facility. Another problem is the reduced data usability. The duplicated entries make it harder for users to search and filter data. They also hinder the generation of accurate statistics. It also affects the overall user experience. The confusion caused by the duplicated names can frustrate users who are entering or reviewing data. This can negatively affect the system's adoption and usage.

Troubleshooting and Mitigation

The configuration changes made to the health facility levels did not fix the bug. This suggests that the issue is not related to the configuration settings but rather to the underlying code. The Deloitte team's root cause analysis highlights the specific files and transformers where the problem lies. The solution involves correcting the logic within the query transformers. Specifically, the transformers should correctly interpret the facility's hierarchy. They should extract the necessary address components without duplicating the facility name. Thorough testing is necessary to ensure that the fix is effective. It is critical to confirm that the address structure is accurate after the changes. A comprehensive testing strategy, including unit tests and user acceptance testing (UAT), is required to prevent future regressions. The fix should involve modifying the code within the two transformers (eventLocationAddressFHIRPropertyTemplateTransformer and eventLocationAddressLineTemplateTransformer). The code should correctly map the facility's hierarchy. This will ensure that the address is displayed accurately.

Conclusion: Ensuring Data Integrity

The health facility address duplication bug is a significant issue. It affects the accuracy and usability of data in OpenCRVS. The root cause lies in the query transformers that handle event location data. By understanding the problem and its causes, we can work towards a solution that ensures data integrity and improves the user experience. Addressing this bug will make sure that the health facility addresses are displayed correctly. The ultimate goal is to maintain the accuracy of health information. This is essential for the effective management and analysis of vital statistics.

For further reading on OpenCRVS, you can visit the official website: OpenCRVS