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


We need to separate "application roles" (used to assign privileges to users) from "organizational roles" (which reflect real-world job titles), because these two are not always aligned.  In simple cases, these two types of roles can be combined or confused; however, as an enterprise grows, exceptions arise.  Put simply: separating roles between the application (used for privileging) and roles within the "real world" means that all users sharing the same job title do not have to share the same privileges in OpenMRS.

The difference between application roles and organizational roles is their purpose: application roles define user privileges within the OpenMRS application and organizational roles define the person's position (job title) within the organization. The problem is that people's job titles do not always align 1:1 – e.g., not all doctors should have doctor privileges or people that aren't officially "doctors" need doctor level privileges. While the two are 1:1 in my example, having them separate allows for privileges and job titles to be managed separately.

There wouldn't be a problem if OpenMRS roles were only used for authentication (checking privileges); however, it's common for people to start building assumptions that the application roles represent organizational roles.

For example:

  • An implementation creates roles like DOCTOR and NURSE and assigns appropriate privileges.
  • Doctors are given DOCTOR role to use the system, nurses the NURSE role, etc. Everybody is happy.
  • They make a couple of reports that list all doctors, using the DOCTOR role to create the cohort. They write a module that prints out letters to patients and signs them with "Dr. Full Name" using the "Dr." prefix if the user has the DOCTOR role. As time passes, similar assumptions in reports, modules, and workflows are made that users with the DOCTOR role are doctors.
  • Complaints begin coming in:
    • Physician Assistants are printing out on reports as doctors (they shouldn't) and their signatures say "Dr. Full Name" when they should not. Initially, the system admin managed a separate PHYSICIAN ASSISTANT role, but eventually switched to DOCTOR, since he was told that the privileges should be identical and they kept forgetting to keep the privileges aligned.
    • Some of the physician assistants are currently working as nurses and should have only NURSE privileges in the system, but changing their privileges makes them show up on reports as nurses.
    • The admin doesn't know what to do with a group of consulting physicians, who need to show up in choice lists and reports as doctors (which are all governed by having the DOCTOR role), but should not have doctor privileges in the system.
    • The role-based home page is sending some users to the wrong starting page because, for various reasons,they have/need privileges in the system that don't match their job title.

All of these issues arise from conflating the notion of organizational roles with the (application) roles within the authentication system of OpenMRS... and they can all be solved by separating these two ideas. As soon as reports, modules, workflows, etc. start making the assumption that someone with a DOCTOR role in the system is actually a doctor (as their organizational role), they are conflating the two ideas – (1) this person needs to have DOCTOR level privileges within the system and (2) this person is a doctor – which, in practice, do not always align.


If you want the authentication system (what are supposed to be application roles/privileges) to be used also for organization roles, then you create organization roles separately and don't use them for privilege assignment. For example:

  1. Application roles like these, with appropriate privileges assigned to each:
  2. Organizational roles (job titles) like these, without any privileges assigned to them:
    • DOCTOR
    • NURSE
  3. You assign both in most cases. When you want someone to have the organizational role (job title), without giving the privileges, then you assign the organizational role and omit the application role.  You can also give someone the privileges of a certain role without being forced to give them the job title.

To make it easier to assign these roles together, you could add grouping roles:


Ultimately, OpenMRS would have a separate mechanism for recording organizational roles (job titles) outside of the privileges mechanism – creating a new user with a job title would suggest associated application roles.

Data Model


Draft ERD 

Organizational Role ERD

Provider Management Module Data Model 

The data model diagram for the Provider Management module be found here.  It would be great if we could take this into account when coming up with the final core design.

Open Questions

Do we only attach OrganizationalRole to Person? Or do we also attach it to Provider?

  • No labels


  1. In recent discussions, Burke has indicated that his idea of a single person having multiple entries in provider arises from the desire to separate provider roles. In that case, the field Provider Role ID should appear in the Provider table. I would argue that Start Date, End Date and Location ID should also be there to add time and place limitations on the role. The question of whether to have a Provider Supervisor table would be separate.

  2. I just added a link to a diagram of the Provider Management data model... I'm not an expert with Entity/Relationship mapping, so my apologizes if I got some of the one/many/mandatory/optional links wrong... :)

  3. @Mark
    Thanks for providing this. It is a little hard to understand what is going on, let me make some statements that reflect what I understand and you can declare them right or wrong or make your own list of statements and I will delete this comment.

    1. Each entry in the provider table represents a provider in a particular role (provider_role_id, provider_role).
    2. All providers in a particular role are supervised by providers in another role (supervisee_provider_role).
    3. Each provider_role has a particular set of attributes to be maintained for the provider (provider_role_provider_attribute_types).
    4. Based on the provider's role, suggested supervisors are determined by a "logic rule" (not sure if we still use this name, or even if that mechanism is used) based on the provider's attributes (supervision_suggestion).
    5. Providers in a particular role can assume certain relationships (with patients?) (provider_role_relationship_type).
    6. Based on the relationship type desired, suggested providers are determined by a "logic rule" (ditto) based on the patient?'s attributes.

    Based on what you've said in the past, I think this is addressed at providers who are community health workers (CHW provider type). (a) They have certain attributes, for example, geographic area served. (b) They are supervised by a CHW Supervisor type. The CHW supervisor may have several geographic areas for which s/he is responsible, which are maintained in provider attributes. (c) The supervisor of a CHW is most likely the CHW Supervisor responsible for the geographic area in which the CHW works. (d) The relationship between a person and a CHW is usually of the CHW relationship type. (e) The CHW suggested for the patient is the CHW whose service area includes the patient's preferred address or home clinic or whatever. Of course, there could be other rules besides geography, e.g. males have male CHWs and females have female CHWs.

    While many of these features appear to relate to local business rules, I think there are a number of points in common with the other proposals:
    (1) provider_type as a table and provider_type_id as a required field in provider (query: are we talking subclasses or types or some mixture of both).
    (2) importance of location in the provider's role (is it required or optional? do we have the APIs we need for comparing location, especially when we have the interior of facilities as well as the geographic hierarchy expressed as locations)
    (3) is time important? (note the recent addition of relationship start/end date)
    (4) is supervision something to support as integral to providers? or is it just another provider attribute or part of an hr module rather than the provider mechanism? is supervision best modelled as role-to-role or person-to-person or person/role/location-to-person or what?

    1. Your statements are more or less correct, except for #2.  The provider_role to supervisee_provider_role defines the valid supervisor/supervisee relationships that may exist (ie a Head Surgeon can supervise a Surgeon), but the relationships still need to be created explicitly.

      #5--yes, with patients

      Also, the suggestions can be based on all details of the underlying person, not just provider attributes.

      Also, provider_role_id is not currently required--you can have a provider without a role.  But I don't think I'd be opposed to making it mandatory if we pulled this into core.

      My thoughts were that if people we interested, the addition of the provider_role_id to the provider table and the new provider_role table could be rolled into core, but we could do that without necessarily rolling the other tables into core.  We might want to roll in something like the provider_role_provider_attribute_type table, but I would think that people would find something like suggestion rules too specific to add to core.

      At first glance, adding location and start/stop date to provider_role makes sense to me... actually, the CHW team in Rwanda recently asked if we could track provider start date, but this was after the original functional specs were written, so it didn't make it into this release.