Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata

Primary mentor

Burke Mamlin

Backup mentor

Elliott Williams

Assigned to

Alexis Duque


The Atlas Module was created in Google Summer of Code 2011 as a way for implementations to easily create and maintain a marker on the OpenMRS Atlas. The module has not yet been widely adopted for two reasons: (1) it has not been distributed as part of OpenMRS, since OpenMRS 1.10 was delayed and later changed, and (2) creating or updating a marker depends on the module running in a production system connected to the public internet.

This project aims to address both of these issues by making a version of the Atlas Module to be distributed within OpenMRS 2.0 and allowing an implementation's marker to be registered to an OpenMRS ID, allowing for a the marker to be created or revised outside of the module.

Project Champions

Skills Needed

  • Decent Java coding skills
  • Basic SQL skills
  • Some PHP experience will help


  • New Features
    • Adapt the Atlas Module to run within OpenMRS 2.0
    • Allow markers to be filtered by type(s)
  • Marker Ownership
    • Refactor the Atlas Module and the OpenMRS Atlas website to register ownership of an implementation marker (via OpenMRS ID)
    • Provide a mechanism to "recover" control of a marker using the registered OpenMRS ID
    • Allow a user to link to an existing marker from within the Atlas Module, using their OpenMRS ID
  • Administration
    • Create administrative screen(s) for the Atlas Server to more easily manage markers

