Clarify Manageable Roles by MarkvanMents · Pull Request #11753 · mendix/docs

MarkvanMents · 2026-08-18T06:35:23Z

There is confusion about the way that manageable roles work, and there is also a major confusing change in the UX.

This PR aims to clarify how manageable roles work.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

atennapel · 2026-08-20T13:51:48Z


 {{% alert color="warning" %}}
-The effects of changes to user roles are not immediate. This means that your app might show outdated pages or incorrect data. For more information, please refer documentation about [persistent sessions](/refguide/clustered-mendix-runtime/#sessions-are-always-persistent).
+The effects of changes to user roles are not immediately applied to end-users who are signed in to the app. End-users need to sign out and sign in again to pick up their new roles. This means that your app can show the wrong pages or data. For more information, refer to the documentation on [persistent sessions](/refguide/clustered-mendix-runtime/#sessions-are-always-persistent).


End-users need to sign out and sign in again to pick up their new roles.
Or wait 30s (i.e. the SessionValidationTimeout). After 30s the session will be revalidated by fetching it from the database, which will have the updated roles.

I think we should be cautious in the wording. There are all kinds of places where the logged in users roles are cached and used to make decisions about for example what kind of interface elements to show or not in the web client.

I also think we should be cautious. How about we say something like:

Suggested change

The effects of changes to user roles are not immediately applied to end-users who are signed in to the app. End-users need to sign out and sign in again to pick up their new roles. This means that your app can show the wrong pages or data. For more information, refer to the documentation on [persistent sessions](/refguide/clustered-mendix-runtime/#sessions-are-always-persistent).

The effects of changes to user roles are not immediately applied to end-users who are signed in to the app. This means that your app can show the wrong pages or data. Although the user roles are reapplied when their session is revalidated, Mendix advises that end-users sign out and sign in again to pick up their new user roles. This ensures that they have the correct user roles. For more information, refer to the documentation on [persistent sessions](/refguide/clustered-mendix-runtime/#sessions-are-always-persistent).

@atennapel and @knorrie let me know if you are happy with this and I can commit the change and merge the PR.

Yes looks good to me.

MariaShaposhnikova · 2026-08-21T08:29:58Z

+A user role aggregates a number of access rights to app documents such as data, pages, and microflows. Each end-user of the application is assigned one or more user roles by an end-user with user management rights, and gets all the access rights that these user roles represent.

-Every user role has one or more [module roles](/refguide/module-security/#module-role), which means that users with that user role have all the access rights that are defined for those module roles. A typical user role has the **System.User** module role and at least one other module role.
+Every user role has one or more [module roles](/refguide/module-security/#module-role). End-users with that user role are granted all the access rights defined for those module roles. A typical user role has the **System.User** module role and at least one other module role.


Suggested change

Every user role has one or more [module roles](/refguide/module-security/#module-role). End-users with that user role are granted all the access rights defined for those module roles. A typical user role has the **System.User** module role and at least one other module role.

Every user role has one or more [module roles](/refguide/module-security/#module-role), which means that a user role is granted all the access rights defined for this module role. A typical user role has the **System.User** module role and at least one other module role.

I had to reread the sentence several times to understand it and tried to make it clearer.

MariaShaposhnikova · 2026-08-21T08:31:18Z

+Every user role has one or more [module roles](/refguide/module-security/#module-role). End-users with that user role are granted all the access rights defined for those module roles. A typical user role has the **System.User** module role and at least one other module role.

-The purpose of the distinction between user roles and module roles is to make a module self-contained (independent from the app in which it is defined or used), so that it can be reused in different apps and/or published to the Marketplace.
+The separation of user roles and module roles means that modules can be self-contained (independent of the app in which it is defined or used). This allows it to be reused in different apps or published to the Marketplace.


Suggested change

The separation of user roles and module roles means that modules can be self-contained (independent of the app in which it is defined or used). This allows it to be reused in different apps or published to the Marketplace.

The difference between user roles and module roles is that modules can be self-contained (independent of the app in which it is defined or used). This allows it to be reused in different apps or published to the Marketplace.

MariaShaposhnikova · 2026-08-21T08:36:43Z

-| Check security | This specifies whether the consistency of security settings is checked for this user role. You can choose to not check security for a user role. For example, user roles that are used only for web service users do not need to be checked because they never sign in to the client. For more information on the security check, see [App Security](/refguide/app-security/). |
+| Property | Description |
+| --- | --- |
+| Name | The name of the user role. This name is shown to end-users who can create or edit user accounts in the application. Blank apps usually start with the `User` and `Administrator` user roles. |


Suggested change

| Name | The name of the user role. This name is shown to end-users who can create or edit user accounts in the application. Blank apps usually start with the `User` and `Administrator` user roles. |

| Name | The name of the user role. This name is shown to end-users who can create or edit user accounts in the application. Blank apps usually start with the **User** and **Administrator** user roles. |

MariaShaposhnikova · 2026-08-21T08:38:43Z

 ### User Management Properties {#user-management}

-A user role can be allowed to manage users with a number of other user roles (including itself), called manageable roles. This means that end-users who have this user role, can create, view, edit and delete users with at most the manageable user roles.
+A user role can be allowed to manage end-users depending on their user roles. These roles are called manageable roles (or grantable roles).


Suggested change

A user role can be allowed to manage end-users depending on their user roles. These roles are called manageable roles (or grantable roles).

A user role can be allowed to manage end-users. User roles that can be managed by another user role are called manageable roles (or grantable roles).

It gets confusing whose user role we mean here, so I removed it.

MariaShaposhnikova · 2026-08-21T08:39:41Z

-| --- | --- |
-| All | End-users with this user role can manage all users and grant all user roles. Usually this option should only be configured for an administrator. |
-| Selected | End-users with this user role can manage users that have at most the selected user roles, and can grant only the selected user roles. Select **(No user roles)** to only manage users without a user role (for example, newly created users). If nothing is selected, end-users with this user role cannot manage users at all.  |
+End-users who have this user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.


Suggested change

End-users who have this user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.

End-users who have manageable user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.

MariaShaposhnikova · 2026-08-21T08:40:28Z

-| --- | --- |
-| All | End-users with this user role can manage all users and grant all user roles. Usually this option should only be configured for an administrator. |
-| Selected | End-users with this user role can manage users that have at most the selected user roles, and can grant only the selected user roles. Select **(No user roles)** to only manage users without a user role (for example, newly created users). If nothing is selected, end-users with this user role cannot manage users at all.  |
+End-users who have this user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.


Not sure I understand what "which is not selected" means?

MariaShaposhnikova · 2026-08-21T08:44:29Z

+
+{{< figure src="/attachments/refguide/modeling/security/app-security/user-roles/manageable-roles.png" alt="User management section with only the User role selected as a manageable role" >}}
+
+The following table shows which end-users an end-user with the `SubAdministrator` user role can manage:


Suggested change

The following table shows which end-users an end-user with the `SubAdministrator` user role can manage:

The following table shows which end-users the `SubAdministrator` user role can manage:

MariaShaposhnikova · 2026-08-21T08:45:46Z

+¹ The SubAdministrator can only grant or remove the `User` user role.
+² Although `User` is a manageable role, User3 also has the `SubAdministrator` user role which is not a manageable role for a SubAdministrator.
+
+The **(No user roles)** manageable role allows this user role to manage end-users without a user role (for example, newly created end-users).


Suggested change

The **(No user roles)** manageable role allows this user role to manage end-users without a user role (for example, newly created end-users).

The **(No user roles)** role is a manageable role and allows another user role to manage end-users without a user role (for example, newly created end-users).

MariaShaposhnikova · 2026-08-21T08:46:58Z

+The **Select / deselect all** checkbox lets you select all the roles as manageable roles, or deselect them all.
+
+{{% alert color="warning" %}}
+If the **Select / deselect all** box is checked (that is, all roles are manageable by this user role) then adding a new user role to the app will mean that it is automatically selected as a manageable role. If any of the roles are not selected, then added user roles will not be automatically selected as manageable roles.


Suggested change

If the **Select / deselect all** box is checked (that is, all roles are manageable by this user role) then adding a new user role to the app will mean that it is automatically selected as a manageable role. If any of the roles are not selected, then added user roles will not be automatically selected as manageable roles.

If the **Select / deselect all** box is checked (that is, all roles are manageable by this user role) then adding a new user role to the app will mean that it is automatically selected as a manageable role. If none of the roles are selected, then added user roles will not be automatically selected as manageable roles.

MarkvanMents added 4 commits August 17, 2026 15:50

Resolve Markdown linting issues

efbad28

Update Images for User Roles

607f4a1

Clarify Manageable Roles in User Roles

954cbe6

Add alt-text

e79635d

MarkvanMents added Needs R&D technical verification Internal WIP Needs Support verification labels Aug 18, 2026

github-actions Bot assigned MarkvanMents Aug 18, 2026

Fix grammar, style, and consistency issues in User Roles

ca6a7ae

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

MarkvanMents requested a review from knorrie August 18, 2026 07:07

Address clarity concerns

07ec41d

MarkvanMents marked this pull request as ready for review August 19, 2026 09:43

atennapel reviewed Aug 20, 2026

View reviewed changes

MarkvanMents removed Internal WIP Needs Support verification labels Aug 21, 2026

MariaShaposhnikova reviewed Aug 21, 2026

View reviewed changes

	Every user role has one or more [module roles](/refguide/module-security/#module-role). End-users with that user role are granted all the access rights defined for those module roles. A typical user role has the System.User module role and at least one other module role.
	Every user role has one or more [module roles](/refguide/module-security/#module-role), which means that a user role is granted all the access rights defined for this module role. A typical user role has the System.User module role and at least one other module role.

	The separation of user roles and module roles means that modules can be self-contained (independent of the app in which it is defined or used). This allows it to be reused in different apps or published to the Marketplace.
	The difference between user roles and module roles is that modules can be self-contained (independent of the app in which it is defined or used). This allows it to be reused in different apps or published to the Marketplace.

	\| Name \| The name of the user role. This name is shown to end-users who can create or edit user accounts in the application. Blank apps usually start with the `User` and `Administrator` user roles. \|
	\| Name \| The name of the user role. This name is shown to end-users who can create or edit user accounts in the application. Blank apps usually start with the User and Administrator user roles. \|

	A user role can be allowed to manage end-users depending on their user roles. These roles are called manageable roles (or grantable roles).
	A user role can be allowed to manage end-users. User roles that can be managed by another user role are called manageable roles (or grantable roles).

	End-users who have this user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.
	End-users who have manageable user role can create, view, edit, and delete end-users with the selected roles, provided they do not also have a user role which is not selected.


		{{< figure src="/attachments/refguide/modeling/security/app-security/user-roles/manageable-roles.png" alt="User management section with only the User role selected as a manageable role" >}}

		The following table shows which end-users an end-user with the `SubAdministrator` user role can manage:

	The (No user roles) manageable role allows this user role to manage end-users without a user role (for example, newly created end-users).
	The (No user roles) role is a manageable role and allows another user role to manage end-users without a user role (for example, newly created end-users).

	If the Select / deselect all box is checked (that is, all roles are manageable by this user role) then adding a new user role to the app will mean that it is automatically selected as a manageable role. If any of the roles are not selected, then added user roles will not be automatically selected as manageable roles.
	If the Select / deselect all box is checked (that is, all roles are manageable by this user role) then adding a new user role to the app will mean that it is automatically selected as a manageable role. If none of the roles are selected, then added user roles will not be automatically selected as manageable roles.

Uh oh!

Conversation

MarkvanMents commented Aug 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants