RolesSettings Documentation

Overview

The RolesSettings component in the Vantage analytics and data platform is designed to manage user roles within an organization. This component allows users to create, edit, search, and delete role definitions that govern user access and permissions. It serves as a crucial part of the platform's security and user management framework, ensuring that appropriate access controls are enforced throughout the system.

Purpose

The primary purpose of the RolesSettings component is to provide an intuitive interface for administrators to manage roles associated with user permissions. It facilitates the ability to add new roles, modify existing roles, and filter through the roles based on user-defined criteria. This enhances the ability to maintain role hierarchies and ensure users can only access features appropriate to their assigned roles.

Structure and Functionality

This component is organized around the following key functionalities:

• Role Management: Create, edit, and delete roles.
• Search Functionality: Filter roles by name or description.
• Dynamic UI: Update the UI in response to role changes.

State Management

The component uses the following states:

• roles: An array that stores role definitions fetched from the server.
• isLoading: A boolean that indicates whether the roles are currently being fetched.
• searchQuery: A string that captures the user's input for filtering roles.
• isModalOpen: A boolean that indicates whether the role editor modal is open.
• editingRole: An object that holds the role being edited, if any.

Data Fetching

• The component fetches roles from the /api/organization/roles endpoint on mount and updates the UI accordingly. If the fetch operation is successful, roles data is stored in the roles state; otherwise, an error is logged, and loading state is updated.

Settings

The following detailed settings pertain to the RolesSettings component:

1. roles

   • Type: Array
   • Description: This setting holds an array of role objects, each containing details about a specific role (id, name, context, description). Changing this setting updates the displayed list of roles in the component.
   • Default Value: [] (empty array)

2. isLoading

   • Type: Boolean
   • Description: This setting indicates whether the component is currently fetching roles from the backend. If true, a loading message is displayed. Setting it to false implies that either the roles have been successfully fetched or an error occurred.
   • Default Value: true (initially when the component mounts)

3. searchQuery

   • Type: String
   • Description: This text input captures the user's search query for filtering roles based on name or description. Changing this setting will filter the displayed roles accordingly.
   • Default Value: '' (empty string)

4. isModalOpen

   • Type: Boolean
   • Description: This setting controls the visibility of the Role Editor modal. When true, the modal opens for creating or editing a role.
   • Default Value: false

5. editingRole

   • Type: Object or null
   • Description: This setting stores the current role being edited. If set to an object, it signifies that the role editor modal is in edit mode for the specified role. Setting this to null indicates the creation of a new role.
   • Default Value: null

Use Cases & Examples

Use Cases

1. User Onboarding: An organization expands its team and needs to define roles such as "Admin", "Editor", and "Viewer" to manage user permissions effectively. The RolesSettings component is used to create these roles quickly.

2. Role Modification: A security audit reveals that certain users have excessive permissions. An administrator can easily edit existing roles to restrict access levels utilizing the RolesSettings component.

3. Custom Access Control: A specific project requires a unique role that combines permissions from multiple existing roles. The RolesSettings component can be used to create this custom role, ensuring granular access.

Configuration Example

Scenario: An organization needs to create a new role called "Data Analyst" which allows read access to analytics resources.

Sample Configuration Data:

{
    "name": "Data Analyst",
    "context": "organization",
    "description": "Role to access analytical data and generate reports."
}

Steps:

1. The administrator opens RolesSettings.
2. Clicks on the "Create role set" button, which opens the RoleEditorModal.
3. Inputs the above details into the modal fields.
4. Submits the form, triggering the handleSaveRole method, which sends a POST request to /api/organization/roles with the JSON body containing the new role.
5. Role is created, and the displayed list of roles is updated automatically to include the new "Data Analyst" role.

This functionality shows how the RolesSettings component can directly impact user role assignments and permissions in a real-world context, streamlining administrative processes and enhancing usability within the Vantage platform.