Skip to content

OpenMRS Android App ‐ Adoption documentation

Jump to bottom
Michaël Bontyes edited this page Jan 19, 2026 · 1 revision

OpenMRS Android FHIR App: Contributor & Adopter Overview

Vision and Core Features

  • Mobile OpenMRS companion built on Android FHIR to sync clinical data (patients, encounters, observations, locations) with OpenMRS servers using either Basic Auth or OAuth2/OpenID Connect, configurable through local.properties.

  • Offline-first synchronization with configurable FHIR search URLs for incremental and first-time downloads, including patient-list scoping by location or cohort type to keep device datasets targeted and manageable.

  • Configurable clinical workflows through FHIR Questionnaires for patient registration and encounter capture, including optional review pages and reusable screener templates that can be customized or sourced from server assets.

  • Patient list scoping and cohort selection allowing implementers to constrain downloads and workflows by OpenMRS Group definitions.

  • Diagnostic and support tooling via in-app export of logs protected by optional passwords and directed to a configurable support email, easing field support and compliance needs.

  • Application diagnostics collection including device/app logs, sync summaries, and environment metadata, exportable to a designated support email for rapid debugging.

  • Offline biometric login support enabling secure, encrypted session unlock using Android BiometricPrompt with locally stored encrypted tokens.

  • Interoperability extensions: documented OpenMRS-specific FHIR extensions for identifiers, person attributes, group scoping, observation grouping, and encounter screener flags ensure payloads align with OpenMRS expectations while leveraging standard FHIR structures.

Application Feature Overview

The OpenMRS Android FHIR application provides a comprehensive set of user-facing features that support clinical workflows, patient management, offline-first data capture, and transparent synchronization.

Core Features

  1. Patient Registration
    Capture new patient demographics using customizable FHIR Questionnaires, supporting OpenMRS identifier rules and offline registration.

  2. Location Selection
    Choose the active clinical location for registrations, patient lists, encounters, and sync scoping.

  3. OpenMRS Identifier Selection
    Configure or select identifier types required during patient creation, aligned with OpenMRS identifier extension rules.

  4. Synchronization
    Bidirectional offline-first sync of patients, encounters, observations, and related resources---supporting incremental sync, Group-based scoping, and conflict-minimized merging.

  5. Patient Edit
    Modify patient demographic details while preserving OpenMRS identifier and attribute mappings.

  6. Visit / Encounter Edit
    Reopen and update encounters or visits using questionnaire-driven forms, with full parent/child Observation reconstruction.

  7. Fast Data Entry / Group Session Entry
    High-throughput screening and clinical data entry workflows using shared screener templates and patient lists.

  8. Sync Info Screen
    Provides visibility into sync history, resource download/upload counts, and pending operations for debugging and monitoring.

  9. Unsynced Resource Info Screen
    Shows locally stored resources awaiting upload, supporting field workflows and troubleshooting of partial or failed syncs.

  10. Patient List Selection (OpenMRS Cohorts)
    Select patient lists powered by OpenMRS Group resources or cohort-type filtering, enabling targeted workflows such as ward-based rounding, CHW assignments, or screening events.

  11. Application Diagnostics Collection & Email to Developer
    Export logs, sync metadata, crash traces, and environment details---protected by optional password---to a configurable support email for rapid troubleshooting.

  12. Offline Biometric Login Support
    Authenticate securely even without internet access using Android biometric hardware; session tokens are encrypted via Android Keystore-backed keys and unlocked locally after successful biometric verification.

FHIR Implementation Details

  • Sync configuration uses explicit resource search URLs (e.g., _sort=_lastUpdated) and first-sync overrides to control payload breadth. The client deduplicates by resource type before enqueueing downloads, preventing redundant broad queries on subsequent syncs.

  • Patient-list scoping leverages FHIR Group searches with optional location and cohort-type parameters to tailor downloads per site and cohort, aligning with OpenMRS group-based patient lists.

  • Observation grouping semantics rely on the observation-child extension to rebuild parent/child Observation hierarchies extracted from questionnaires, preserving OpenMRS-compatible obs groups and repeat structures.

  • Encounter screener composition uses the show-screener extension to lift selected questionnaire items into a shared screener template, giving implementers a consistent pre-encounter triage experience while keeping the main form intact.

