n8n-nodes-openmrs

Community node for n8n providing OpenMRS FHIR R4 integration with intelligent patient search, clinical data access, and healthcare workflow automation.

---

What's New in v1.2.0

Smart Patient Search - No more memorizing UUIDs!

• Search by OpenMRS ID: 131280865
• Search by Name: Patricia Lewis (partial matching)
• Search by Phone: +254712345678

---

Features

Intelligent Patient Lookup

Real-world clinics don't use UUIDs. Search patients the way healthcare workers actually do:

• By Identifier - OpenMRS ID, National ID, Facility Number
• By Name - First name, last name, or partial matches
• By Phone - Mobile number in any format
• By UUID - For system integrations

Complete FHIR R4 Coverage

Access all essential clinical resources:

Resource	What You Get	Common Use Cases
Patient	Demographics, identifiers, contacts	Registration, identity verification
Encounter	Visits, admissions, consultations	Attendance tracking, visit history
Observation	Labs, vitals, diagnostic results	Trend analysis, clinical alerts
Diagnostic Report	Imaging, pathology reports	Disease progression tracking
Condition	Diagnoses, active problems	Differential diagnosis, comorbidities
Medication Statement	Current & past medications	Treatment history, drug interactions

Developer-Friendly

• Simple Auth - HTTP Basic Authentication
• Pagination - Handle large datasets efficiently
• Error Handling - Clear error messages and continue-on-fail support
• Custom API Calls - Direct access to any OpenMRS FHIR endpoint

Built for Global Health

• Optimized for low-bandwidth environments
• Works with OpenMRS 2.x and 3.x
• Compatible with DHIS2 workflows
• Supports both cloud and on-premise deployments

---

Installation

Via n8n Community Nodes (Recommended)

1. Open n8n
2. Go to Settings → Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-openmrs
5. Click Install

Via npm

npm install n8n-nodes-openmrs

From Source

git clone https://github.com/monfortbrian/n8n-nodes-openmrs.git
cd n8n-nodes-openmrs
npm install
npm run build
npm link

---

Quick Start

1. Configure Credentials

1. In n8n, go to Credentials → New
2. Search for OpenMRS API
3. Configure:
   • Base URL: https://demo.openmrs.org/openmrs (include /openmrs)
   • Username: admin
   • Password: Admin123
4. Test & Save

2. Search Patient by OpenMRS ID

Add Node → OpenMRS
├─ Resource: Patient
├─ Operation: Search by Identifier
└─ Identifier: 131280865

Result: Complete patient record instantly

3. Find Patient by Name

Add Node → OpenMRS
├─ Resource: Patient
├─ Operation: Search by Name
└─ Name: Patricia

Result: All patients with "Patricia" in their name

---

Examples

Example 1: Patient Search by ID (Real-World)

Instead of this (nobody remembers):

UUID: 7826f08a-0258-4fb1-ba69-2af192f392db

Do this:

OpenMRS ID: 131280865

n8n Workflow:

1. Add OpenMRS node
2. Resource: Patient
3. Operation: Search by Identifier
4. Identifier: 131280865
5. Execute

Output: Full patient FHIR record

---

Example 2: Get Patient Lab Results

1. Add OpenMRS node
2. Resource: Observation
3. Operation: Get Many
4. Patient UUID: 7826f08a-0258-4fb1-ba69-2af192f392db
5. Limit: 50
6. Execute

Output: Up to 50 most recent lab results with values, units, reference ranges

---

Example 3: Track Patient Visit History

1. Add OpenMRS node
2. Resource: Encounter
3. Operation: Get Many
4. Patient UUID: 7826f08a-0258-4fb1-ba69-2af192f392db
5. Return All: true
6. Execute

Output: Complete visit timeline from first to last encounter

---

Example 4: Custom FHIR Query

Use the Custom API Call resource for advanced queries:

1. Add OpenMRS node
2. Resource: Custom API Call
3. HTTP Method: GET
4. Endpoint: /ws/fhir2/R4/Patient
5. Query Parameters:
   - name: birthdate
   - value: gt1990-01-01
6. Execute

Output: All patients born after January 1, 1990

---

Real-World Use Cases

Clinical Workflows

Patient Admission Dashboard

Webhook Trigger
→ OpenMRS: Search by OpenMRS ID
→ OpenMRS: Get Encounters (last 6 months)
→ OpenMRS: Get Observations (recent labs)
→ Code: Calculate risk scores
→ Display: Admission summary

