Medic / CHT Feedback → openIMIS - V1
This workflow outlines how Community Health Workers (CHWs) using the CHT platform can send feedback on health services covered by insurance claims into openIMIS, leveraging FHIR Communication resources through the openHIM middleware.
CHT Feedback → openIMIS workflow 1
Trigger
Feedback is submitted by the CHT platform either:
In batch mode (e.g., at the end of each workday), or
In real-time (on-demand submission).
Workflow on CHT Side
1. Retrieve InsureeUUID by Insuree Code
CHT sends a request to openHIM to resolve the unique internal identifier:
GET /fhir/Patient?identifier={insureeCode} Purpose: Validate the identity of the Insuree and obtain their UUID (
Patient.id)Outcome:
If found → Continue
If not found → openHIM returns
OperationOutcome; stop and log rejection
2. Retrieve Latest ClaimUUID by InsureeUUID
Once InsureeUUID is retrieved, CHT fetches the most recent Claim for this patient:
GET /fhir/Claim?patient=Patient/{insureeUUID}&_sort=-created&_count=1 example in openIMIS context:
Latest claim by Patient
To view above resource(s), one must get valid token from FHIR api (bearer token jwt)
sample response for single claim:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http%3A%2F%2Fdemoimis.tinker.com.np%2Fapi%2Fapi_fhir_r4%2FClaim%2F%3Fpatient%3D42584440-2c16-46b6-9092-b8d3f439d6ba%26_sort%3D-created%26_count%3D1"
}
],
"entry": [
{
"fullUrl": "http://demoimis.tinker.com.np/api/api_fhir_r4/Claim/96c604a1-4d71-4c37-bd5a-867595863102",
"resource": {
"resourceType": "Claim",
"id": "96c604a1-4d71-4c37-bd5a-867595863102",
"identifier": [
{
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "96c604a1-4d71-4c37-bd5a-867595863102"
},
{
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "Code"
}
]
},
"value": "CID00001"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-visit-type",
"code": "O",
"display": "Other"
}
]
},
"use": "claim",
"patient": {
"reference": "Patient/42584440-2c16-46b6-9092-b8d3f439d6ba",
"type": "Patient",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "42584440-2c16-46b6-9092-b8d3f439d6ba"
},
"display": "105000002"
},
"billablePeriod": {
"start": "2019-02-03",
"end": "2019-02-03"
},
"created": "2019-02-03",
"enterer": {
"reference": "Practitioner/b4ea00c1-c7d6-4eaa-96a3-60e2d36484b3",
"type": "Practitioner",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "b4ea00c1-c7d6-4eaa-96a3-60e2d36484b3"
},
"display": "VIDS0011"
},
"provider": {
"reference": "Organization/5c08e764-04ed-42a0-bbea-fe0ea4c08a3f",
"type": "Organization",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "5c08e764-04ed-42a0-bbea-fe0ea4c08a3f"
},
"display": "VIDS001"
},
"priority": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/processpriority",
"code": "normal",
"display": "Normal"
}
]
},
"diagnosis": [
{
"sequence": 1,
"diagnosisCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/diagnosis-ICD10-level1",
"code": "A009 Cholera, unspecified",
"display": "Cholera, unspecified"
}
]
}
}
],
"insurance": [
{
"sequence": 1,
"focal": true,
"coverage": {
"reference": "Coverage/0673a137-401e-46e4-be28-f21f649b8eb0",
"type": "Coverage",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "0673a137-401e-46e4-be28-f21f649b8eb0"
}
}
}
],
"item": [
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",
"valueReference": {
"reference": "Medication/5b086a53-09ec-49e8-b8c6-dc5a127c2694",
"type": "Medication",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "5b086a53-09ec-49e8-b8c6-dc5a127c2694"
}
}
}
],
"sequence": 1,
"category": {
"text": "item"
},
"productOrService": {
"text": "0182"
},
"quantity": {
"value": 2.0
},
"unitPrice": {
"value": 10.0,
"currency": "$"
}
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",
"valueReference": {
"reference": "ActivityDefinition/488d8bcb-5b88-438c-9077-f177f6f32626",
"type": "ActivityDefinition",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "488d8bcb-5b88-438c-9077-f177f6f32626"
}
}
}
],
"sequence": 2,
"category": {
"text": "service"
},
"productOrService": {
"text": "A1"
},
"quantity": {
"value": 1.0
},
"unitPrice": {
"value": 400.0,
"currency": "$"
}
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",
"valueReference": {
"reference": "ActivityDefinition/e437f7e6-fbe4-40f5-aa1b-13c0b32d6ca9",
"type": "ActivityDefinition",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "e437f7e6-fbe4-40f5-aa1b-13c0b32d6ca9"
}
}
}
],
"sequence": 3,
"category": {
"text": "service"
},
"productOrService": {
"text": "I113"
},
"quantity": {
"value": 1.0
},
"unitPrice": {
"value": 1250.0,
"currency": "$"
}
}
],
"total": {
"value": 1670.0,
"currency": "$"
}
}
}
]
}
{
"resourceType": "ClaimResponse",
"id": "8f08cd42-025b-47bf-bb7a-04211fd51ced",
"identifier": [
{
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "8f08cd42-025b-47bf-bb7a-04211fd51ced"
},
{
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "Code"
}
]
},
"value": "569"
}
],
"status": "active",
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-visit-type",
"code": "O",
"display": "Other"
}
]
},
"use": "claim",
"patient": {
"reference": "Patient/d8393487-c3aa-4d3a-b56f-82f9b3b47a46",
"type": "Patient",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "d8393487-c3aa-4d3a-b56f-82f9b3b47a46"
}
},
"created": "2025-06-23",
"insurer": {
"reference": "openIMIS"
},
"requestor": {
"reference": "Practitioner/53d8bd54-f155-4dec-8564-8045c199dc3c",
"type": "Practitioner",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "53d8bd54-f155-4dec-8564-8045c199dc3c"
}
},
"request": {
"reference": "ClaimV2/8f08cd42-025b-47bf-bb7a-04211fd51ced",
"type": "ClaimV2",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "8f08cd42-025b-47bf-bb7a-04211fd51ced"
}
},
"outcome": "complete",
"item": [
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",
"valueReference": {
"reference": "ActivityDefinition/488d8bcb-5b88-438c-9077-f177f6f32626",
"type": "ActivityDefinition",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "488d8bcb-5b88-438c-9077-f177f6f32626"
},
"display": "A1"
}
}
],
"itemSequence": 1,
"adjudication": [
{
"category": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-status",
"code": "1",
"display": "rejected"
}
]
},
"reason": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-rejection-reasons",
"code": "7",
"display": "FAMILY"
}
]
},
"amount": {
"value": 400,
"currency": "$"
},
"value": 1
}
]
}
]
}
Purpose: Get the latest claim ID (
Claim.id) for the given insureeOutcome:
If found → Proceed to feedback
If not found → openHIM returns
OperationOutcome; stop and log rejection
Submit Feedback to openIMIS via openHIM
If both InsureeUUID and ClaimUUID are valid, the CHT backend submits a FHIR Communication:
POST /fhir/Communication Payload Includes:
Communication.subject:"Patient/{insureeUUID}"Communication.basedOn:"Claim/{claimUUID}"Communication.payload: Textual feedbackCommunication.extension: Custom metadata (e.g., feedback type, urgency, tags)
openIMIS communication Payload
basically now, openIMIS asks 4 questions to insuree Q/A
Subscription response
{
"resourceType" : "Communication",
"id" : "Claim001Communication",
"meta" : {
"profile" : [
"https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/openimis-communication"
]
},
"status" : "completed",
"subject" : {
"reference" : "Patient/{insureeUUID}"
},
"about" : [
{
"reference" : "Claim/{claimUUID}"
}
],
"payload" : [
{
"extension" : [
{
"url" : "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code" : "CareRendered"
}
]
}
}
],
"contentString" : "yes"
},
{
"extension" : [
{
"url" : "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code" : "PaymentAsked"
}
]
}
}
],
"contentString" : "no"
},
{
"extension" : [
{
"url" : "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code" : "DrugPrescribed"
}
]
}
}
],
"contentString" : "yes"
},
{
"extension" : [
{
"url" : "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code" : "DrugReceived"
}
]
}
}
],
"contentString" : "yes"
},
{
"extension" : [
{
"url" : "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept" : {
"coding" : [
{
"system" : "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code" : "Asessment"
}
]
}
}
],
"contentString" : "4"
}
]
}
Response after feedback is given
201 Response is obtained after successful, also the API will provide uuid of feedback basically shown below: “63b3db4c-7533-4af5-95a0-e57d5b08c9fe"
{
"resourceType": "Communication",
"identifier": [
{
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "63b3db4c-7533-4af5-95a0-e57d5b08c9fe"
}
],
"status": "completed",
"subject": {
"reference": "Patient/35abe9e9-300e-4d50-aaac-d8c3a0a57f4a",
"type": "Patient",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "35abe9e9-300e-4d50-aaac-d8c3a0a57f4a"
},
"display": "121212"
},
"about": [
{
"reference": "Claim/32839bc9-7dd5-424c-a07f-35d56014473f",
"type": "Claim",
"identifier": {
"type": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
"code": "UUID"
}
]
},
"value": "32839bc9-7dd5-424c-a07f-35d56014473f"
},
"display": "UPDH0002"
}
],
"payload": [
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code": "CareRendered"
}
]
}
}
],
"contentString": "yes"
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code": "PaymentAsked"
}
]
}
}
],
"contentString": "no"
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code": "DrugPrescribed"
}
]
}
}
],
"contentString": "yes"
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code": "DrugReceived"
}
]
}
}
],
"contentString": "yes"
},
{
"extension": [
{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [
{
"system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/feedback-payload",
"code": "Asessment"
}
]
}
}
],
"contentString": "4"
}
]
}openHIM Mediator: Validation & Routing
The openHIM CHT Feedback mediator handles:
Schema validation
Reference integrity checks (
Claim.id,Patient.id)Payload enrichment or transformation (if needed)
Returns
OperationOutcomeif invalid
openIMIS Processing
openIMIS:
Stores the feedback and links it to the correct claim
Saves metadata in
json_extcolumn for flexible UI rendering and downstream analysis
Acknowledgment & Logging
openIMIS replies:
201 Createdfor success400or422for validation issues
openHIM logs:
Request trace (FHIR bundles)
Response codes and error messages
Rejected feedbacks for admin follow-up
FHIR Resources Used
Resource | Purpose |
|---|---|
| Used to resolve the |
| Used to find latest claim using |
| Feedback container sent to openIMIS |
| Flexible metadata saved in openIMIS |
Diagram
CHT Feedback → openIMIS workflow 2
This workflow enables Medic / CHT to subscribe to claim validation events from openIMIS using the FHIR Subscription resource. When a claim is validated (Claim.status = validated), openIMIS notifies CHT. This notification triggers the creation of a feedback collection task/form on the CHT platform for the relevant Community Health Worker (CHW).
This is a one-way event-driven integration: from openIMIS → CHT via FHIR Subscription + rest-hook notification.
Trigger
Claim is validated in openIMIS.
Actors
Actor Role | System Name | Description |
|---|---|---|
Subscriber | CHT Platform | Subscribes to claim validation events to initiate feedback form workflows |
Publisher | openIMIS | Emits FHIR |
Interoperability Layer | openHIM | Handles routing, subscription registry, and transformation if needed |
Workflow Steps
Step | System | Action |
|---|---|---|
1 | CHT | Submits FHIR |
2 | openIMIS | Stores and activates subscription |
3 | openIMIS | Upon validation of a |
4 | openHIM | Forwards validated claim data (if acting as proxy/middleware) |
5 | CHT | Receives claim data and triggers CHW form/task generation |
6 | CHW (via CHT) | Receives notification in-app, fills feedback form |
7 | CHT | Sends completed feedback form as |
8 | openHIM | Validates and forwards to openIMIS |
9 | openIMIS | Saves |
FHIR Resources & API Calls
1. Subscription (CHT → openIMIS)
POST /fhir/Subscription
{
"resourceType": "Subscription",
"status": "active",
"reason": "Receive validated claims for feedback",
"criteria": "Claim?status=validated",
"channel": {
"type": "rest-hook",
"endpoint": "https://cht.myorg.org/hooks/claim-validation",
"payload": "application/fhir+json",
"header": ["Authorization: Bearer {cht-jwt}"]
}
}
2. Notification Payload (openIMIS → CHT)
This will typically be a Claim or a Bundle resource with full details of the validated claim.
3. Feedback Submission (CHT → openIMIS)
POST /fhir/Communication Payload example:
{
"resourceType": "Communication",
"status": "completed",
"subject": { "reference": "Patient/{insureeUUID}" },
"about": [{ "reference": "Claim/{claimUUID}" }],
"payload": [
{
"extension": [{
"url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/communication-payload-type",
"valueCodeableConcept": {
"coding": [{ "system": ".../feedback-payload", "code": "CareRendered" }]
}
}
],
"contentString": "yes"
}, ... ] }
Preconditions
openIMIS must support the
Subscriptionresource (FHIR R4) for Claim ManagementClaim validation updates must trigger event emitters
CHT must expose a secure
rest-hook-compliant HTTPS endpoint
Diagram
Did you encounter a problem or do you have a suggestion?
Please contact our Service Desk
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. https://creativecommons.org/licenses/by-sa/4.0/