Managing Permissions, Roles and Users

In Sophora , users are assigned to one or multiple roles, which determine the permissions a user has. A user with two or more roles has all permissions that are granted him by each of these roles individually (see section "Users with Multiple Roles" for more details). Which permissions are granted by which role can be configured in the role editor.

Why You Should Use Roles

There are plenty of reasons why it is useful and important to use roles and to equip different users with different roles. Here are a few examples.

Most probably, not all of your editors are responsible for the same kind of documents. Some of them could only be responsible for creating, editing and managing teletext articles, some of them write articles for your website, and some of them organize the television schedule. While it is Sophora's great advantage, that you can configure and manage all these tasks with just one system, it could and likely will be a very confusing information overload for your editors. Hence, you can and should clear their view by restricting the kind of information each editor gets - that way they are able to concentrate on the things they are good at. For example, you can configure a role "teletext editor" and configure it in a way, that users with this role may only read and edit documents belonging to the teletext family, or just documents in or below your teletext structure node. If he has to assist in your website's editorial department, e.g. due to holidays or illnesses there, you can simply assign to him a "website editor" role, and he will be ready to work there.

For security issues, you may want to deny most users the right to change most or all system documents. You could configure a special role and assign to it all the permissions you need for administrating purposes. Then, if just one editor respectively from every department should be able to change system documents, you can assign to each of them this additional role. That way, you just have to configure one additional role and do not have to create two roles for each department (e.g. "teletext editor" and "teletext editor admin").

By restricting system permissions and system document permissions to a small set of users, you can prevent editors from accidentally breaking your system configuration.

Creating and Editing Roles

Creating a New Role

Open the Administration view.
Go to User Management >> Roles .There, open the context menu with a right-click.
Select New: Role. The 'New document' wizard opens.
Choose a structure node preferably under /system and id stem. You can simply keep the defaults. Press Finish.
The role editor opens up.
To save the document, you have to enter a name first.
You must publish the document for the role to take affect.

Editing a Role

Expand the entry Roles within the administration view.
Double-click the role you want to edit.
The role editor opens, where you can edit the role according to your wishes.
Do not forget to publish the role, when you're finished.

The Role Editor

The document to configure a role looks like the one which you can see in the following screenshot. The field Name is mandatory; role names are unique, there cannot exist two different roles with the same name. Below that, you can choose which of the published work environments should be made available to users with this role.

Subsequently, you will find the section to assign permissions. A detailed explanation about what permissions there are and what they mean can be found in the next section.

On the dispositions tab of the role editor, you will find a list of all users to which this role is assigned. You can open the corresponding user document by double-clicking on the user in the list.

Note that the role document must be published, as only the last published version is taken into account.

Permissions

In general, there are five different kinds of permissions, which will be explained below:

System permissions
Document type permissions
Structure node permissions
Proposal section permissions
Tab permissions

Permissions are exclusively assigned to roles. Hence, you should note: whenever a user with a specific permission is mentioned, a user with a role with said permission is meant.

System Permissions

System permissions apply globally and are independent from any specific structure nodes or documents. These are all existing system permissions:

Administrator

Users which are equipped with the Administrator system permission receive more detailed information and can perform more actions throughout the Sophora DeskClient, for example:

UUID and structure node document UUID are displayed on the meta tab of a structure node editor.
Property tooltips display the actual key of the current property.
The internal names of image variants are shown next to their label.
They may export the entire structure tree or parts of it.
All existing websites and all of their subordinate nodes are shown in the structure view.
They can add new websites to the structure.
They can search the archive repository for permanently deleted documents.
The administration view is visible in its entirety; users may access all entries there.

Especially, the Administrator permission allows a user to create, modify and remove system documents such as node types, users, and form field groups, as well as configuration documents like pararaph styles and image variants.

Break Lock

A document is locked if a user is working on it. If a user with the break lock system permission tries to open such a document, he may break the lock without asking the current editor's permission first.
There is an execption from this: A user can always break his own lock even without the break lock system permission. This is new with Sophora Server versions 2.4.25, 2.5.23, 3.0 and newer.

Delete Documents From Trash

Only a user with this permission is allowed to delete documents permanently. Else, he or she may not remove documents from trash.