Lost-to-Follow-Up Recovery

Schedule (weekly)
→ OpenMRS: Get All Patients on ART
→ Code: Filter last visit > 28 days
→ OpenMRS: Search by Phone
→ SMS: "Medication ready for pickup"
→ DHIS2: Update tracker

Data Analytics

Disease Surveillance

Schedule (every 6 hours)
→ OpenMRS: Get Conditions (last 6h)
→ Code: Filter cholera, measles, meningitis
→ Code: Check outbreak threshold
→ DHIS2: Post to IDSR module
→ SMS: Alert district officer

Lab Turnaround Time Monitoring

OpenMRS: Observation created
→ Calculate: Order time - Result time
→ IF > 48 hours
  → Alert lab manager
  → DHIS2: Post performance indicator

Global Health

• HIV/TB treatment adherence tracking
• Maternal health visit reminders
• Vaccine defaulter identification
• Stockout prevention for ARVs

---

API Reference

Supported Resources

• Patient - Demographics, identifiers
• Encounter - Visits, admissions
• Observation - Labs, vitals, diagnostics
• Diagnostic Report - Imaging, pathology
• Condition - Diagnoses, problems
• Medication Statement - Prescriptions, dispensing
• Custom API Call - Any FHIR endpoint

Patient Operations

• Search by Identifier - OpenMRS ID, National ID
• Search by Name - Partial name matching
• Search by Phone - Phone number search
• Get - Retrieve by UUID
• Get Many - Retrieve all (paginated)

Other Resource Operations

• Get - Retrieve single resource by UUID
• Get Many - Retrieve all for patient (paginated)

Pagination

All Get Many and search operations support:

• Return All: true/false
• Limit: 1-100 (default: 50)

---

FHIR Endpoints Used

GET /ws/fhir2/R4/Patient?identifier={id}
GET /ws/fhir2/R4/Patient?name={name}
GET /ws/fhir2/R4/Patient?telecom={phone}
GET /ws/fhir2/R4/Patient/{uuid}
GET /ws/fhir2/R4/Encounter?patient={uuid}&_count=50
GET /ws/fhir2/R4/Observation?patient={uuid}&_count=50
GET /ws/fhir2/R4/DiagnosticReport?patient={uuid}&_count=50
GET /ws/fhir2/R4/Condition?patient={uuid}&_count=50
GET /ws/fhir2/R4/MedicationStatement?patient={uuid}&_count=50

---

Compatibility

• n8n: 0.187.0 or higher
• OpenMRS: 2.3+ with FHIR2 module
• Node.js: 18.0.0 or higher

---

Troubleshooting

Node doesn't appear

# Check installation
npm list -g n8n-nodes-openmrs

# Clear cache
rm -rf ~/.n8n/cache

# Restart n8n
n8n start

Authentication fails

• Include /openmrs in Base URL
• Verify credentials in OpenMRS
• Check FHIR2 module is enabled

Empty search results

• Patient may not exist with that identifier
• Try different search criteria
• Verify FHIR2 module configuration

Build errors (for developers)

# Clean rebuild
rm -rf node_modules dist
npm install
npm run build

---

Development

Building

npm run build      # Compile TypeScript
npm run dev        # Watch mode
npm run lint       # Check code quality
npm run lintfix    # Auto-fix issues

Testing Locally

# Build and link
npm run build
npm link

# Start n8n
n8n start

# Test in n8n UI
# Your node appears as "OpenMRS"

Publishing

# Bump version
npm version minor  # 1.1.0 → 1.2.0

# Publish
npm publish

# Push to GitHub
git push origin main --tags

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push: git push origin feature/amazing-feature
5. Open Pull Request

---

Changelog

[1.2.0] - 2026-03-05

Added

• Patient search by OpenMRS ID/identifier
• Patient search by name (partial matching)
• Patient search by phone number
• Custom API Call resource for advanced queries

Changed

• Improved error messages
• Better TypeScript types
• Updated documentation

[1.1.0] - 2026-03-03

Added

• 6 FHIR resources (Patient, Encounter, Observation, etc.)
• Get and Get Many operations
• Pagination support

[1.0.0] - 2026-03-01

Added

• Initial release
• Basic FHIR R4 support

---

License

MIT License

Copyright © 2026 Monfort Brian N.

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• n8n Community: n8n Forum

---

Acknowledgments

Built for healthcare workers in low-resource settings. Enabling better patient outcomes through data interoperability and workflow automation.

Made with ❤️ for global health