@openmrs/esm-patient-immunizations-app 11.3.1-pre.9342 → 11.3.1-pre.9344
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.turbo/turbo-build.log
CHANGED
package/README.md
CHANGED
|
@@ -1,4 +1,173 @@
|
|
|
1
1
|
# esm-patient-immunizations-app
|
|
2
2
|
|
|
3
|
-
The immunizations widget
|
|
3
|
+
The immunizations widget provides a visual, intuitive system for clinicians to record immunizations, track vaccination schedules, and monitor a patient's vaccination status.
|
|
4
4
|
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
This module is a patient chart widget that can be added to any patient chart dashboard. It provides two main views:
|
|
8
|
+
|
|
9
|
+
1. **Immunization Summary**: A detailed, collapsible table that groups immunizations by vaccine type. It provides an overview of the patient's vaccination history with expandable rows for more detail.
|
|
10
|
+
From this view, users can add new immunizations or edit/delete existing doses, which launches the immunization workspace form.
|
|
11
|
+
|
|
12
|
+
2. **Immunization History**: A separate card that provides a simple, chronological list of all immunizations the patient has received.
|
|
13
|
+
This card, in conjunction with the summary view, helps clinicians track whether a patient's next scheduled dose is upcoming or overdue.
|
|
14
|
+
|
|
15
|
+
## Key Features
|
|
16
|
+
|
|
17
|
+
### Enhanced Immunization Form
|
|
18
|
+
|
|
19
|
+
- **Comprehensive Data Entry**: A workspace form allows for recording new vaccinations with fields for:
|
|
20
|
+
- Vaccination Date
|
|
21
|
+
- Immunization (Vaccine Name)
|
|
22
|
+
- Dose Number
|
|
23
|
+
- Manufacturer
|
|
24
|
+
- Lot Number
|
|
25
|
+
- Expiration Date
|
|
26
|
+
- Next Dose Date
|
|
27
|
+
- Free-text Notes
|
|
28
|
+
- **Smart Validation**: Includes checks for future dates and ensures the vaccination date is on or after the patient's birth date.
|
|
29
|
+
- **Loading & Error States**: Provides clear user feedback during form submission and validation.
|
|
30
|
+
|
|
31
|
+
### Detailed Summary & History
|
|
32
|
+
|
|
33
|
+
- **Grouped Summary Table**: Displays a consolidated list of all vaccine types the patient has received. Each entry shows the vaccine name and details of the most recent dose.
|
|
34
|
+
- **Expandable Details**: Users can expand each vaccine entry to see a detailed history for that specific vaccine, including dose number, dates, lot number, manufacturer, notes, and actions.
|
|
35
|
+
- **Chronological History Card**: A separate view shows all immunization events sorted by date.
|
|
36
|
+
|
|
37
|
+
### Next Dose Tracking
|
|
38
|
+
|
|
39
|
+
- **Visual Indicators**: The system uses visual cues to highlight the status of upcoming vaccinations:
|
|
40
|
+
- 🔴 **Red flag**: Indicates an overdue or currently due vaccination.
|
|
41
|
+
- 🟢 **Green flag**: Indicates an upcoming vaccination.
|
|
42
|
+
- **Scheduling Logic**: The `Next Dose Date` field helps clinicians plan future appointments and prevents scheduling errors (e.g., setting a next dose date before the current vaccination date).
|
|
43
|
+
|
|
44
|
+
### Full Record Management
|
|
45
|
+
|
|
46
|
+
- **Edit Functionality**: Allows modification of existing immunization records. The form is pre-populated with existing data, and the vaccine name is locked to maintain data integrity.
|
|
47
|
+
- **Delete Functionality**: Individual immunization doses can be safely deleted after a confirmation prompt.
|
|
48
|
+
- **User Feedback**: Toast notifications confirm the success or failure of create, update, and delete operations.
|
|
49
|
+
|
|
50
|
+
## Configuration
|
|
51
|
+
|
|
52
|
+
### Available Widgets
|
|
53
|
+
|
|
54
|
+
This module registers several extensions that create the complete immunization feature. Here is a breakdown of the key widgets and how they are used:
|
|
55
|
+
|
|
56
|
+
1. **Immunizations Dashboard Link (`immunization-summary-dashboard`)**: Adds the "Immunizations" link to the patient chart's side navigation menu and automatically creates a dedicated dashboard page for immunization widgets.
|
|
57
|
+
|
|
58
|
+
2. **Immunization Summary Table (`immunization-details-widget`)**: The main collapsible table that groups immunizations by vaccine type. Automatically placed on the Immunizations Dashboard.
|
|
59
|
+
|
|
60
|
+
3. **Immunization History Card (`immunization-detailed-history-card`)**: A chronological list of all immunizations. Automatically placed on the Immunizations Dashboard.
|
|
61
|
+
|
|
62
|
+
4. **Immunization Overview Widget (`immunization-overview-widget`)**: This is a small, summary card intended for placement on other dashboards, like the main patient summary. It is **not assigned to a dashboard slot by default**.
|
|
63
|
+
|
|
64
|
+
To add the overview widget to the patient summary dashboard, add the following to your `extensions.json` configuration:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"name": "immunization-overview-widget",
|
|
69
|
+
"slot": "patient-chart-summary-dashboard-slot",
|
|
70
|
+
"order": 8
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Frontend Configuration
|
|
75
|
+
|
|
76
|
+
Configure the widget by setting values in your implementation's configuration file (typically `config.json` or via the System Administration module). The following parameters are available:
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
### Configurable Parameters Summary
|
|
81
|
+
|
|
82
|
+
| Parameter | Type | Description | Default |
|
|
83
|
+
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
84
|
+
| **`immunizationConceptSet`** | `string` | A UUID or concept mapping (e.g., `"CIEL:984"`) that resolves to a **concept set** containing all available vaccine concepts. | `"CIEL:984"` |
|
|
85
|
+
| **`sequenceDefinitions`** | `array` | Defines the **dose and booster schedules** for each vaccine. Each entry represents one vaccine and its sequence definitions. | See example below |
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
### Example Configuration
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"immunizationConceptSet": "CIEL:984",
|
|
94
|
+
"sequenceDefinitions": [
|
|
95
|
+
{
|
|
96
|
+
"vaccineConceptUuid": "783AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
|
|
97
|
+
"sequences": [
|
|
98
|
+
{ "sequenceLabel": "Dose-1", "sequenceNumber": 1 },
|
|
99
|
+
{ "sequenceLabel": "Dose-2", "sequenceNumber": 2 },
|
|
100
|
+
{ "sequenceLabel": "Dose-3", "sequenceNumber": 3 },
|
|
101
|
+
{ "sequenceLabel": "Dose-4", "sequenceNumber": 4 },
|
|
102
|
+
{ "sequenceLabel": "Booster-1", "sequenceNumber": 11 },
|
|
103
|
+
{ "sequenceLabel": "Booster-2", "sequenceNumber": 12 }
|
|
104
|
+
]
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Note**: Replace `vaccineConceptUuid` with your actual vaccine concept UUIDs.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
### Configuration Notes
|
|
115
|
+
|
|
116
|
+
- **Dose numbering convention**:
|
|
117
|
+
- `1–9` → Primary doses
|
|
118
|
+
- `11–19` → Booster doses
|
|
119
|
+
- If `sequenceDefinitions` is not provided, vaccines are treated as single-dose vaccines without predefined schedules.
|
|
120
|
+
- `sequenceLabel` values are used as translation keys in the UI for localization.
|
|
121
|
+
- You can add multiple vaccine definitions to represent your national or local immunization program.
|
|
122
|
+
|
|
123
|
+
## Backend Setup Requirements
|
|
124
|
+
|
|
125
|
+
The immunizations feature requires backend configuration in the OpenMRS [FHIR2 module](https://github.com/openmrs/openmrs-module-fhir2).
|
|
126
|
+
|
|
127
|
+
### Required Global Properties
|
|
128
|
+
|
|
129
|
+
- `fhir2.immunizationsEncounterTypeUuid` - UUID of the encounter type for immunization encounters
|
|
130
|
+
- `fhir2.administeringEncounterRoleUuid` - UUID of the encounter role for the administering provider
|
|
131
|
+
|
|
132
|
+
### Required Concept Mappings
|
|
133
|
+
|
|
134
|
+
The following CIEL concepts must be mapped:
|
|
135
|
+
|
|
136
|
+
| CIEL Code | Concept Name | Required |
|
|
137
|
+
|-----------|--------------|----------|
|
|
138
|
+
| CIEL:1421 | Immunization grouping concept | ✅ Required |
|
|
139
|
+
| CIEL:984 | Vaccine | ✅ Required |
|
|
140
|
+
| CIEL:1410 | Vaccination date | ✅ Required |
|
|
141
|
+
| CIEL:1418 | Dose number | ✅ Required |
|
|
142
|
+
| CIEL:1419 | Manufacturer | ✅ Required |
|
|
143
|
+
| CIEL:1420 | Lot number | ✅ Required |
|
|
144
|
+
| CIEL:165907 | Expiration date | ✅ Required |
|
|
145
|
+
| CIEL:161011 | Free text comment | ⚠️ Optional |
|
|
146
|
+
| CIEL:170000 | Date next dose | ⚠️ Optional |
|
|
147
|
+
|
|
148
|
+
## Implementation Checklist
|
|
149
|
+
|
|
150
|
+
### Backend Setup (Required)
|
|
151
|
+
|
|
152
|
+
- [ ] Configure global property `fhir2.immunizationsEncounterTypeUuid` with encounter type UUID
|
|
153
|
+
- [ ] Configure global property `fhir2.administeringEncounterRoleUuid` with encounter role UUID
|
|
154
|
+
- [ ] Verify all required CIEL concept mappings exist (CIEL:1421, CIEL:984, CIEL:1410, CIEL:1418, CIEL:1419, CIEL:1420, CIEL:165907)
|
|
155
|
+
- [ ] Verify optional CIEL concept mappings if using notes or next dose date features (CIEL:161011, CIEL:170000)
|
|
156
|
+
|
|
157
|
+
### Frontend Setup (Required)
|
|
158
|
+
|
|
159
|
+
- [ ] Configure `immunizationConceptSet` to point to your implementation's concept set for vaccines.
|
|
160
|
+
- [ ] Configure `sequenceDefinitions` for all vaccines that have a multi-dose or booster schedule.
|
|
161
|
+
- [ ] Set user permissions for recording and managing immunizations.
|
|
162
|
+
|
|
163
|
+
### Optional Customizations
|
|
164
|
+
|
|
165
|
+
- [ ] Add or modify `sequenceDefinitions` to match local or national immunization programs.
|
|
166
|
+
- [ ] Add translations for custom `sequenceLabel` values if supporting multiple languages.
|
|
167
|
+
|
|
168
|
+
## Key Files for Customization
|
|
169
|
+
|
|
170
|
+
- **`src/config-schema.ts`**: Main configuration for vaccine concept sets and dose schedules.
|
|
171
|
+
- **`src/immunizations/immunizations-detailed-summary.component.tsx`**: The main component for the immunization summary view.
|
|
172
|
+
- **`src/immunizations/immunization-history-dashboard.component.tsx`**: The component for the chronological history view.
|
|
173
|
+
- **`src/immunizations/immunizations-form.workspace.tsx`**: The workspace form for adding and editing immunizations.
|