Delete Documents That Are Still Referenced

If any user tries to delete a document which is still referenced in a different one, he will be informed about this fact in a notification. Only users with this permission are then allowed to delete the document anyway.

Edit Categories

Only users with this permission are allowed to edit the category select values, which are shown in the view Categories .

Edit HTML Paragraph

Only users with this permission are allowed to edit copytext paragraphs of the HTML type.

Finish Pre-Published Documents

To publish one or more documents which are already pre-published, a user needs this permission.

Mass and Direct Image Upload

Users to whom this permission is assigned have the possibility to upload image files directly during the creation of a new image document. They will also have the right to upload multiple image files at once and create the corresponding Sophora documents. By denying this permission to a couple of users, you can prevent the Sophora server from high workload.

Mass Operations

Users need this permissions to perform mass operations, i.e. accessing operations for a whole search result via Search View >> More Actions >> Search Result.

Set Documents Offline That Are Referenced by Published Documents

This one is probably self-explanatory.

Document Type Permissions

Document type permissions restrict operations a role may execute upon certain document types. For example, a role might be configured in such a way that its users may read, create and save story documents but are not allowed to publish them. By default, document type permissions are valid globally. However, you can constrain where they should or should not apply by combining them with structure node permissions. The following list contains all available document type permissions.

Create
Read
Save
Release
Publish
Set Offline
Delete
Restore
Clone
Protect

It is not possible for any role to have the permission to publish a document without also having the permission to set it offline. Therefore, if you grant a role the permission Publish for a document type, Set Offline will also be granted.

You may set some, none or all document type permissions for each document type. You can also grant or revoke all document type permissions for a single document type at once via the context menu.

Permissions for New Document Types

If a new document type and a configuration for it have been created, the system role admin will have all permissions regarding this document type automatically. No other role will have any permissions on a new document type, even those who have created the new document type themselves. Every permission has to be assigned explicitly by an administrator (not someone with the role admin, but someone with the system permission Administrator).

Structure Node Permissions

Structure node permissions restrict operations to the enabled structure nodes. Some of these permissions affect just the structure node itself. Other structure permissions additionally depend on document type permissions. The different structure node permissions are all listed and explained in this section.

Keep in mind that each role automatically has reading access to the system site, since it is the location for select values, paragraph styles, etc, which each user has to be able to read. Keep also in mind, that a user without the system permission Administrator is not able do read or edit the system site or any of its children, nor to see them in the structure view.

Edit Documents

Documents at a structure node may only be edited, if this permission is set for that structure node. This permission also depends on the document type permissions. Thus, to edit a document at a structure node, a user has to have both the permission to edit documents at the structure node as well as the one to edit documents of that type (see: Document Type Permissions further above). For example, if a user has the permission to Edit Documents for the structure node home, but lacks the permission to edit documents of the type sophora-content-nt:story, he still won't be able to edit (create, save, ...) any story documents; in particular, he won't be able to edit any stories below the structure node home. Implies the Read Documents permission.

Edit Structure

This permission allows a user to create new subordinate structure nodes, or to rename, publish or delete existing ones.

Publish Default Document

Beside the corresponding document type permissions, this permission must be granted to a user, so he is able to publish the default document of a structure node.

Read Documents

Documents at a structure node may only be read by a user, if this permission is set for that structure node in one of his roles. This permission also depends on the document type permissions. Thus, to read a document at a structure node, a user has to have both the permission to read documents at the structure node and to read documents of that type (see: Document Type Permissions further above).

Because a user has to be able to read a document when he edits one, the permission Read Documents will be granted to a role automatically, if the permission Edit Documents is set.

You can set or remove all of these structure node permissions for one specific structure node at once using the context menu. This way you can also remove all permissions from all subnodes, or assign the set of permissions of a node to all subnodes.

Moving Structure Nodes

Modifying the Order of Structure Nodes

To allow a role to modify the ordering of structure nodes, the permission Edit navigation on the parent structure node is required. Thereby, the ordering of all immediately subordinate nodes may be changed (this can be done by dragging the selected structure node within the Structure view). To be able to publish this modified order, a role has to have the permission Edit structure on the parent node.

