Getting Started with openmrs-android-sdk

The OpenMRS-Android-Client can be used implemented either by forking the whole openmrs-android-client project and using the custom base url as asked while starting the app, or if the UI already present in the openmrs-android-client is not suitable for the implementation then we can use openmrs-android-sdk to get the core functionalities and build a custom UI on top of it.

The Openmrs-Android-sdk can be used as a library to build custom-UI on top of existing work done already on the android platform in Openmrs without forking the openmrs-android client . This is a short document on how to get started with the openmrs-android-sdk with an application from scratch.


  1. Basic familiarity with Android-development knowing how to use basic functionalities of the Android-Studio.
  2. Android Studio installed and setup preferrably with jdk-8.

Detailed Steps

  • Get started with a new application in Android-Studio, and select empty activity while choosing templates for a new application.  


  • These are the sample Gradle files and dependencies we need for this project.
    1. The top-level Gradle file can be kept intact except if already not there we should add the "" under the repository section



                   b. The app level gradle file needs to add a few dependencies for some android architecture lifecycle components as well as openmrs-android-sdk. This test application has been tested for API level 29 as captured in the Gradle file.




          c. Before calling any repository methods to interact with the OpenMRS Rest APIs through the openmrs-android-sdk. we must initialize the sdk with the 4 entities, the application context, the base URL, or the server we are going to interact with and correspondingly username and password to work it out. Usually, the applications built around this will have a proper login flow and will get the username and password from that flow before initializing the sdk as in actual openmrs-android client but for demo purposes to make things simple I have simply initialized the sdk with the required details by hard -coding them in the test - application.


        d. After we have initialized the sdk we can simply go on and make a list view and a view model, the view model will be storing the data which will be used by the list view to show the fetched data from the openmrs-servers.

             1. Simple XML UI.


             2. Provider Adapter to adapt data from the server response to list view items.



              3. View Model to call the repository methods which interact with openmrs servers using the openmrs-sdk.


             4. Using it all up to show the providers list in the MainActivity.


  • After All these steps have been completed The Main Activity should display a list of providers fetched from the servers and the results may vary depending upon the current list of providers the server has at that moment 



The whole test Application is hosted here, and the original repository containing the work is being hosted at the openmrs-android client. I hope that gives a bit of a hint, on how do we make use of the openmrs-android-sdk to interact with the openmrs-rest-APIs simply by passing in base URL and initializing the sdk correctly to extend the openmrs client as the way we want !!