Roles and permissions – what users may see and do¶
This chapter describes how roles work in nexxcite: how permissions are granted and denied, how the roles of a user are combined, how entity policies restrict access to records, and which permissions exist.
It is intended for administrators who design the access concept of an installation. How users get their roles is described in Users.
1. Roles at a glance¶
A role bundles everything that decides what a user may see and do. A user can have several roles; nexxcite combines them.
Roles are managed in the Admin Studio under Access → Roles. The role editor has these tabs:
| Tab | Content |
|---|---|
| "General" | "Priority", "Home Action", "Top App Bar", "Left App Bar" |
| "Included Roles" | Other roles this role contains, and – read-only – "Effective Included Roles" |
| "Custom Styling" | "Theme", "Logo (Light Mode)", "Logo (Dark Mode)", "Custom Styles", "Custom Scripts" |
| "Global Search" | The "Entities" and "AI Search Assistants" users with this role may use in the global search |
| "Permissions" | Individual permissions, each allowed or denied, optionally marked "Important" |
| "Entity Policies" | "Read Limits", "Edit Limits", "Delete Limits", "Add Limits" per entity, "Field Limits" per field |
Summary¶
- Everything is denied unless a role allows it. The exceptions are "Clear Definition Cache" and the four entity defaults "Read records of entities without read limit", "Edit records of entities without edit limit", "Delete records of entities without delete limit" and "Add records of entities without add limit", which are allowed by default.
- "System Developer" contains every permission, "System Administrator" the administrative ones (section 4).
- When roles disagree, the role with the lowest "Priority" value wins – 1 beats 10. With the same value, the role whose name comes first alphabetically wins. "Important" overrides that rule.
- Entity policies restrict which records a user may read, edit, delete or add. Limits of several roles are added up: a record is accessible when any role's limit admits it.
- For entities without a limit, the entity defaults decide. Denying them turns the entity policies into a whitelist (section 6).
Roles can always be saved, even without an open sketch. While a sketch is open, a changed role is collected in it and takes effect when the sketch is published (see Sketches and publishing).
2. The roles nexxcite creates¶
On its first start, nexxcite creates two roles:
| Role | Priority | Content |
|---|---|---|
| "Administrator" | 1 | "System Developer" allowed – every permission. Assigned to the first user nxadmin. |
| "Default User" | 1 | Nothing. A starting point for the roles of ordinary users. |
Both can be changed. If one of them is deleted, nexxcite creates it again at the next start.
3. Priority – which role wins¶
Every role has a "Priority", a whole number. The lower the number, the higher the priority. With equal numbers, the role whose name comes first in alphabetical order wins – for every kind of setting. Still, give roles that can contradict each other different numbers, so that renaming a role does not change the result.
| Setting | Several roles define it | Result |
|---|---|---|
| A permission | Contradicting values | The role with the highest priority wins (section 5) |
| "Home Action" | Different actions | The action of the role with the highest priority |
| "Theme" | Different themes | The theme of the role with the highest priority, used as a whole |
| "Logo (Light Mode)", "Logo (Dark Mode)" | Different logos | Both logos of the role with the highest priority that defines any logo |
| "Top App Bar", "Left App Bar" | Different app bars | The entries of the app bars of all roles are shown together |
| "Custom Styles", "Custom Scripts" | Several | All of them are added; those of the role with the highest priority come last |
| "Entities", "AI Search Assistants" (global search) | Several lists | The lists are added up |
| Entity policies | Several limits | Added up, see section 6 |
Example: A user has the roles "Clerk" (priority 20, home action "My tasks") and "Team lead" (priority 10, home action "Team dashboard"). After signing in, they see the team dashboard.
4. Included roles¶
A role can include other roles. A user with the role then also gets everything the included roles grant – and the roles those include, and so on. "Effective Included Roles" shows the complete result.
- Roles that would include themselves, directly or through others, are not offered.
- Included roles keep their own priority. Including the role "Administrator" (priority 1) into the role "Helpdesk" (priority 50) gives a helpdesk user the administrator permissions with priority 1 – which beats anything "Helpdesk" denies without "Important".
5. Permissions¶
How it works¶
Every permission has a value: Allow or Deny. In the tab "Permissions", a role lists the permissions it sets. A permission that no role of the user sets has its default value – Deny for all permissions except "Clear Definition Cache" and the four entity defaults (section 6).
Most permissions are part of an umbrella permission:
System Developer
├── everything for designing the application
│ (actions, entities, forms, grids, lists, business rules, …)
└── System Administrator
└── everything for administering the installation
(users, roles, credentials, sketches, settings, monitoring, …)
Allowing "System Administrator" therefore allows, for example, "Edit User" – unless something else denies it. The complete assignment is listed in section 11.
Which value counts¶
To decide a permission for a user, nexxcite looks at the permission itself and at all umbrella permissions it belongs to, across all roles of the user:
- If one of these entries is marked "Important", only the important entries count. Among them, the one of the role with the highest priority wins.
- Otherwise, the entry of the role with the highest priority wins. If the permission itself and an umbrella permission are set by roles of the same priority, the permission itself wins.
- If no role sets anything, the default value applies.
The examples assume the same user with all the roles mentioned.
| Roles of the user | Result for "Delete User" | Why |
|---|---|---|
| "Admin" (priority 1): "System Administrator" Allow | Allowed | Granted through the umbrella permission |
| "Admin" (priority 1): "System Administrator" Allow, "Delete User" Deny | Denied | Same role, same priority: the specific permission wins |
| "Admin" (priority 1): "System Administrator" Allow; "Restricted" (priority 5): "Delete User" Deny | Allowed | Priority 1 beats priority 5 |
| as before, but "Restricted" marks "Delete User" as Important | Denied | Important entries beat all others |
| "Clerk" (priority 20) only, nothing set | Denied | Default value |
For administrators
- Deny within a role by adding the specific permission with Deny to the same role that allows the umbrella permission.
- Deny across roles with "Important", or by giving the denying role the better priority.
- Use "Important" sparingly. An important Allow can only be overridden by another important entry.
The Admin Studio and the management views¶
The Admin Studio requires "Admin Studio". Each collection in it additionally requires the permission of its management view, for example "Open Role Manager" for Access → Roles (see Admin Studio). Adding, editing and deleting require the corresponding "Add …", "Edit …" and "Delete …" permissions. Without the edit permission an editor opens without a save button; without the permission to add, nothing can be created or cloned.
6. Entity policies¶
Entity policies restrict access to records, per entity. Each limit names an entity and a condition.
| Limit | Condition | Effect |
|---|---|---|
| "Read Limits" | A filter on the records of the entity | Users see only records that match. Applies to the queries nexxcite runs for the user – lists, grids, searches, opening a record, refreshing an open record – and to records shown through a relationship to a single record. |
| "Edit Limits" | An expression, evaluated on the record | Changing a stored record is only possible when the expression is true – in a form, by an action and through the REST API alike. Otherwise: "You are not allowed to edit this record." |
| "Delete Limits" | An expression, evaluated on the record | Deleting is only possible when the expression is true. Otherwise: "You are not allowed to delete this record." |
| "Add Limits" | An expression without record context | New records can only be created when the expression is true. Otherwise: "You are not allowed to add a record of entity type …". |
How limits are combined¶
- No limit for an entity in any of the user's roles: the entity default decides (see below). By default, that means no restriction.
- One or more limits: access is granted when at least one of them admits it. The limits of all roles are combined with "or".
- A read limit with an empty filter admits all records of its entity. Because the limits are combined with "or", it also lifts the read limits other roles define for that entity.
- A role without a limit for an entity does not lift the limits of the user's other roles.
Example: The role "Sales North" has the read limit Region = North on "Customers", the role "Sales South" has Region = South. A user with both roles sees the customers of both regions. A user who additionally has the role "Reporting" (without any limit on "Customers") still sees only North and South.
Entity defaults – allowing or denying everything that has no limit¶
Four permissions decide what happens with entities for which none of the user's roles defines a limit:
| Permission | Identifier | Applies when | Default |
|---|---|---|---|
| "Read records of entities without read limit" | Records.Read |
No role of the user has a read limit for the entity | Allow |
| "Edit records of entities without edit limit" | Records.Edit |
No role of the user has an edit limit for the entity | Allow |
| "Delete records of entities without delete limit" | Records.Delete |
No role of the user has a delete limit for the entity | Allow |
| "Add records of entities without add limit" | Records.Add |
No role of the user has an add limit for the entity | Allow |
They are set in the tab "Permissions" like every other permission and are not part of an umbrella permission. As soon as any role of the user defines a limit for an entity, the limit decides and the entity default is no longer considered for that entity.
With the defaults denied, the entity policies work as a whitelist: users only reach the entities that are listed in a limit.
- Add "Read records of entities without read limit" with Deny to the role.
- In the tab "Entity Policies", add a read limit for every entity the users may read. Leave the filter empty to admit all records of the entity, or set a filter to admit only some of them.
- Proceed the same way with "Edit records of entities without edit limit", "Delete records of entities without delete limit" and "Add records of entities without add limit". Edit, delete and add limits need an expression that returns true when the action is allowed – a limit without an expression admits nothing.
Records of an entity the user may not read are missing from lists, grids and searches. Fields shown through a relationship to a single record of such an entity stay empty. Editing or deleting a record without permission ends with "You are not allowed to edit this record." or "You are not allowed to delete this record.", adding one with "You are not allowed to add a record of entity type …".
Example: The role "External Partner" denies all four entity defaults. It has read limits on "Projects" (filter Partner = current user's company) and "Documents" (empty filter), and an edit limit on "Documents" with an expression that is always true. Partners see their projects and all documents, may edit documents, and can neither see, edit, delete nor add anything else.
Field limits – restricting single fields¶
The tab "Field Limits" controls access to the fields of an entity. Each rule names an entity, a field and an access level:
| Access | Means |
|---|---|
| "Denied" | The field is empty for the user – in forms, lists, grids, searches and exports – and cannot be changed. |
| "Read" | The field can be seen but not changed. The input is shown disabled; a value that an action or a business rule sets is discarded. The field is never written when the user saves a record. |
| "Read & Edit" | No restriction. |
Instead of a field, a rule can name "(All other fields)". That rule is the default of the role for the entity: it applies to every field of the entity the role has no rule of its own for. Rules for single fields override the default in either direction. So only the exceptions need to be configured:
- Only a few fields visible: a default "Denied", plus a rule "Read" or "Read & Edit" for each field that may be seen.
- Everything except a few fields: no default (or "Read & Edit"), plus a rule "Denied" or "Read" for each field to protect.
A new rule starts as "(All other fields)" with "Read".
How field limits are combined:
- Per role, the rule for the field counts; if the role has none, its default for the entity. A role with neither has nothing to say about the field.
- The roles that have something to say are combined with "or": the most permissive access wins.
- A field none of the user's roles has a rule or a default for is not restricted.
- Field limits only narrow what the entity policies allow. A user who may not edit a record cannot edit any of its fields, whatever the field limits say.
- The record id cannot be restricted and is not offered. Every other field can be restricted – also fields nexxcite fills itself, such as the fields of an n:m relationship that link the two records. Restricting those prevents linking records; that is up to whoever sets the rule.
Example: The role "Staff" has on "Employee" the default "Read", and "Denied" for "Salary". Staff members see every field of an employee except the salary, and change none of them. The role "HR" has "Read & Edit" for "Salary"; a user with both roles sees and edits salaries, but still only reads the other fields – "HR" has nothing to say about them, so the default of "Staff" decides.
System Developer¶
Users with "System Developer" are not affected by edit, delete and add limits, nor by the entity defaults for editing, deleting and adding. For them, a field limit "Read" works like "Read & Edit". Read limits and the field limit "Denied" apply to them as well.
7. Global search¶
In the tab "Global Search", a role can restrict which entities and which AI search assistants its users can search with.
- An empty list means: this role does not restrict anything.
- The lists of all roles of a user are added up.
- If none of the user's roles has an entry, everything that is searchable is available.
8. License-free roles¶
A role can carry the special property "License free". Users with at least one such role do not take a license when they sign in (see Licensing). The property is intended for technical users and for special cases agreed in your license contract.
The property is set with the switch "License free" on the tab "General" of the role editor (Admin Studio → Access → Roles).
9. When changes take effect¶
| Change | Takes effect |
|---|---|
| Role saved without an open sketch | Immediately for new sign-ins |
| Role saved while a sketch is open | When the sketch is published |
| Roles of a user changed in the user editor | Immediately for new sign-ins |
| Entity policies | With the next action of the user (opening, saving, deleting a record, running a query) |
| Permissions, app bars, home action, theme | For a user who is already working: when they reload the page or sign in again |
Saving a role or a user does not end the sessions of the users concerned. To make a reduced permission take effect at once, end their sessions (Admin Studio → Access → Authenticated Users → "User Sessions" → "Sign out user").
10. Permission overview – what a user may really do¶
The "Permission Overview" shows the result of all the rules in this chapter at a glance: which permissions a user ends up with after all their roles, included roles, priorities and "Important" entries are combined, and which records of which entity they may read, edit, delete and add – each with the reason.
It is opened from the toolbar of two management views:
| Opened in | Select | Shows |
|---|---|---|
| Admin Studio → Access → Users | A user | The roles assigned to the user and every role they include |
| Admin Studio → Access → Roles | A role | The role and every role it includes – what a user who holds only this role gets |
In the User Manager the button requires "Open Role Manager", because the overview shows the content of the user's roles. The overview only reads; nothing can be changed in it.
The overview has these parts:
| Part | Content |
|---|---|
| Tiles | Number of effective roles, allowed and denied permissions, permissions decided by a role, entities with limits |
| "Roles" | Every effective role with its priority and how the user got it: "Assigned", "Selected role" or "Included by …" |
| "Entity policies" | One row per entity any of the roles defines a limit for, with the access to adding, reading, editing and deleting records and the limits that decide it. The row "All other entities" shows the entity defaults (section 6). |
| "Field limits" | Per entity with field limits: the row "All other fields" for the defaults, and one row per field with a rule of its own – each with the result for reading and editing and the rule of every role that decides it. |
| "Permissions" | Every permission, grouped like in the permission reference, with the result and why: the role that decides it, whether it is granted through an umbrella permission, whether the entry is "Important", and the entries of other roles it overrules. The filters "Allowed", "Denied" and "Decided by a role" narrow the list. |
An entity whose records can be added, edited or deleted but not read at all is marked with a warning, and a note above the tiles counts these rows. Such a user can work on a record while it is open, but once they leave it, no list, search, link or URL brings it back. That can be intended – a form through which records are submitted and never seen again – but is usually a mistake. A read limit with a filter is not marked, because which records it admits depends on the data.
Exporting the overview to Excel¶
"Export to Excel" in the header of the overview downloads it as an Excel workbook, for example for an audit. The workbook shows the state of the last "Refresh" and has one sheet per part:
| Sheet | One row per |
|---|---|
| "Summary" | Key figure: whose overview it is, when it was read, the counts of the tiles |
| "Roles" | Effective role, with priority and source |
| "Permissions" | Permission, with the result, whether a role or the default value decides it, the deciding role and its priority, the umbrella permission it comes through, "Important", and the overruled entries |
| "Role Entries" | Permission entry as a role sets it – the raw data behind the result |
| "Entity Policies" | Entity and operation (add, read, edit, delete), with the result and the deciding limits |
| "Field Limits" | Field limit row, with the result for reading and editing and the deciding rules |
Every sheet except the summary is an Excel table: each column has a filter, and the header row stays visible while scrolling. Each column holds one fact, so the sheets can be filtered, sorted and combined – for example all permissions that the role "Helpdesk" decides.
Example: A user has the roles "Helpdesk" (priority 50) and – included by it – "Administrator" (priority 1). The overview shows "Delete User" as Allowed through "System Administrator" by role Administrator (priority 1) and lists the Deny that "Helpdesk" sets for it as overruled.
11. Permission reference¶
"Granted by" names the umbrella permission that contains a permission. "System Administrator" is itself contained in "System Developer".
Management views and editors¶
| Area | Permissions | Granted by |
|---|---|---|
| Actions | "Open Action Manager", "Add Action", "Edit Action", "Delete Action" | System Developer |
| AI assistants | "Open AI Assistant Manager", "Add AI Assistant", "Edit AI Assistant", "Delete AI Assistant" | System Developer |
| App bars | "Open App Bar Manager", "Add App Bar", "Edit App Bar", "Delete App Bar" | System Developer |
| Business rules | "Open Business Rules Manager", "Add Business Rules", "Edit Business Rules", "Delete Business Rules" | System Developer |
| Dashboards | "Open Dashboard Manager", "Add Dashboard", "Edit Dashboard", "Delete Dashboard" | System Developer |
| Entities | "Open Entity Manager", "Add Entity", "Edit Entity", "Delete Entity" | System Developer |
| Expressions | "Open Expression Manager", "Add Expression", "Edit Expression", "Delete Expression" | System Developer |
| Filters | "Open Filter Manager", "Add Filter", "Edit Filter", "Delete Filter" | System Developer |
| Forms | "Open Form Block Manager", "Add Form Block", "Edit Form Block", "Delete Form Block" | System Developer |
| Grids | "Open Grid Manager", "Add Grid", "Edit Grid", "Delete Grid" | System Developer |
| Lists | "Open List Manager", "Add List", "Edit List", "Delete List" | System Developer |
| Relationships | "Open Relationship Manager", "Add Relationship", "Edit Relationship", "Delete Relationship" | System Developer |
| Scheduled actions | "Open Scheduled Action Manager", "Add Scheduled Action", "Edit Scheduled Action", "Delete Scheduled Action" | System Developer |
| Business logic overview | "View Entity Business Logic Overview" | System Developer |
| Mailbox listeners | "Open Mailbox Listener Manager", "Edit Mailbox Listener", "Delete Mailbox Listener" | System Administrator |
| "Add Mailbox Listener" | System Developer | |
| API access | "Open API Access Manager", "Add API Access", "Edit API Access", "Delete API Access" | System Administrator |
| Authenticated users | "Open Authenticated Users Manager" | System Administrator |
| Authentication providers | "Open Authentication Provider Manager", "Add Authentication Provider", "Edit Authentication Provider", "Delete Authentication Provider" | System Administrator |
| Business hours | "Open Business Hours Manager", "Add Business Hours", "Edit Business Hours", "Delete Business Hours" | System Administrator |
| Counters | "Open Counter Manager", "Add Counter", "Edit Counter", "Delete Counter" | System Administrator |
| Credentials | "Open Credentials Manager", "Add Credentials", "Edit Credentials", "Delete Credentials" | System Administrator |
| Global settings | "View Global Settings", "Edit Global Settings" | System Administrator |
| Global values | "Open Global Value Manager", "Add Global Value", "Edit Global Value", "Delete Global Value" | System Administrator |
| Icon fonts | "Open Icon Font Manager", "Add Icon Font", "Edit Icon Font", "Delete Icon Font" | System Administrator |
| Images | "Open Image Manager", "Add Image", "Edit Image", "Delete Image" | System Administrator |
| Queries | "Open Query Manager", "Add Query", "Edit Query", "Delete Query" | System Administrator |
| Roles | "Open Role Manager", "Add Role", "Edit Role", "Delete Role" | System Administrator |
| Sketches | "Open Sketch Manager", "Add Sketch", "Edit Sketch", "Delete Sketch" | System Administrator |
| Themes | "Open Theme Manager", "Add Theme", "Edit Theme", "Delete Theme" | System Administrator |
| Users | "Open User Manager", "Add User", "Edit User", "Delete User", "Reset User Password" | System Administrator |
Entity defaults¶
| Permission | Default | Granted by |
|---|---|---|
| "Read records of entities without read limit" | Allow | – |
| "Edit records of entities without edit limit" | Allow | – |
| "Delete records of entities without delete limit" | Allow | – |
| "Add records of entities without add limit" | Allow | – |
Sketches and system functions¶
| Permission | Default | Granted by |
|---|---|---|
| "System Developer" | Deny | – |
| "System Administrator" | Deny | System Developer |
| "Admin Studio" | Deny | System Administrator |
| "Create sketch", "Import sketch", "Add sketch", "Export sketch", "Publish sketch", "Save sketch", "Delete sketch" | Deny | System Administrator |
| "View sketch history" | Deny | System Administrator |
| "Developer Console" | Deny | System Developer |
| "Data Inspector" | Deny | System Administrator |
| "Export Query Results" | Deny | System Administrator |
| "Reset Counter Value" | Deny | System Administrator |
| "Background Job Administration" | Deny | System Administrator |
| "View Background Processes" | Deny | System Administrator |
| "View Servers" | Deny | System Administrator |
| "View Communication" | Deny | System Administrator |
| "View Authentication Log" | Deny | System Administrator |
| "View License" | Deny | System Administrator |
| "View User Sessions" | Deny | System Administrator |
| "Sign Out User Sessions" | Deny | System Administrator |
| "Reset Two-Factor Authentication of a User" | Deny | System Administrator |
| "Clear Definition Cache" | Allow | – |
Collections¶
| Permission | Default | Granted by |
|---|---|---|
| "Use collections" | Deny | System Administrator |
| "Save records to collections" | Deny | System Administrator |
| "Save queries to collections" | Deny | System Administrator |
| "Create and manage own collections" | Deny | System Administrator |
What each of them allows is described in Collections.
12. Limitations¶
- A changed permission does not reach a browser tab that is already open; the user has to reload the page or sign in again (section 9).
- The permission overview (section 10) describes read limits by their filter. Whether a filter that uses values of the signed-in user (for example "the current user's company") admits a record can only be seen by that user.
- Read limits also apply to users with "System Developer", edit, delete and add limits do not.
- An edit, delete or add limit without an expression admits nothing. If it is the only limit for an entity, the action is denied for everybody affected.
- "Read records of entities without read limit" also applies to users with "System Developer". Do not deny it in a role that developers or administrators have, unless they get read limits for the entities they work with.
- An n:m relationship stores its links in an entity of its own. Removing a link deletes a record of that entity, adding a link creates one. With "Delete records of entities without delete limit" or "Add records of entities without add limit" denied, the entity needs a delete or add limit as well.
- A field that cannot be read still works in filters and sorting. A user can, for example, filter a list by a hidden salary and so learn which records have a high one. Sums, averages and groupings over a hidden field are answered empty.
- Business rules and actions see a hidden field as empty, because they run for the user. A calculation that uses a hidden field therefore calculates with an empty value – if its result is written into a field the user may edit, the wrong result is saved. Keep the result field read-only for the same users, or do not hide fields that calculations of these users depend on.
- A value for a field that cannot be edited is discarded whoever sets it – the user, a default value, a business rule or an action. This also applies to the field that links a record to its parent in a relationship: restricting it prevents linking records through that relationship.
- When a record is created, a mandatory field that cannot be edited gets the neutral value of its type (empty text, 0, no) instead of a value of the user, because the record could not be stored without it.
- Fields of the user profile that nexxcite reads for its own purposes – for example the names of users shown in the user menu and in user selections – are not restricted there.
13. Frequently asked questions¶
Does a higher priority number mean a more important role? No. The lower the number, the higher the priority. A role with priority 1 beats a role with priority 10.
A user has "System Administrator", but cannot open the actions. Why? Actions, entities, forms and the other design definitions belong to "System Developer", not to "System Administrator". Allow the individual permissions or "System Developer".
Can I take away a single permission from an administrator? Yes. Add the permission with Deny to the same role that allows "System Administrator", or to a role with a better priority, or mark it as "Important" in any role.
Can a role grant access to records that another role's read limit hides? Only through a read limit of its own for the same entity. A role without a limit does not lift the limits of other roles. A read limit with an empty filter admits all records.
How can I check what a user may do without signing in as them? Select the user in Admin Studio → Access → Users and click "Permission Overview" (section 10).
How do I give a user access to only a few entities? Deny "Read records of entities without read limit" and add a read limit with an empty filter for each entity the user may read (section 6).
Can the AI assistant change roles or permissions? No. Roles and their assignments are not accessible to the AI assistant. The assistant itself works with the permissions of the signed-in user.