Extra Credit

  • New Features
    • Provide a tool to export a slide for presentation (e.g., using phantomjs to create slide-worthy image)
    • Provide an RSS with with last updated site
  • Marker Ownership
    • Allow a user to create their marker directly on the Atlas website
    • Allow a user to update or delete their marker directly on the Atlas website
    • Provide a mechanism to transfer ownership from one OpenMRS ID to another (registered owner specifies a new owner's OpenMRS ID)



  • Updated Atlas Module associating marker with OpenMRS ID with new functionality.
  • OpenMRS 2.0 Atlas Module integration.
  • Atlas website markers management functions + extra functionalities (markers filtering, color, …).
  • README in developer’s documentation explaining how are implemented new functionalities and Atlas Module App.
  • README in user documentation  explaining how to use Atlas Module App.

Communication Plan

  • Hangout meeting every monday and/or friday (~14:00-16:00)
  • Emails
  • IRC meetings
  • Gdoc for collaborative work.

Project Timeline

21 April – 18 May:

  • Getting familiar with Atlas Module and OpenMRS ID SSO

  • Fixing some Atlas related Tickets

  • Community bonding, participating in community events (Developers Forum, OpenMRS University, Hangout with mentor….).

19 May – 31 May:

  • Refactor Atlas Server with a php framework
  • Add global navbar on the top of Atlas
  • Add Sign In button for OpenMRS ID and OpenMRS ID SSO support for Atlas.

  • User can sign in successfully with his OpenMRS ID in Atlas Module using Multipass

1 June 1 – 30 June:

  • A user can create a new marker directly in the Atlas Server

  • A user can update, delete a marker created in the server. 

  • New administrative screens in Atlas Server to manage markers (move, remove outdated or invalid markers)

  • Extra features in Atlas Server : map exporting as a slide for presentation
  • Deploy Atlas Server to new prod host
  • Restablish marker fading feature

Mid term Eval

1 July – 12 July:

  • Atlas Module depends new UI Framwork
  • Add Atlas Server map in Atlas Module
  • User can authenticate in the module with his OpenMRS ID
  • An existing marker can be associated with an OpenMRS ID in Atlas Module

  • Atlas Module ported to OpenMRS 2.0 (whith a look like Google app style)

13 July – 26 July: 

  • Refactor the module
  • Make Atlas Module compatible accross OpenMRS 1.x and 2.x
  • RSS Feed with last updates in Atlas
  • Release Atlas Module 2.0 and deploy it to Modulus

10 August – 15 August:

  • Marker filtering by type or version

  • Marker Search by OpenMRS ID

16 August – 22 August:

  • Wrapping up project, final touches.

  • Writing Wiki and developer doc.


Enter Atlas Module

Just click on the OpenMRS Atlas icon from OpenMRS Ref App.

Atlas Module

In my mind, Atlas Module just render the Atlas Server into OpenMRS app, adding admin function as enable/disable marker update, send or not statistics.

Home Page

As a user can create or edit markers directly in Atlas Server, Atlas Module homepage can be an embedded view of Alas Server (maybe with <iframe> HTML tags for example), or just a map with user markers (maybe better idea !)

OpenMRS ID sign-in is required

Link/Unlink a server to a site in the Atlas

Enable or Disable Automatic Update

Edit your marker, show your counts chose to display them in Atlas

Show what is sent to OpenMRS

Atlas Server

A Visitor

Atlas Server Login


New database to manage markers created in Atlas Server and privileges

  • No labels


  1. This looks interesting (smile)

  2. Hi, I'm interested in working on this project, I have some questions: why Atlas Module isn't actually distributed as part of OpenMRS ? What's the problem ? Is Atlas Website repo here : ?

    1. The Atlas module would have been released within OpenMRS 1.10; however, 1.10 was delayed and ended up turning into OpenMRS 2.0, which has a new UI.  The goal of this project is to add some missing features and get the module running as an app within OpenMRS 2.0.

      Yes, openmrs-contrib-atlas is the code for the server side.

  3. Is there somewhere I can have a look to see how a module can got running as an app ? 

    To associate an OpenID with a Marker, we must first add a form into Atlas Module Management panel to sign in with the OpenMRS ID. Is it the right way ? I think we must change bubble too, in order to display OpenMRS ID informations.

    1. There is some documentation under Epic - Reference Application, including OpenMRS 2.x Developer Documentation.

      While we want to associate an OpenMRS ID with the marker for the sake of management/recovery, we won't force it to be shown in the bubble.  I believe we already have the option to include contact information, so the knowledge of an OpenMRS ID could aid in filling it out, but we don't want to assume that the person managing the marker will always be the contact person for the site.

  4. Very usefull links (wink) 

    I'm ok with informations shown in the bubble.
    Should we first make running Atlas module as an app and then add new functionnalites, or otherwise ?

    What are other functionnalites we can add ?

    1. I edited the page to provide some more specifics.

  5. Hi Burke,
    In your opinion, is adapting the Atlas Module to run within OpenMRS 2 + markers filtering by type are good mid-terme objectives ? Or should I be more ambitious ?

    1. In terms of adoption, I would prioritize associating OpenMRS ID (if that proves too difficult, we can go with email, but OpenMRS ID would be much more preferable) and getting it running in OpenMRS 2.0, so it can be shipped with a future version of OpenMRS 2.0.  The ultimate vision would be something like a Google marker icon as an "app" in OpenMRS 2.0 that, when clicked, opens a view of the OpenMRS Atlas in a mode that helps you create/modify your marker's position & bubble.

  6. Which functionalities could be helpfull to manage markers on Atlas Server backend ?

    1. Initially, just being able to delete markers or re-assign them woudl help.  Ultimately, it would be nice to expose RESTful access to the Atlas data and then make a simple web-based app in an admin section of the Atlas website:

      • Delete marker
      • Re-assign marker
      • Discover any bogus/invalid markers (e.g., someone playing around creates a marker in the middle of an ocean)
  7. Hi Burke Mamlin,

    I would like to work on this module. I cloned the atlas client side module and browsed the code on the functionality. I have setup up the reference application. I am also looking at some of the sample apps that were made in OMRS13 (smile) so that it might help me port the code into 2.0 I have been looking at the server end code as well and tried it out in my server. 

    I would like to know more about OpenMRS ID integration part, is there a REST methods already that are providing methods to obtain the OpenMRS ID or should we write our own API?

    About the Server Code, I deployed it in my XAMMP server, And is there any documentation for it?

    And regarding the multiple tools on the server side can we change the original full screen based server into a panel based one?

    Forgive me if I have been asking a lot of implementation questions. I think these would help me out to put up a better proposal.

    Thanking you in advance


    1. I believe there is a REST API for OpenMRS ID.  Elliott Williams is the best person to chat with about OpenMRS ID access, since he created it for us.

      Sorry, but no documentation for the server code at this point.  I threw it together in my spare time, so it hasn't gotten much love.

      We can do anything we want with the server side.  You could do filtering in a panel; however, Google seems to be migrating away from panels and more toward embedded controls.

      1. There is no REST API for manipulating OpenMRS ID data. However, I am mentoring a GSOC project to do just that.

        If you're only needing to use an ID as a form of authentication, I'm working on that right now in a single-sign-on module. We currently use OpenMRS ID SSO on, and have plans to use it on the helpdesk and the module repository shortly.

        1. Elliott Williams Thank you for taking the time to provide the information. I don't think we might be changing any OpenMRS ID data. We will need the data to associate it with the markers. And also the single-sign-on Module would be a great help!. I will be following it very closely.

      2.  I will try looking what might work well with the embedded control style.Thank you for the insight. 

  8. Hi Burke, could I send you my proposal draft to get your feeback before I submit it ?
    Daniel gave me this link to add an app into OpenMRS 2 : App Framework Step by Step Tutorial#Step1-PackagethefunctionalityasanApp

    Is it the right way for Atlas Module ?

  9. Alexis Duque, your timeline looks pretty good.

    Starting early on SSO for Atlas server is good.  We will probably need to start with Multipass and switch to OAuth when it becomes available.  I would move up the "adapt module for OpenMRS 2.0" earlier, since it can be happening in parallel with changes to the Atlas Server.  I believe the needs for the module will get smaller – i.e., as the marker management moves to the server, the primary purpose of the module will become automating marker updates.

    Prior to 18 May, we can hopefully create a road map for specific features with prototypes, so you have a clear idea of the work to be done rather than having it moving too much during the summer.  For example, some story boards of how we expect a user should be able to manage their marker on the Atlas Server, how a user in the Atlas Module can identify their marker to the module (i.e., tell the module which marker it should be updating).


    1. Thanks Burke Mamlin

      Starting early on SSO for Atlas server is good.  We will probably need to start with Multipass and switch to OAuth when it becomes available

      I'm actually looking for some tips or informations, because I never work on SSO ^^ It's very interesting for me. Do you have some repo were it's used in OpenMRS ?  


      • An existing marker can be associated with an OpenMRS ID in Atlas Module. 2

      • Add function to "recover" control of a marker using the registered OpenMRS ID 3

      • A marker can be created and updated directly in the Atlas Server. 4

      • Atlas Module ported to OpenRMS 2.0 (whith a look like google app style) 1

      I've made some changes on these points directly on the timeline.

      with prototypes

      I'm going to move to this pages mockups I've done prior, and create others, with what I have in my mind (smile)

      some story boards

      That means, writing something like that : "As a user, I wan't to sign in with my openMRS ID on the server to access marker management functions"  ?

      Can I clear prior comments on this project page ? Is it ok to write long comment, or you prefer use email ?


      1. openmrs-contrib-id-sso is the implementation of Multipass.  Elliott Williams could give you pointers on where to find examples.

        By "story boards" I was referring to user stories (like your example) but with a more detailed description of the specific steps a user would take combined with some mockups to demonstrate expected behavior.  Basically, enough to explain the vision of how users will interact.  The mockups are good, but in some cases we are making assumptions on how users will get to those views or how they might interact with them.  For example, how does a user coming to the Atlas for the first time recognize that they can create their own marker and do so?  How does a user do this from within the module – i.e., how does the Atlas module know which marker is theirs... just by OpenMRS ID and, if so, what if they have made multiple markers?

        1. I'm going to send an email to Elliott to have some tips.

          This afternoon (maybe morning for you (smile) )  I start to create some issue in Atlas Module, so we can complete them (with description, and mockup, ..) and then plan them.

          Is it like you are used to work ? 

  10. I've created a Scrum board in JIRA to plan and manage our work. Is it OK ? 

  11. Burke Mamlin, can I become admin of Atlas Module project ? Or I should create a new Atlas Module 2.0 project in JIRA ?

  12. One small thing based on the screen shots (maybe this is already changed). The correct English form of the verb "send" in the sentence would be, "See what data is sent to OpenMRS Atlas." (smile) 

    Great progress on this project so far!

  13. (smile) Burke opened a ticket for that , screen capture are deprecated (wink) I'm going to update that.