Letting a module require configuration at first-time setup (for Atlas)

Every time I look at the OpenMRS Atlas, I’m very sad that we aren’t prompting people to configure it the first time they log into OpenMRS.

So I’d like to work on [RA-281] Configure Atlas module at first startup - OpenMRS Issues.

One approach would be to introduce a “not yet configured” stage to the module lifecycle; we ought to do this at some point, but for my purposes making that core change seems like overkill.

My thought is to introduce a more general feature, like “Sticky Notifications” (this is a dumb name I just made up):

  • these would be displayed prominently on the home screen
  • a module can register a bean that dynamically generates notifications (each time the home screen is loaded)
  • these notifications would have something like:
  • privilege required to see them
  • icon and text
  • 0 or more actions (which are text + a link to follow + privilege required to see this action)

The Atlas module could do something like this:

(Better UX would be to provide a “No thanks” action from the message itself, but I prefer to be greedy here and nudge more people to participate, by forcing them to click through the Configure Atlas page if they want to opt out.)

The same functionality could be used to implement a “message of the day” feature, or similar.

Any opinions about this? My take is that it’s easy and non-invasive, and has some amount of reusability. (I really don’t want to muck around with adding screens to the installer, and I don’t want to forcibly load the Configure Atlas page before they can do anything else.)

1 Like

I love this idea … even the dismissal UX. The Atlas is super valuable to all of us … if we get more people using it. :smile:

Sounds fine to me, can we use this too to alert the admin that a module was started/stopped and requires restarting openmrs?

It could be used for that also, yes.

I haven’t considered whether this should be shown on all pages or just the home screen.

I went ahead and implemented this idea. I called it “Administrative Notification”, but I’m happy to rename it if someone has a better one.


The code

Framework: a module that wants to notify the admin creates AdministrativeNotification and they do this via an AdministrativeNotificationProducer. The coreapps module provides a fragment to display these, and the referenceapplication module shows it on the home page.

Usage: a module does something like ConfigureAtlasNotificationProducer.

A side effect is that the Atlas module now requires the App Framework module, which is a problem for the legacy UI. The alternative would be to have the Reference Application module be responsible for generating the notification instead of the Atlas module. I think that might even be a better approach. @burke, let’s figure out which approach to take. (I’ll comment on RA-281 as a reminder.)


What it looks like:

Clicking the link takes you to the Configure Atlas screen, which also lets you “Stop reminding me”:

To get the notification to stop appearing the admin either needs to turn on the automatic updates, or else click on the “Stop reminding me” link. (It’s not enough to place your pin, you actually have to turn on automatic updates. That wasn’t my intent, but see this post.)

Is there a reason not to do this like how its done using session cookies in platform 1.x? So the fragment or REST based UI is able to use the session cookie to show messages?

This looks nice Darius. What does it look like when there are many of these notifications? Let’s say if every module that requires configuration before running the first time did this, what would things look like?

For sites not connected to the Internet can the module allow a user to download a file (with the metadata information) that can be uploaded to Atlas offline?

Hi @ssmusoke,

You can’t upload a file containing metadata, but you can set “by yourself” some stats directly creating/editing your marker at atlas.openmrs.org at anytime, as you can see in the capture.

I Hope this can help you :smile:

Or maybe you suggest to let the user getting these stats from the Atlas Module when it is offline ?

This was planned for a future version of the Atlas (not sure if we ticketed it yet) and would have the advantage of sending not only counts, but also the module list and other system info. While we don’t intend to ever show that information on the Atlas for individual sites, we do want to be able to share aggregate data on module usage and system specs.

@burke oh yes while that is an excellent tool for Atlas, it may also be a good one for implementors to manage inventory of their sites, in our case we are looking at ~300 now with probably a 4x growth in the next 18 months.

I would be interested in working to contribute to a module that allows the collection of inventory information, and maybe some options can be unselectable for privacy reasons. Maybe even being able to get a data continuously to be able to track progression - say concepts, obs, module meta-data, etc that is timestamped to graph and chart - or am I off my rockers with this one?

The lifecycle of a “you need to configure the atlas” notification is not aligned with the web layer, so the code that generates it wouldn’t have access to an HTTP session. Also, these aren’t necessarily targeted at, or dismissible by, a specific user.

So I don’t think a session cookie based implementation is right for the general concept. Btw I also implemented a REST resource so that a REST client can show these.

That said, the idea of a notification that each user should dismiss individually is useful (e.g. “the system will be unavailable for maintenance from 10-12pm”) and these could make sense to control via session cookies.

Right now there’s a “requiredPrivilege” field on the notification class; we could also add a “suppressByCookie” field and support this behavior. Anyone want to do this? :smile:

1 Like

It doesn’t look great:

I would think we should tweak the CSS to have less vertical spacing around the notifications. (I just grabbed an existing element from the style guide for this.)

That said, having multiple notifications be this obtrusive would push the user to actually deal with them. :smile:

For completeness: I ended up moving the ConfigureAtlasNotificationProvider class from the Atlas module to the Reference Application module (so that we wouldn’t make the Atlas module depend on App Framework). That probably broke a link in my previous post, so if you’re looking for that example code snippet, you can find it here.