Roles & Permissions

Permissions control what each employee can see and do. They are packaged into roles; employees receive roles through their group memberships.

The permission model

Each permission combines two axes:

Actions

Action Grants

Read

View records

Update

Edit records (implies Read)

Delete

Remove records (implies Update)

Override

Bypass standard flow restrictions — for example, non-standard proposal state transitions

Launch

Start operations — notably business process instances; launch rights are granted per process

Create

Add new records

Export

Download an entity’s records as a file, for example deals or the sign-in log; includes Read

Actions form a hierarchy: Delete implies Update, which implies Read.

Scopes

Scope Grants access to

Own

Records the employee authored or is assigned to

Group

Records shared with a specific employee group

Any

All records in the organization

Scopes also form a hierarchy: Any implies Group, which implies Own.

Not every entry offers every scope. Personal access tokens, app passwords and OAuth applications have Own and Any but no Group scope, and LDAP consumers and the sign-in log have Any only. The permissions for sign-in and credentials below list them.

The matrix

A role is a set of permission entries. Each entry specifies a secured entity (the thing being protected), an action, and a scope.

Secured entities include deals, proposals, displays, documents, processes, settings, and several dozen more. Custom entity types and field groups defined through the entity system also appear as secured entities. Each secured entity is granted on its own: a permission on a parent entity does not reach its child entities.

When creating a role, you start with zero permissions and check boxes in the permission matrix to grant access. The matrix is on the Roles tab of Employees. Each row of an entry names an action and a scope, for example View (own), Edit (all) or Create (all): the matrix writes Read as View, Update as Edit and Any as all.

Admin roles

A role can be marked as an admin role. An admin-role holder gets broad administrative permissions within the organization, and the permission model still applies to every one of them.

The admin role flag is distinct from the main administrator flag on an employee account. The main administrator bypasses all permission checks entirely. The bypass does not reach the license. A function that your organization does not have is refused for everyone, the main administrator included, and its screens show "This section is not available on your current plan. Contact CityScreen to upgrade." See employees for the three kinds of administrator.

How permissions accumulate

An employee belongs to one or more groups. Each group can carry one or more roles. The employee’s effective permissions are the union of all permissions from all roles in all groups they belong to.

If any group grants a permission, the employee has it, and no other group can take it away.

Field-level permissions

Within an entity, visibility of individual fields can be restricted per employee group. This means a group may see a document without seeing specific columns — for example, a margin field.

Field-level permissions are configured on the entity type through field permissions.

Counterparty permissions

Counterparty permissions are granted for each counterparty type. An employee who can read one counterparty type may not be able to read another.

See counterparties.

Account and identity permissions

Sign-in, credentials and the LDAP directory have their own entries in the permission matrix.

Entry Scopes Actions What it controls

Personal access tokens

Own, Any

Create, View, Edit, Delete

Tokens that call the API with an employee’s own access. With Own, an employee manages the tokens of their own account on the Access Tokens tab of Account.

App passwords

Own, Any

Create, View, Edit, Delete

Passwords for mail clients and other programs that sign in over LDAP. With Own, an employee manages their own on the App passwords tab of Account.

LDAP consumers

Any

Create, View, Edit, Delete

The accounts that other systems use to read the LDAP directory, on the LDAP consumers tab of Employees.

OAuth applications

Own, Any

Create, View, Edit, Delete, and Rotate signing key (Any only)

The applications that connect through OAuth and OpenID Connect, on the OAuth applications tab of Employees. Rotate signing key replaces the key that signs OpenID Connect tokens.

Sign-in log

Any

View, Export

The Sign-in log tab of Employees and the Sign-in history tab of an employee record. Either action opens them.

The Any scope of personal access tokens and app passwords reaches the tokens and app passwords of every employee. Other employees' access tokens and app passwords are reachable through the REST API.

Personal access tokens, app passwords, LDAP consumers and OAuth applications are four separately licensed functions. The pages of these functions say in the same words: "This function is licensed. If your organization’s license does not include it, contact CityScreen." The sign-in log is part of every organization and needs no license.

No role holds the permission for the sign-in log until an administrator grants it. An administrator grants Sign-in log to the roles that audit sign-ins, as described in Sign-In Log.

The Employees entry has four more actions. They are granted for a group of employees or for all of them, and they need no license:

Permission Allows

Reset password (group), Reset password (all)

Sending another employee a password reset link. See Employees.

Reset two-step verification (group), Reset two-step verification (all)

Seeing whether another employee uses two-step verification, and removing their authenticator app and backup codes. See Two-Step Verification.

Set two-step verification methods (group), Set two-step verification methods (all)

Choosing the verification methods of another employee: e-mail codes, an authenticator app, or both.

End sessions (group), End sessions (all)

Seeing and ending the sessions of another employee.

Employees manage their own password, two-step verification and sessions on the Account page without any of these permissions.

Before you grant any of these permissions at someone’s request, make sure you know who is asking.

Menu visibility

Menu sections appear only when the employee holds a read permission for the corresponding secured entity. Two employees with different roles see different menus and different record lists.

Some tabs of the personal Account page follow other rules. Profile and Sessions are open to every employee, and Sessions needs no license. Authorizations needs the license for OAuth applications and no permission. Access Tokens and App passwords need the View permission of their entries, and the license.

Related pages

  • Employees — the accounts that receive permissions

  • Employee Groups — the groups that carry roles

  • Field Permissions — restricting visibility of individual fields

  • Entity System — custom entity types that appear as secured entities

  • LDAP Directory — how LDAP consumers use roles to see employees and groups

  • Sign-In Log — the log that the Sign-in log permission opens