Challenges and Design Considerations

  • Balancing payload size vs. completeness: Filtering strategies compare _include/_revinclude, _has with Group membership, and potential $everything use; each carries trade-offs in paging support, dataset volume, and backend setup effort.

  • Maintaining data fidelity across edits: Complex parent/child Observation reuse and tokenized matching are necessary to avoid ID churn and stale parent groups during encounter edits, reflecting OpenMRS' requirements for structured obs trees.

  • Environment alignment: Correct port/hostname mapping for Keycloak and the OpenMRS gateway, plus discovery/base URL accuracy, are critical to prevent authentication and sync failures, especially in multi-host setups (e.g., localhost vs. 10.0.0.2).

OpenMRS Compatibility Highlights

  • Uses OpenMRS FHIR extensions to encode location-bound identifiers, person attributes, group scoping, and observation grouping, ensuring server-side compatibility and predictable analytics behavior.

  • Supports OpenMRS-specific login flows (Basic Auth or OAuth2 via Keycloak), with guidance for predefined users and logout endpoints to integrate with standard SSO deployments.

  • Observation handling, encounter screener composition, and Group-based patient list syncing map directly to OpenMRS modules' expectations, minimizing custom server changes beyond documented extensions.

Adopting the Application in Your Organization

  1. Prepare infrastructure

    • Stand up OpenMRS + FHIR2 and Keycloak using the provided Docker Compose or the OpenMRS Distro SSO setup; ensure KC_HOSTNAME, gateway ports, and discovery/base URLs are aligned for both web and mobile clients.

  2. Configure the client

    • Copy local.properties.default to local.properties; supply GitHub credentials for artifact access, choose auth mode (basic or openid), and set fhir_sync_urls plus optional first_fhir_sync_url to bound initial and incremental sync scopes.

    • Enable patient-list scoping with filter_patient_lists_by_group and cohort-type where Groups are used for cohort targeting.

  3. Model your clinical forms

    • Publish or bundle FHIR Questionnaires for registration and encounters; use the observation-child and show-screener extensions to shape parent/child obs trees and screener behavior. Configure questionnaire identifiers (registration_questionnaire_name, questionnaires, encounter_type_system_url) in local.properties.

  4. Plan sync boundaries

    • Decide on filtering strategies (_include/_revinclude, _has Group filters) based on expected volumes and backend support; consider paging and offline requirements described in the sync options analysis.

  5. Operationalize support

    • Set support_email and optional diagnostics_password so field teams can securely export diagnostics. Validate connectivity health-check endpoints via check_server_url and tune timeouts for reliable status signaling.

    • Enable biometric login for offline authentication, ensuring compatibility with device hardware and Android Keystore-backed encryption.

  6. Contribute back

    • Review the observation save logic docs before modifying form or encounter code paths to preserve data integrity, and align new features with the documented OpenMRS extensions for maximum compatibility.

Getting Started Checklist for Contributors

  • Clone the repo and configure local.properties with credentials, URLs, and auth mode.

  • Run OpenMRS/Keycloak via Docker Compose or your existing SSO distro; verify hostnames/ports and test login with predefined Keycloak users.

  • Sync a small dataset by narrowing fhir_sync_urls and, if needed, using first_fhir_sync_url for initial seeding; iteratively expand once performance is validated.

  • Design or adapt questionnaires with the required OpenMRS extensions for identifiers, attributes, obs grouping, and screener flags, then test registration/encounter flows offline and online.

  • Test offline biometric login and diagnostics export as part of local development to ensure predictable behavior across devices.

Clone this wiki locally