OpenMRS Android Client User Guide

There is a need for an user guide for the OpenMRS Android Client and we were working on structure of the user guide from some time. The user guide will have detailed description of all the features of the Android Client along with how one can use them.

Issue link is here

For everybody’s convenience I’m using google doc, so please suggest if anything is missing or there is any improvment. I would really appreciate the help :slight_smile:

Link to doc is here

@raff, @adamg, @tmarzeion, @ykarim250 have a look.

#Structure of the User Guide is:


  • Introduction to OpenMRS
  • Introduction to Android Client ##Example - how to use?

##Features with its use cases

  • Login Offline
  • Sync On/Off

##The flow (with features available on each page)

  • Login

  • Change location

  • Sync On/Off

  • Dashboard

  • Logout

  • Find Patients

  • Download Patients

  • See Downloaded Patients

  • Sync Patient

  • See Patient’s diagnosis, visits and vitals

  • Active Visits

  • Capture Vitals

  • Capture different details using custom json forms

  • Add encounters

  • Register Patient

  • Patient Registration (online + offline)

  • Add patient photo

  • Form Entry

  • Filling Up Forms

  • Settings


  • Username
  • Password
  • Session & Session Location
  • Visits
  • Vitals

External Links

  • Setup your own server
  • Contribute

##Troubleshooting (solution to general problems)



Great initiative!

I suggest you use the gitbook format (rather than a Google Doc), as that’s what we’re trying to use on other OpenMRS projects going forwards.

@shivtej, thanks a lot! Do you think you could put it on instead of google doc as @darius suggested? It’s better for tracking changes and reverting if needed.

I’d make the following adjustments:

  1. Add Requirements section after Introduction. Include supported version of Android and OpenMRS Platform.

  2. Rename Example to Getting Started. Show basic workflow Login -> Register Patient -> Start Visit -> Capture Vitals -> View Captured Vitals. Do not go into details so that it can be completed in 5 minutes.

  3. I’d combine features and the flow section and call it simply Features:

x.1. Security Explain how data is stored and secured on the device and the SSL connection with the server. x.2. Login x.3. Registering Patients

  • Entering Patient Details
  • Adding Patient Photo
  • Finding Similar Patients x.5. Viewing Patients
  • Downloading Patients
  • Finding Patients
  • Visits
  • Diagnosis
  • Vitals
  • Encounters x.6. Active Visits x.4. Entering Data
  • Filling Up Forms
  • Adding New Forms Explain how to add forms on the server and basic form structure
  • Form Examples x.7. Working Offline Explain a bigger picture of sync on/off feature and how to switch.
  • Registering Patients Explain delayed identifier assignment and duplicate patients resolution
  • Synchronizing Patients Explain what gets synced? How often?

What do you think?

@raff, @darius thanks for the wonderful suggestions. Combining the feature and flow section would be great, otherwise there will be repetitions. I’ll do that. Thanks for listing out missing features as well. I’ll put this up on gitbook.

Hosted on gitbook:

1 Like

Now the structure for the user guide is finalized, we want to start working on it. Please give suggestions how should we go about it. Should we host it on the github like the other guides (eg: or host it on the gitbook itself ?

@raff, @avijitghosh82, @ykarim250 what do you guys think ?

@burke where do we intend to host our gitbooks?

@burke, do you have any response to Darius’s question? We’d like to move it forward…

Could we not have well-written Wikis beside each project’s source code on Github itself, and copy them simultaneously to OpenMRS Wikis as well?

Gitbook doesn’t seem as neat as Github wikis to me.

@shivtej You have used Introduction twice can you please fix that.Also we can add details about all the forms. And for getting started we can add a guide to the android client which will guide the user through all the features of the app on the first start.

@avijitghosh82, I agree with you. It will be just like other guides.

If there is no more responses, I’m taking this forward based on above discussion.

@defcon, no problem. We’ll moving this to github and solve all the issues there.’s integration with GitHub changed in a way that didn’t work well for us. I got some time tonight to dive into this and discovered we can host these books ourselves on GitHub Pages, using Travis to build & deploy including PDF generation and edit links directly to GitHub.

After setting this up for our Guide and Dev Manual, I set up the Android Client User Guide (PDF) too. These books will automatically update within minutes of any commit to master. :slight_smile:

This is nice, @burke . We can now start working on the user guide :slight_smile:

Thanks @burke! Would it be possible to put the user guide in instead of creating a separate repo for it? The reason I’m asking is that we could actually start asking on PRs to update the guide and code at the same time… The less repos to handle the better for both contributors and reviewers.

1 Like

Looks like a cool idea! :smile:

@burke, I’ve updated the ‘introduction’ section of Android User Guide but the changes aren’t reflected in the gitbook where it is hosted. Could you please look into this. Thanks!

@burke, could you please mentor me regarding this issue ? I want to learn about these things and want to tackle them myself. Thanks!

Fixed the build in

I don’t have access to the repo somehow, so @burke or @dkayiwa please merge the PR.

I rerun the build with my fix and it failed again. It seems to fail randomly for some reason… Let’s disable pdf generation for a while until we find the issue. PR at

Strange that /dev/5’s had read only access while /dev/3’s and /dev/4’s had write. I wonder what really happened. Just given back /dev/5 admin access. So @raff can you try again?

@dkayiwa, worked. @shivtej, your changes are in at