Define your permissions

In this section, we will illustrate some examples of how to set up your permissions

Introduction to roles & permissions

An important aspect of developing a medical application, is making sure that your user has access to only the information which they are authorised to see. Until now we've assumed that everybody can see all information, but that is rarely the case in an actual application. As the application progresses, you're more likely to segment the users into different roles such as patients, doctors, administrators, ...

The Extra Horizon backend has a couple of mechanisms to enable these roles & restrict permissions to certain users, classes of users or groups of users. Depending on the specific use-case of your medical device, you'll most likely need a combination of these.

1/ Global permissions & roles

These permissions are called as such because they are not restricted to a specific instance of a resource like a specific document or a specific group. They apply to the whole 'environment' and are the most extensive set of permissions.

Examples: VIEW_TEMPLATES, DELETE_REPORTS, CREATE_PROFILES,...

These global permissions are assigned to users through a role, which is a container for a set of permissions. Once you've created a role with a set of permissions, you can assign that role to the users that need to perform them.

To get an overview of the current roles & possible permissions in your environment, open your Control Center at https://app.extrahorizon.com/users/roles/ . There you'll see a list of global roles and their associated permissions. The admin role typically has the most permissions associated with it. This part of the UI also allows you to create new roles and manage existing roles.

In the users UI at https://app.extrahorizon.com/users/users, you see the different roles which are assigned to users. After clicking on a user, you'll be able to change their role (provided you have the proper permission to do so).

Note that it is also possible to add your own custom permissions to a role. The Extra Horizon backend ignores them, but you can leverage them within your own backend functions.

For more information, see global roles.

2/ Group membership

Concepts

What is a group? Fundamentally, a group is just a 24 character hex string identifier such as 654cf5b4c14e6e67bd3a8bfd. This identifier is used to link users together in a group. What this identifier references to, is entirely up to the developer. For example, this identifier can be the id of a document in a MyGroups schema. Or it is simply an identifier which is generated by a developer and stored somewhere else. Extra Horizon provides the means to conceptually link users together in a group, but gives developers the freedom to fill in themselves what this grouping means.

There are 2 ways that a user can be linked to a group: as a patient or as staff. You can interpret this as a classification within the group membership. The distinction between these two will be more important when talking about schema permissions but intuitively, staff membership is more permissive than patient membership. Patients have no permissions other than being member of the group and do not have the ability to get more permissions through group membership. Staff users on the other hand, can have more permissions assigned through a group role.

Group roles

Group roles give staff members extra permissions compared to patient members. They consist of a set of permissions which will only apply to the group. This set of permissions is a specific subset of the global permissions. You can find the list here. As you can see, they are mostly related to managing the group itself. While you can technically include other global permissions in your role role (or your own custom permissions), they will be ignored by the Extra Horizon backend.

Summary

The group concept provides a means to link different users together in a group, either as a patient or as staff. In itself, this doesn't determine whether somebody has access to a certain document or not. But this concept is leveraged to its full potential in the next section on schema permissions.

For more information, see groups.

3/ Schema permissions

Within a data schema, there are a two mechanisms which are important in deciding who has access to the documents of that schema

• Access modes: setting that controls which class of users gets to do what operations.

• Actions: transition actions can grant permissions to users by manipulating the userIds & groupIds fields of a document.

Access modes

All schemas contain the following properties: createMode, readMode, updateMode & deleteMode. Each of these modes have different settings which specify who will be able to perform the respective operation on the documents of the schema.

Next to this, it's important to know that every document in the Extra Horizon data service has the following array properties: userIds & groupIds. As the name implies, userIds is an array containing user ID's and groupIds is an array containing group ID's. By default these arrays are empty and you can't manipulate them directly as you would with the data contained in them, but there are API & SDK calls to add & remove users/groups to & from these arrays.

Combined with the schema access modes, the contents of these arrays in a document unambiguously determine if a user has the permission to perform a create, read, update or delete operation.

Lets take readMode as an example. The different possible settings for readMode are:

• default: who can read?

  • users whose userId is in the userIds array of a document.

  • users that have a staff membership in a group whose group ID is in the groupIds array of a document.

• allUsers: All users in the system will have the permission to read the documents of the schema.

• enlistedInLinkedGroups: who can read?

  • all users in the default case.

  • users that have a patient membership in a group whose group ID is in the groupIds array of a document.

You see how the group membership introduced in 2 becomes important in determining whether a user has access or not.

Important to note here is that global permissions take precedence over everything.

• Example: a user who has the READ_DOCUMENTS:my-schema permission, will be able to read all documents of schema my-schema, even if the readMode of that schema is set to default and his user ID is not present in userIds and his group ID's aren't present in groupIds.

For an explanation of all modes, please see here.

Actions

Imagine the following problem: a patient member in a group creates a document. Unless the readMode is set to allUsers, nobody can see the document. But we don't want to set it to allUsers because that means that everybody will be able to see the document. Likewise we don't want to give people global permissions either because that means they can see all documents. So how do we make this document available to the right people?

This is where transition actions come in handy. A particular set of these actions, described here, are used to modify document access.

For example, in order to solve the above problem we can use the linkCreator and linkEnlistedGroups action:

• linkCreator will add the user ID of the user who created the document, to the userIds array of the document. This makes the document accessible to the patient who created the document in all possible settings of readMode.

• Secondly, the linkEnlistedGroups action will take the ID's of all groups where this patient is a member of and add these to the groupIds array of the document. This ensures that when readMode is set to default, all staff members in those groups will be able to read the document.

So when we configure these actions to be used in the creationTransition of a schema, every time a new document is created, the backend will execute these actions on the document and ensure that the right users have access to it.