HIE Implementation Guide: HMIS to HIE Integration

Following these guidelines ensures your HMIS interfaces correctly with the HIE's critical components. Comptracks Systems built this guide from real-world SHA integration projects to help engineering teams plan and scope their own implementation.

Priority Levels

Icon	Level	Description
🔴	Critical	Essential functionality — must be implemented
🟠	Standard	Expected functionality — should be implemented
🟢	Advanced	Enhanced functionality — optional features

🔧 Core Requirements

Use Official APIs Critical

Requirement	Details
API Source	Use only APIs provided through the official portal
No Third-Party	Avoid unofficial interfaces or middleware
Data Exchange	All communication through official channels only

Best Practices: maintain up-to-date API documentation, implement proper authentication and security, monitor API usage and performance.

Direct HMIS Integration Critical

Requirement	Details
Implementation	Direct integration within HMIS itself
No Middleware	No external components or third-party systems
Native Functionality	All features built into the HMIS

👤 Client Registry Integration

1. Patient Registration Standard

Feature	Implementation Details
Registration Form	Implement patient registration functionality
ID Search	Search by ID number capability
PIN Management	Set default PIN, enable PIN changes
User Awareness	Inform patients about PIN for Afyayangu login

2. Patient Search Critical

Parameter	Required	Description
ID Number	Yes	National identification number
Full Name	Yes	Complete patient name
Date of Birth	Yes	Patient's date of birth
Phone Number	No	Contact phone number
Other Identifiers	No	As per API documentation

Enable comprehensive search functionality, display accurate results, and implement error handling for failed searches.

3. Patient Data Decryption Critical

Component	Requirement
Decryption Keys	Use AfyaLink-provided keys
Data Security	Encrypt all sensitive information
Key Management	Secure storage with access controls
Audit Logging	Log all decryption activities

4. Patient Data Mapping & Storage Standard

Field	Type	Description
CR ID	String	Client Registry identifier
ID Number	String	National ID
Full Names	String	Complete patient name
Date of Birth	Date	Patient DOB
Gender	Enum	Patient gender
Phone Number	String	Contact number

Store patient details locally after a successful search to eliminate repeated API calls, and map all required fields accurately.

5. Update Patient Standard

Feature	Details
Update Functionality	Enable information updates
Encryption	Send updates with encrypted PIN
Validation	Validate all update requests
Change Tracking	Track all patient modifications

6. Dependents Handling Standard

Dependent Type	Action
Spouse	Store and display as next of kin
Children	Register as dependents
Relationships	Map family connections clearly

7. Consent Workflow Advanced

Capture patient consent before processing requests, store consent linked to patient records, comply with privacy laws and regulations, and implement age-appropriate consent mechanisms.

🔍 Eligibility Check

1. Search Patient Eligibility Critical

Implement eligibility search functionality with clear visual status indicators, and show reasons and solutions when a patient is ineligible.

2. SHA Patient Visit Critical

Process flow: verify eligibility → initialize SHA visit → capture required parameters → confirm visit creation.

3. Display SHA Scheme Eligibility Standard

Scheme	Display Requirements
SHIF	Status, coverage period, benefit limits
ECCIF & PCIF	Active periods, waiting periods
POMF	Eligibility status, coverage details
ECDF	Active coverage, benefit information

Use color-coded eligibility status and easy-to-read benefit displays, with detailed information on hover or click.

🏥 Facility Registry Integration

1. Search Facility Critical

Parameter	Description
Facility Code	Unique facility identifier
Facility Name	Official facility name
Location	Geographic location
Level	Facility level (primary, secondary, tertiary)

2. Save Facility Details Standard

Store facility name, level, codes, location and contact details locally in the HMIS database, implement caching to reduce API calls, and ensure proper data mapping.

3. Use Facility Details Standard

Populate the organization resource in claims, ensure consistent facility information, and implement data validation and fallback mechanisms.

👨‍⚕️ Health Worker Registry Integration

1. Search Practitioner Critical

Search by ID number, registration number, or practitioner name.

2. Save Practitioner Details Standard

Store full names, license numbers, registration number, ID number and specialization.

3. Use Practitioner Details Standard

Populate the practitioner resource in claims, keep information consistent across claims, and handle updates and missing data appropriately.

💼 Claims Integration

1. SHA Codes Mapping Critical

Map SHA codes to your local database, keep coding consistent for SHA visits, validate codes before submission, and handle code version changes.

2. Map Preauth Services Critical

Flag services requiring preauthorization with visual indicators during service selection, and block the service until preauth is confirmed.

3. Send PreAuth Check Critical

Process flow: identify service requiring preauth → collect required information → submit preauth request → process and store response → proceed based on authorization status.

4. SHA Intervention Amounts Standard

Display the SHA payable amount per intervention using locally stored data, update amounts regularly, and indicate patient vs. SHA responsibility.

5. ICD-11 Search Critical

Approach	Benefits
API-based with caching	Always current, minimal storage
Local database	Fast, offline capability
Hybrid	Optimal performance and accuracy

6. Build Claim Bundle (Registries) Standard

Assemble patient information, facility details, and practitioner information from local storage, along with current visit details and system-generated claim metadata.

7. Build Claim Bundle (SHR, Services & Diagnosis) Critical

Include primary and secondary diagnoses (ICD-11), all procedures rendered, prescribed medications, and any additional required clinical information.

8. Claim Submission Standard

Validate claim data completeness, submit the claim to the HIE, receive and process the response, store the claim ID for tracking, and provide status feedback.

9. Poll Claim Status Critical

Regularly check status using the claim ID, handle all status codes appropriately, display clear visual indicators, and enable resubmission for rejections.

🚀 Advanced Features

Facility Level Context Advanced

Customize workflows based on facility capabilities, show appropriate options by facility level, hide unavailable features, and provide facility-specific guidance.

Service Filtering By Facility Level Advanced

Filter services by facility level, show only relevant services, prevent selection of unavailable services, and implement referral workflows.

✅ Production Readiness Requirements

To be eligible for production deployment, a system must complete 100% of all Critical (🔴) and Standard (🟠) components. Advanced (🟢) features are optional enhancements and are not required for production.

Integration Area	Required Components
Core Requirements	2
Client Registry	6
Eligibility Check	3
Facility Registry	3
Health Worker Registry	3
Claims Integration	9
Total Required	26