Skip to main content

Modify user roles

The operations that a user can do on an entity are determined by two factors:

  • The roles of the user.
  • Whether the entity was shared with the user (if the entity is encryptable and the user a Data Owner).

This how-to focuses on assigning and removing roles from a user. You can read more about permissions and Data Owner users in this explanation.

Check user roles​

The user roles information are stored in the systemMetadata property. The fields of this property that are relevant for roles are:

  • isAdmin is a boolean field that is true if the user is an admin.
  • roles is a set of the ids of all the roles assigned to the user.
  • inheritsRoles is a boolean field that is true if the user has no role set and so inherits the default roles from the group configuration.

Default Roles​

Each database has its own default roles, that are set when the group is created. You can edit the default roles and check which permissions they grant in the Cockpit (🚧).

Roles are assigned based on the user type:

  • If the user is a HealthcareParty user (i.e. the healthcarePartyId field is not empty), it will receive all the HCP roles.
  • If the user is a Patient user (i.e. the patientId field is not empty), it will receive all the PATIENT roles.
  • If the user is a Device user (i.e. the deviceId field is not empty), it will receive all the DEVICE roles.
  • If the user is not a Data Owner user, it will receive all the USER roles.

If you assign a new role to a User, it will lose all the default roles.

Assign a role to a user​

To assign a role to a user, you first need to identify which role you want to give. You can retrieve all the available roles using the getAllRoles method in the role section of the sdk.

val allRoles = sdk.role.getAllRoles()

Then, you can update the roles for a user adding the id of the new role to the existing ones for the user. For the sake of the example, we will use the first role in the result.

// val userId = The id of the user to update
val user = sdk.user.getUser(userId)!!
sdk.user.setUserRoles(userId, (user.systemMetadata!!.roles + allRoles.first()).toList())

Now the users has all their previous roles plus the new one.

warning

This operation sets the roles for a user, so it can be used both to add and remove roles: to add a role, just like in the example, you have to pass all the previous roles plus the ones that you want to add. To remove a role, you have to pass all the previous roles except for the one that you want to remove.

note

You can also modify the roles of a user manually in the Cockpit (🚧)

Reset user roles​

To remove any role configuration from a user and revert it to the configuration defined in the group, you can use the removeRolesFromUser method of the SDK:

sdk.user.resetUserRoles(userId)

Creating custom roles​

You can create your own roles from the existing permissions using the createRole method in the role section of the SDK. You have to provide:

  • The name of the role: it can only contain uppercase letters (A-Z) and underscores, with a maximum length of 40 characters. The id of the created role will automatically be set to <GROUP_ID>:<ROLE_NAME>.
  • The set of permissions granted by the role. You can retrieve all the available permissions using the getPermissions method in the role section of the SDK.
  • Optionally, a short description for the role (max 300 characters). The description parameter was added in SDK 2.5.0.
  • Optionally, inheritsUpTo: the maximum level in the downward group hierarchy where this role can be used (null = any child group at any level, 0 = only the current group, 1 = only the current group and its direct children, and so on).
val allPermissions = sdk.role.getPermissions()
val customRole = sdk.role.createRole(
	name = "MEDICAL_SECRETARY",
	permissions = setOf(allPermissions.first()),
	description = "A role for the medical secretaries of the practice"
)

You can later change the permissions granted by a role using the modifyRolePermissions method, or permanently delete the role using the purgeRole method.

There is also a createRoleInGroup variant that takes the id of the group where the role should be created as its first parameter.

note

In TypeScript and Python the description parameter is required (pass undefined / None if you don't want to provide one). It comes before the options argument (containing inheritsUpTo) in TypeScript, and before inherits_up_to in Python: check your existing createRole calls if you upgrade from an SDK version older than 2.5.0.