Storing user-specific settings for OpenMRS 3.0

There are a growing number of examples within OpenMRS 3.0 of needing to be able to store user-specific application state. Here’s a recent example in Slack…

The current default approach is to use user_property with namespaced property names. This may work for simple cases, but faces a few challenges:

  • user_property currently limits property name to 100 chars and values to 255 chars
  • Applications will certainly want rapid/immediate access to a subset of properties and our APIs may not currently live up to this expectation
  • There will undoubtedly be user-patient-specific state as well (e.g., user preference for priority of conditions in the patient’s condition list)

While we can propose a convention for namespacing user property names, I would suggest we go a little further:

  • Refactor user_property to accommodate longer names and values.
  • Support separate namespace & property names so, for example, an application can say “I’m com.acme.foobar and I need [to set] my baz property for this user” allowing the API to manage how namespacing is handled rather than leaving it up to all clients to property follow a convention.
  • Come up with a plan for handling user-patient-specific state. Do we build this in on a case-by-case basis? Or do we create a centralized user_patient_property?

/cc @mksd @ibacher @grace @jdick @mseaton

1 Like

@burke this seems like a great idea. How do you want to move this forward?

I would suggest also including the ability to add access checks for the user->patient access, in case it is revoked between when the property is saved and the next access.

Maybe also setting a maximum number, pruning rules - after a period time, or a number of patients as this can grow exponentially large and slow down the views

Not being a member of the MF squad maybe it would be good to define these namespaces for a specific module without the ability for clients to override them to prevent conflicts, overwrites and clashes - even determine how to clean up orphaned configurations

Created the ticket for this at

Cases that require longer names and values, smell like gone beyond the original purpose of user properties, and hence should probably better use something else.

This looks like a call for another storage structure and its corresponding API. A centralised user_patient_property is the ideal.

Looks fair enough!

Unless you have very obviously simple optimisations, i would not address this until when it comes up as a real problem from implementations.

Nowadays, especially with our frontend technology, it’s not unusual to want to store JSON as a user property. 255 chars seems overly restrictive.

Fair point. Users should not be able to read user-patient properties without “View Patient” privilege.

These days, often the module is the client, so we would rely on the convention of modules (including frontend modules) to provide a unique “module id” that the API could use to namespace.

What new size values would you propose for the property and value?

A simple answer would be to use the JSON data types supported by MySQL 5.7+ and Postgres 9.2+.

We discussed this on the 2021-09-01 Platform Team call and came to this decision for enhancing capabilities for user properties:

  • Change user_property.value from VARCHAR(255) to LONGTEXT
  • Increase from VARCHAR(100) to VARCHAR(255)

This work is defined as:

The goal was to prevent clients from running into error from arbitrarily tight length constraints (e.g., storing a list of seven UUIDs could exceed the current 255 char limit for values). While we could migrate to JSON values in the future, we didn’t feel there was time for this with Platform 2.5 (could consider for Platform 2.6+). Since we are changing the value size, it seemed like a good time to provide a little more slack in property names (, since we expect these to be namespaced and a long module ID followed by a key containing a UUID could easily push the 100 character limit.

Personally, I would support moving toward having clients provide their namespace and key separately (instead of just a key, where we expect all clients to follow the same convention of namespace & key separated by a period).

@tendomart will create a separate ticket (linking as related to TRUNK-6020) for creating user-patient properties.


We’ve got it at

Thanks for pulling out the user-patient properties from TRUNK-6020, @tendomart.

I added a comment to TRUNK-6026 suggesting that we make sure we have some real world examples of needing user-patient properties before working on that feature. While we can invent examples, if we don’t have real world requirements, I’d favor de-prioritizing TRUNK-6026 until we do.


Any implementers here with real world requirements @ssmusoke @MekomSolutions @AMPATH @PIH ?

@grace, could we add to an upcoming OpenMRS 3.0 squad call an agenda item to simply ask “Are there any specific needs today to be able to store patient-specific settings for users?” Assuming this is an imagined need (not pressing), the Platform team will de-prioritize TRUNK-6026. The work to improve user settings is already underway.

1 Like

@grace did you present this to the MF squad ? And if so , did you get any feedback?

@tendomart I asked a question on Slack here about it:

Is it that a user_property would say “on the patient chart show the allergy widget at the top”, and a user_patient_property could override this behaviour for a specific patient? As in “on the patient chart show the allergy widget at the top, except for John Doe where it should show second after the conditions widget”.

If so, then I personally think this shouldn’t be prioritised as of yet, let’s get non patient-specific user customisations right first.

1 Like

Thanks @mksd for the pointer .I actually missed out on that .

Yeah… The change we’re implementing in 2.5 is just to expand the size of the columns in the user_property table to allow more data to be stored as a single user property. We haven’t really gotten into the user_patient_property component yet.

I think there’s another question of whether or not the MF squad actually wants to take advantage of that functionality yet or if the focus is on getting the basic UI right.