Overview

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.

Workaround

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:
    • DOCTOR PRIVILEGES
    • NURSE PRIVILEGES
    • REGISTRATION CLERK PRIVILEGES
  2. Organizational roles (job titles) like these, without any privileges assigned to them:
    • DOCTOR
    • NURSE
    • REGISTRATION CLERK
  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:

  • DOCTOR DEFAULT ROLES containing roles DOCTOR + DOCTOR PRIVILEGES
  • NURSE DEFAULT ROLES containing roles NURSE + NURSE PRIVILEGES
  • REGISTRATION CLERK DEFAULT ROLES containing roles REGISTRATION CLERK + REGISTRATION CLERK PRIVILEGES

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 

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?