Medic / CHT Feedback - Claim Subscription → openIMIS Interoperability

This page documents the interoperability process between Medic / CHT and openIMIS for managing claim validation notifications. The workflow leverages the FHIR Subscription resource to notify CHT when a claim’s status changes to validated, enabling CHWs to provide timely feedback.

Purpose

Enable CHT to subscribe to Claim validation events in openIMIS and automatically receive notifications when a claim reaches a validated state (Claim.status=validated). This allows CHT to trigger feedback collection workflows linked to validated claims.

Trigger

The trigger for this workflow is a change in claim status in openIMIS to validated.

Workflow

Example Use Case

A Community Health Worker (CHW) uses the CHT platform to subscribe to claim validation events from openIMIS. When a claim is validated, openIMIS sends a notification to CHT, which then triggers a feedback task for the CHW.

Workflow Maturity

Newly Defined

Workflow is specified and approved. Initial implementation in progress.

Referenced Standards

HL7 FHIR Subscription Resource: https://hl7.org/fhir/subscription.html
HL7 FHIR Financial Module (Claims): http://hl7.org/fhir/financial-module.html

Assumptions & Prerequisites

The Subscription process uses existing Patient Identity Management (via openIMIS FHIR API).
Unique insuree identifiers are already assigned and managed by openIMIS.
openHIM (if present) validates and routes FHIR messages (syntax and security).
CHT provides an HTTPS endpoint to receive subscription notifications securely.
openIMIS is extended to emit notifications when Claim.status=validated.

Actors

POS (CHT)	The Community Health Toolkit captures a feedback.
IOL (openHIM)	Mediates transactions between CHT and openIMIS, ensuring interoperability.
FIS (openIMIS)	Manages data on beneficiaries, claims, and coverage in the Financing and Insurance System.

Validations

The Interoperability Layer (IOL) should validate:
- Syntax of FHIR Subscription requests
- Security (OAuth2/JWT authentication)
- Notification delivery (e.g., retry on failure)
openIMIS must validate:
- The presence of active subscriptions before emitting notifications
- The structure of outbound Claim resource payloads

1. Subscribe to Claim Validation Events

CHT submits a FHIR Subscription resource to openIMIS via openHIM
Developer Documentation: openIMIS Subscription API | Step 2.2: Create a Subscription

2. Claim Validation in openIMIS

When a claim is validated in openIMIS (Claim.status changes to validated):

openIMIS identifies matching active subscriptions
openIMIS sends a notification to the subscriber (CHT)

3. Send Claim Validation Notification

openIMIS sends a notification to the CHT endpoint defined in the subscription

Developer Documentation: openIMIS Subscription API | 4. Receiving Webhook Notifications

4. CHT Processes Notification

Upon receiving the notification:

CHT retrieves full claim details (if needed) using:

GET /fhir/Claim/{claimUUID}

CHT creates a feedback task/form for the responsible CHW
The CHW is notified to complete the feedback form

5. Feedback Submission (CHT → openIMIS)

Once feedback is collected, CHT sends it as a FHIR Communication:

POST /fhir/Communication

FHIR Resources & API Calls

API Call	Purpose

API Call	Purpose
`POST /fhir/Subscription`	Register claim validation subscription
`Notification to CHT (REST hook)`	Notify CHT of validated claim
`GET /fhir/Claim/{claimUUID}`	Fetch detailed claim information (optional)
`POST /fhir/Communication`	Submit CHW feedback to openIMIS

FHIR Resources Used

Resource	Purpose

Resource	Purpose
`Subscription`	Registers interest in claim validation events
`Claim`	Represents validated claims triggering notifications
`Communication`	Used by CHT to submit CHW feedback

Source code

(link to permanent text in https://www.websequencediagrams.com/)

title Feedback collection
participant PoS
participant IOL
participant FIS

note over PoS, FIS
Assumes that feedback or querying of CR is done here
end Note

PoS->IOL: [2] Claim Subscription request
IOL->FIS: [3] Forward Claim Subscription request
FIS->FIS: [4] Claim Subscription Management

alt Validated Claim
  FIS->FIS: [5] Claim Validation
  FIS->PoS: [7] Send Notification on Claim Validation
  opt
	PoS->IOL: [8] * Claim Request
	IOL->FIS: [9] * Forward Claim request
  end
  PoS->PoS: [11] Collect patient's Feedback on claim record
  PoS->IOL: [12] Communication request
  IOL->FIS: [13] Forward Claim Subscription request
end

#	Interaction	Endpoint	Data	Transaction Options

#	Interaction	Endpoint	Data	Transaction Options
2	Claim Subscription request	IOL	FHIR `Subscription` (CHT → openHIM)	FHIR Subscription
3	Forward Claim Subscription request	FIS	FHIR `Subscription` (openHIM → openIMIS)
4	Claim Subscription Management	FIS	Internal: Manage active subscriptions	Persist subscription and handle criteria filtering
5	Claim Validation	FIS	Internal: Claim status updated to `validated`	Triggers notification logic for active subscriptions
6	Send Notification on Claim Validation	PoS	FHIR `Claim` (openIMIS → CHT)	FHIR Claim
7	Claim Request (optional)	IOL	FHIR `Claim` (CHT → openHIM)	Fetch full claim details
8	Forward Claim Request (optional)	FIS	FHIR `Claim`
9	Collect patient’s feedback	PoS	Internal: CHW collects and prepares feedback	Feedback form is populated based on validated claim
10	Communication request (Feedback)	IOL	FHIR `Communication` (CHT → openHIM)	FHIR Communication
11	Forward Communication request	FIS	FHIR `Communication` (openHIM → openIMIS)	Custom metadata stored in `json_ext` for flexible rendering in openIMIS

Starting version :

Medic / CHT Feedback → openIMIS - V1