Overview

Documentation

Description

The aim of the 'CustomRoleBuilder' module is to give granular control to administrators and superusers over the custom user roles, which can be applied to all users.

The system security design is important when it comes to using 'CustomRoleBuilder'. If set User Roles are used (e.g. Customer, Administrator, Shop), then the module may not prove useful. In design cases where more defined roles are used (e.g. ViewProducts, CreateEditProducts, DeleteProducts), The 'CustomRoleBuilder' is a suitable module to use (See ‘Scenario 1’ under ‘Typical usage scenario(s)’).

The module can still be used if the application does not use such specific roles. Custom Roles can be defined that contain several roles for ease of application when creating new accounts (See ‘Scenario 2’ under ‘Typical usage scenario(s)’).

Note: The roles used must be defined at a project security level.

Typical usage scenario(s)

Scenario 1

A company wants the ability to change what a user account can see or do in their management application. They want to be able to do this without having to contact their development team to introduce new roles or change existing one. The change could be time consuming and require downtime for their system.

The company also wants to be able to introduce temporary custom roles that comprise of several system roles, for the internship program that they have on a yearly basis. The internship custom role is not always the same.

With the CustomRoleBuilder, the company will be able to alter existing employee roles, or create new custom employee roles. They will also be able to create temporary custom roles that can be applied to the internship participants.

Scenario 2

An administrator needs to add several users who all contain 5+ system user roles. Using the CustomRoleBuilder, the administrator can create one custom role. This custom role can be applied the user accounts that need to be added.

Features and limitations

• Features
  • Create New Custom Roles
  • Update Custom Roles
  • Delete Custom Roles
  • Apply Custom Roles to user accounts
  • Deactivate Custom Roles
• Limitations
  • User Management – there is no restriction on which user role can apply any particular Custom Role to a user, such as is done in the security setup for each system user role. (‘User management’). However, user management still applies to the system user roles.
  • When changes are applied to Custom Roles, all the user accounts linked to that Custom Role. Applications with 1000’s of users should take that into account when applying changes.
  • During the development phase of an application it is may be a tedious task to create all the ‘well-defined’ system roles that will be used in the application.

Dependencies

• 7.23.19 (Module can be updated to later versions of Mendix, but caution should be exercised)
• Administration, including an entity named 'Account' which has associations with 'UserRoles'. (Standard Adminstration Module)
• System Module (default)

Installation

1. Import the module 'CustomRoles' into your project.
2. Link page 'CustomRole_Overview' found in the _USE_ME folder to an applicable navigation button.
3. Add the snippet 'CustomRoleSelector' found in the _USE_ME folder to the Account_New and Account_Edit page(s) under the Roles field. Depending on your application's preference you can choose to remove the Roles field, or leave it. The custom role(s) applied to the account will automatically update the system user roles applied to the account. Account_Overview will still show the 'UserRoles' applied to the Account.
4. Update Administration entity access for the association 'Account_CustomRole'. Giving the Administrator Read and Write access to this association.
5. Run the application.

Configuration

1. Navigate to the 'CustomRole_Overview' page and create a New and Save a CustomRole.
   1. Name: the name of the custom role that will be visible from the front-end (REQUIRED)
   2. Description: details around the role. For example, you may want to detail the overall permissions of this custom role that you create.
   3. System User Roles: the roles that will apply to this custom role (REQUIRED).

1. Create or Edit a User Account. Apply a custom role.

1. Manage CustomRoles
   1. Edit: Allows the user to edit the custom role that was created. New applied changes are applied to the accounts associated with the Custom Role attached.
   2. Delete: A Custom Role that is not used anymore can be removed entirely from the system. The user roles that were part of this CustomRole will be removed from the accounts associated with the CustomRole being deleted. Overlapping roles from other CustomRoles will not be removed.
   3. Change Active Status: Updates the status of the custom role. Only active status CustomRoles are shown on the accounts page. Similarily to the 'Delete' function when deactivated the user roles are removed from the Accounts associated. Alternatively, when the CustomRole is reactivated those roles are added back to the Accounts. Note: deactivated CustomRoles do not lose their associations with the Accounts that they had.

Known bugs

N/A.

Frequently Asked Questions

Question: Can this be applied to existing systems which already have user accounts?

Answer: Yes, and in this case it is recommended that you keep both the User Roles selector and the Custom Roles selector on the ‘Accounts_Edit’ page, as you can then still see what system user roles were applied for a user.

When the custom roles have been created and applied to the user accounts needed, the User Role selector can then be removed from application.

Question: Which module user has access to perform all the actions on Custom Roles?

Answer: Administrator module role.