Add procedure history management system with encounter type and form #41

Mwanje · 2025-09-17T19:04:57Z

This PR introduces metadata to support the structured documentation and management of patients' procedure history. These include:

New "Procedure History" encounter type for structured procedure documentation
Complete procedure history form with fields for procedure details, timing, outcomes, and duration
Integration with OCL procedure concepts collection (53+ standardized procedures)
Support for documenting completed medical procedures with comprehensive metadata
Validation rules for data integrity (date validation, required fields)

Read the Procedure history wiki page to learn more.

…and form JSON schema.

denniskigen

Great start, @Mwanje! I've left some feedback about a few things we could improve.

configuration/backend_configuration/ampathforms/procedure-history-form.json

denniskigen · 2025-09-24T09:26:03Z

configuration/backend_configuration/ampathforms/procedure-history-form.json

+                "rendering": "select",
+                "isSearchable": true,
+                "concept": "1651AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+                "answers": [


Is the plan to eventually include all procedures from the collection as possible answers for this field so we end up with a complete procedure catalog instead of just 4 sample procedures?

@denniskigen the plan is to include all procedures from the collection

Is this going to be done in this PR as well or we can do a follow PR

Is there an easier way we can maintain the set of answers here, e.g., by referring to a concept set or the existing concept answers? Inevitably for a real-world case this list will get long enough that maintaining it in JSON is likely impractical. @samuelmale Interested in your thoughts here.

Is there an easier way we can maintain the set of answers here, e.g., by referring to a concept set or the existing concept answers?

Yes! The form-engine infers a field's answers from the associated concept if the questionOptions.answers is empty. (Note that concept sets aren't supported)

configuration/backend_configuration/ampathforms/procedure-history-form.json

configuration/backend_configuration/encountertypes/encountertypes_core-demo.csv

Mwanje · 2025-09-24T13:52:18Z

@denniskigen have pushed a commit addressing comments

configuration/backend_configuration/ampathforms/procedure-history-form.json

denniskigen · 2025-09-25T09:24:45Z

configuration/backend_configuration/ampathforms/procedure-history-form.json

+                "rendering": "select",
+                "concept": "1732AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+                "answers": [
+                  {


Looking at the current duration units:

The ordering of units seems random. Could we order them logically (e.g., minutes, hours, days, weeks, months, years), either ascending or descending?

The validation currently only blocks durations greater than 100 years. Should we consider unit-specific limits (e.g., prevent excessive values in hours or minutes when those units are selected)?

Referring to this sample procedure list (~50 procedures):

Which time units are most relevant/commonly used for these procedures?

What's the optimal ordering for user experience?

Does the current validation logic fit typical use cases?

Are months and years realistic for procedure duration tracking, or should we limit to shorter timeframes?

I also think "Number of occurrences" is a completely separate question from "Duration". I.e., if I apply 3 bandages to a patient, that does need to be documented, but the procedure still took, say, 5 minutes regardless.

configuration/backend_configuration/ampathforms/procedure-history-form.json

denniskigen · 2025-10-01T12:44:53Z

Very useful context from @ibacher in the linked PR openmrs/openmrs-esm-patient-chart#2748 (comment).

ibacher · 2025-10-01T14:50:09Z

configuration/backend_configuration/ampathforms/procedure-history-form.json

+                {
+                  "type": "js_expression",
+                  "failsWhenExpression": "procedureDurationUnit === '1733AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' && Number(procedureDuration) > 1440",
+                  "message": "Duration cannot exceed 1440 minutes.. Change unit or reduce duration."
+                },


I'd suggest we'd want this to be more like 2 days (2880 minutes) rather than 24 hours, unless there's a way to input something like 24 hours + 30 minutes or the like.

ibacher · 2025-10-01T14:50:46Z

configuration/backend_configuration/ampathforms/procedure-history-form.json

+                {
+                  "type": "js_expression",
+                  "failsWhenExpression": "procedureDurationUnit === '1073AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' && Number(procedureDuration) > 52",
+                  "message": "Duration cannot exceed 52 weeks.. Change unit or reduce duration."
+                },
+                {
+                  "type": "js_expression",
+                  "failsWhenExpression": "procedureDurationUnit === '1074AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' && Number(procedureDuration) > 12",
+                  "message": "Duration cannot exceed 12 months.. Change unit or reduce duration."
+                }


I'm not sure we have a good reason for allowing durations in weeks, months or years?

ibacher · 2025-10-01T14:51:19Z

configuration/backend_configuration/ampathforms/procedure-history-form.json

+                  }
+                ]
+              },
+              "clearWhenExpression": "Number(procedureDuration) > 99 && (procedureDurationUnit === '1734AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')",


Why are other durations handled as validations, but this is a "clearWhenExpression"? It feels like we should use one tool for limits here.

Add sample OCL procedure concepts, procedure history encounter type, …

9117553

…and form JSON schema.

jabahum mentioned this pull request Sep 24, 2025

(feat) Add Procedure History to Patient Chart openmrs/openmrs-esm-patient-chart#2748

Open

3 tasks

denniskigen reviewed Sep 24, 2025

View reviewed changes

denniskigen changed the title ~~OMRS2025-Hackathon-Procedure-History~~ Add procedure history management system with encounter type and form Sep 24, 2025

denniskigen added omrs25hackathon Tasks from the OMRS 25 hackathon and removed omrs25hackathon Tasks from the OMRS 25 hackathon labels Sep 24, 2025

denniskigen requested review from VeronicaMuthee and gracepotma September 24, 2025 12:01

addressed PR comments

9072704

denniskigen requested a review from ibacher September 24, 2025 18:24

denniskigen reviewed Sep 25, 2025

View reviewed changes

configuration/backend_configuration/ampathforms/procedure-history-form.json Outdated Show resolved Hide resolved

denniskigen reviewed Sep 25, 2025

View reviewed changes

configuration/backend_configuration/ampathforms/procedure-history-form.json Outdated Show resolved Hide resolved

configuration/backend_configuration/ampathforms/procedure-history-form.json Outdated Show resolved Hide resolved

addressing PR comments

2f68a80

ibacher reviewed Oct 1, 2025

View reviewed changes

Add procedure history management system with encounter type and form #41

Are you sure you want to change the base?

Add procedure history management system with encounter type and form #41

Conversation

Mwanje commented Sep 17, 2025 • edited by denniskigen Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

denniskigen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

denniskigen Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Mwanje commented Sep 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

denniskigen commented Oct 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Mwanje commented Sep 17, 2025 •

edited by denniskigen

Loading

denniskigen Sep 24, 2025 •

edited

Loading