An example: To enable that the given role (whose structure node permissions are shown in the subsequent figure) may change the order of the immediately subordinate nodes of trendcities, the permission Edit navigation is selected at this node. Note, that a role with this configuration cannot alter the order of the subnodes of copenhagen. If the role shall be able to publish these changes, it has to have the permission Edit structure for the parent node (demosite in this case).

Moving Structure Nodes Across Multiple Layers

If a role should be allowed to move a structure node across multiple layers, it requires a combination of permissions on both the source and the target node of the structure node to be moved:

Source node:

Edit navigation on the former parent node of the structure node to be moved: Enables, that the ordering may be changed at all.
Edit structure on the former parent node of the structure node to be moved: The removal of a structure node is automatically published immediately.

Target node:

Edit navigation and Edit structure on the new parent node of the structure node to be moved: This allows to add a new child node.
Edit structure on the node superior to the new parent node: Required to publish the changes at the new parent node. (Thus, this permission is not mandatory for actually just moving the structure node.)

Required Permissions to set Offline and Re-publish Structure Nodes

In order to set offline or re-publish a structure node, a role needs to have the system permissions Administrator and Mass Operations in addition to the structure node permission Edit structure.

Permissions for New Structure Nodes

If a new website at the top level is created, no role will have any permissions on that site, except for the system role admin. An administrator has to assign them explicitly afterwards. If a new structure node is created, every role will automatically have the same permissions on the new structure node as they have on its already existing parent node.

Proposal Section Permissions

Proposal section permissions restrict operations upon document proposal sections. The available permissions for each proposal section are:

Read: Proposals in this section can be read. Without this permission, a user cannot see this particular proposal section at all. Note, that the user must also have the document type permission Read for a document's type to be able to read the correspondent proposal.
Edit: The user can edit a proposal's comment and validity duration in this section. If a proposal is offered in different sections, a user can edit it when she has at least the edit permission for one section in which the proposal is offered. Implies the Read permission.
Add: The user can add proposals to the section. Implies the Read permission.
Delete: The user can delete proposals from the section. Implies the Read permission.

Permissions for New Proposal Sections

If a new proposal section is created, no role will have any permissions on it initially - neither the role admin, nor any other one. All permissions have to be assigned explicitly by an administrator.

Tab Permissions

These permissions configure which of the flexible document tabs a user can see or edit. The available tab permissions are:

Read: The user can see the tab and its content, but cannot edit the properties which are shown on the tab. If a user does not have the read permission for a tab, the tab is hidden, i.e. not shown along with the other tabs at the bottom of the document editor.
Edit: A user needs this permission to edit the properties which are shown on the tab. This permission is only available for form and system tabs. Browser tabs make no distinction between read and edit mode. Implies the Read permission.

Within the tab permissions section, you can double click on any tab entry to open the according tab document.

Permissions for New Tab Documents

When a new tab is created, read and edit permissions for the tab are given to all roles automatically.

Permissions on Input Fields

By default, users can edit all input fields of documents they are allowed to read and save (except for those fields that are defined as "Read only" explicitly). Optionally, each input field can be configured to require further permissions from users.

Restrict Editing of Input Fields by Document Type Permissions

Input fields can be configured in a way, that only users with a specific document type permission are allowed to edit the field. For example, you may want to configure the title of a document in a way, that only users who can also publish their changes are allowed to edit the title.

To do so, simply pick all the document type permissions that should be required to edit the property in the corresponding document type permissions picker of the property configuration. If no document type permission is checked, users do not need a specific document type permission to edit the property. Otherwise, only administrators and users that have all required document type permissions for the document type the property belongs to can do so.

Note that this permission check only works on properties of creatable node types, not on reference node types or group node types.

Restrict Editing of Input Fields by Roles

An input field can also be made editable only for users having a certain role. Only administrators and users who belong to at least one of the specified roles are allowed to edit the field. For all other users, the field appears read only. The required roles can be selected within the property configuration wizard of the administrator section of the DeskClient by a role picker. By default, all roles are selected.

Restricting input fields by roles and document type permissions will have an inclusive effect on the editability of the specified property. This means that restricting the role to 'guest' and to the document type permission 'publish' implies, that users who want to edit the property must have the role 'guest' and should at least be allowed to 'publish' the document.

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.

Managing Roles