Roles and Permissions Guide

This guide helps administrators understand the DatAscend Roles and Permissions system, how to establish a baseline role configuration, and how permissions map to both the User Interface (UI) and the underlying API.

---

Getting Started: Minimum Viable Role (MVR)

To prevent users from experiencing an unusable application, you must establish a Minimum Viable Role (MVR). When configuring a new role, certain system schemas are essential to allow basic dashboard layout rendering and navigation.

[!IMPORTANT] The object Permission Dependency In DatAscend, Entities are represented under the object module in the permission matrix. A role MUST have the object -> Get permission enabled. Without this permission, the client application cannot fetch entity schemas, causing the sidebar navigation to be completely blank and the main user interface to become unusable upon login.

Baseline MVR Configuration

To create a functional user role that can successfully log in and navigate the Web UI, you must enable the following baseline toggles:

1. object -> Get: Allows the client app to load structural entity metadata and navigation headers.
2. layout -> Get: Required to retrieve layout schemas for rendering dashboards, details views, and entity grids.
3. notification -> Get Own, Update Own, Delete Own: Essential for handling personal in-app alerts and notifications.
4. user -> Get Own: Required for users to fetch their own user profile details upon authentication.
5. Assign a Domain: You must assign at least one domain to the role under the Select Domains tab. Without a domain context, the application will not display entities or records.

---

Troubleshooting: Blank Screen / Empty UI after Login

If a user successfully logs in but is greeted by a completely blank screen, missing sidebar, or broken layout:

• Symptom: User completes login but is redirected to a dashboard with no menus, sidebar, or interactive controls.
• Root Cause: The user’s assigned role lacks the object -> Get permission.
• Solution:
  1. Log in as a Global Administrator.
  2. Navigate to Settings -> Roles.
  3. Select the affected role from the dropdown.
  4. Click on the Select Permissions tab.
  5. Locate the row for object and switch the toggle under Get to ON.
  6. Click Update (or Save Changes) to apply the permissions.
  7. Have the affected user log out and log back in.

---

Functional Permission Matrix

The following matrix maps how permissions correspond to what users see in the App UI and the API Responses (returning 403 Forbidden if missing):

Module	Action	UI Location / Visual Elements	API Endpoints
object	Get	Navigation Sidebar, Entity records list tables.	GET /api/v1/entities/:entity
	Create	”Add Record” button inside an Entity list page.	POST /api/v1/entities/:entity
	Update	”Edit” button in record action menus (...).	PUT /api/v1/entities/:entity/:id
	Delete	”Delete” option in record action menus (...).	DELETE /api/v1/entities/:entity/:id
report	Get	”Reports” sidebar menu item, embedded report tabs.	GET /api/v1/reports
	Create	”Add Report” button inside the Reports workspace.	POST /api/v1/reports
	Update	”Edit” option on reports, saving report builder configs.	PUT /api/v1/reports/:id
	Delete	”Delete” action on report listings.	DELETE /api/v1/reports/:id
workflow	Get	”Workflows” item in Settings navigation.	GET /api/v1/workflows
	Update	Workflow editor canvas, saving workflow rules.	PUT /api/v1/workflows/:id
system	Get	Access to the Studio workspace from global navigation.	GET /api/v1/system/config
role	Get	Access to Settings -> Roles lists.	GET /api/v1/roles
	Update	Changing permissions, categories, or domains inside a role.	PUT /api/v1/roles/:id
user	Get	Settings -> Users list table.	GET /api/v1/users
	Update	User modification form and profile updates.	PUT /api/v1/users/:id

---

Permission Granularity Definitions

Understanding granular actions prevents over-permissioning users. Across all modules, the system differentiates actions as follows:

• Get: Read-only access to view all resources/records within the module.
• Get Own: Restricted read-only access. Users can only view records they created or that are assigned to them.
• Create: Permission to initialize new records.
• Update: Permission to edit any existing records.
• Update Own: Restricted edit access. Users can only modify records they created or own.
• Delete: Permission to permanently delete any record.
• Delete Own: Restricted deletion access. Users can only remove records they created.

Behavior Across Key Modules

To configure roles effectively, keep in mind how actions are interpreted in each major functional area:

• Entities (object):
  • Read (Get / Get Own): Viewing the records lists and viewing record detail pages (e.g. looking at a Soccer Player’s profile).
  • Write / Modification (Create / Update / Delete): Controls whether the user can create new records, edit field values, or permanently delete entries.
• Reports (report):
  • Read (Get / Get Own): Viewing standard dashboards, charts, and embedded report tabs under entity records.
  • Write / Modification (Create / Update / Delete): Constructing new queries, editing configurations in the Report Builder, adding query sections, and saving layout changes.
• Studio (system):
  • Read (Get): Accessing the Studio canvas workspace to view schemas, relationship graphs, and properties.
  • Write / Modification (Update): Designing new entities, adding attributes/fields, defining relationships, or configuring translation labels.
• Workflows (workflow):
  • Read (Get): Accessing settings to monitor automation configurations and history logs.
  • Write / Modification (Update / Delete): Creating new workflows, configuring triggers, editing logical rules, and updating workflow queues.

---

Pro-tips & Best Practices

[!TIP] Permission Inheritance & Additive Roles

• Additive Behavior: If a user is assigned to multiple roles, their permissions are additive (the union of all granted rights). A block in one role will not override a grant in another.