Core | Essentials | DAM (4.37)

# Permissions and Presets

With permissions and presets, administrators can define how users can use the modules and records in the 4ALLPORTAL. The system differs between:

  • Native permissions which are a module's basic permissions for user rights "Module access", "Main menu entry", "View a record", "Delete", "Edit", "Assign", and "Create".
  • Feature permissions for module specific settings admins can edit to make further definitions for a module's features (e.g. "Allow image editor" or "Allow import tagging").
  • Presets for global or module specific settings users can edit (e.g. to define a theme, the ZIP download name, or individual keyboard shortcuts).

Permissions and presets are the basis on which the Role configuration is made.

# Managing Permissions and Presets

# Configure

  • Admins can change a role's rights and edit the default native permissions, feature permissions and presets in the Role configuration (admin snap-in General system configuration/User settings/Role configuration, tabs Advanced settings and Role-based module settings).

  • Users can change available presets themselves in their profile.

# Edit, Delete, Create

Admins can edit, delete, or create default permissions and presets in admin snap-ins:

  • Feature permissions (to create and manage global feature permissions and presets as well as feature permissions and presets that apply to all modules)
  • {module}/Feature permissions (to create and manage module specific feature permissions only for the selected module)
  • Native permissions to define native permissions for the selected module
  • Module definition to allow a module's presets to show in a user's profile

You also find technical information on all permissions and presets in these snap-ins.

# Storage and Editing

The default values of permissions and presets are stored in the following XML files:

  • global/defaults/native_permissions.xml
  • global/defaults/permissions/ (with an entry for each global feature permission or preset)
  • modules/MODULE/setup.xml
  • modules/MODULE/native_permissions.xml
  • modules/MODULE/ois.xml
  • modules/MODULE/permissions/ (with an entry for each module-specific feature permission or preset)
  • modules/file/check_references.xml (only if you work with 4App DAM)

If you overwrite and change the standard values

  • in your permission admin snap-ins: your changes are stored in a copy of the respective XML file in your custom folder (reload and logout/login required).
  • in your role configurations or the user profile, these changes are stored in the database.

The XML files are only read on reload or restart of the 4ALLPORTAL.

Please note: Before 3.10, the system worked with .4apmsetup files. For details, take a look here.

# Storage in the Database

The information of the role configuration and user settings is stored in database table featureperm_and_preset_store:

Name Type Description
id CEID Generated UUID in the database
client_type CEInteger client type (e.g. web, desktop, mobile)
preset_type CEInteger feature permission / preset
key CEVarchar key for feature permission / preset
module CEVarchar Core Engine module
parent_type CEVarchar defines whether the entry applies to the role or the user
parent_id CEID ID from table ce_role or user, depending on the parent_type
admin_access CEInteger AccessType - defines the visibility for the admin
user_access CEInteger AccessType - defines the visibility for a user
value_type CEInteger defines in which database field the content is located
value_boolean CEBoolean field for content
value_double CEDouble field for content
value_string CEVarchar 255 field for content
value_text CEText field for content

Please note: For admin access, feature permission global.has_superadmin is required. This permission is automatically assigned to role 1 at Core Engine start.

The following values are supported in the database:

Type Value Parameter
ClientTypes ALL 0
ClientTypes SYSTEM 1
ClientTypes WEB 2
ClientTypes TABLET 3
ClientTypes PHONE 4
ClientTypes DESKTOP 5
ClientTypes JAVA_API (Deprecated) 6
ClientTypes APPLICATION_PLUGIN 7
ClientTypes EXTERNAL 8
PresetType FEATURE_PERMISSION 1
PresetType PRESET 2
ParentType USER 0
ParentType ROLE 1
AccessType READ 1
AccessType EDIT 2
ValueType VARCHAR 0
ValueType TEXT 1
ValueType BOOLEAN 2
ValueType DOUBLE 3

# How do Permissions Apply?

The modules' native permissions, feature permissions, and presets of a user are determined by the Core Engine when creating the session container.

For the hierarchy order of native permissions, please refer our role configuration documentation.

Feature permissions and presets are determined using three levels, where the next higher level overrides the previous level:

  1. default settings of the module in folders global/defaults/permissions and modules/MODULE/permissions
  2. individual role settings of the Core Engine role assigned to the user
  3. individual user settings (presets)

Unlike other native permission default rules, feature permission and presets module settings do not overwrite the global settings.

# Native Permissions

Native permissions can be seen as the basic rights set of a role. They are set per module and define whether a role's user has:

  • Module access in general
  • a Main menu entry for this module
  • the rights to view a module's records
  • the rights to delete a module's records
  • the rights to edit a module's records
  • the rights to assign other users/roles to a module's records
  • the rights to create a module's records

Native permissions and rights are configured in the role configuration.

# Permission Values

For each native permission, different values can be assigned (e.g. "Yes", "No", "Only own", etc.). A new 4ALLPORTAL comes with default values for each module. They always apply if a value had not been changed manually to another value.
Default values are stored in the system's XML files (storage).

  • An overview of all possible permission values can be found here.
  • An overview of what "default" means can be found here.

Admins can overwrite the default by assigning further or fewer rights to a role in the role configuration. According to the given rights, NativeOperations are only displayed for the data records to which the user has authorization.
Customized values are stored in the database (storage).

Admins can as well change the rights behind the "default"-value in admin snap-in Module configuration/{module}/Native permissions.

# Native Permissions Snap-in

Use snap-in Module configuration/{module}/Native permissions to check or change the native permissions for the selected module.


Native permissions snap-in of the "Tasks" module

Changes you make here affect all module permissions that are set to "Default" in the Role configuration.
If you change a native permission value here, this changes the default. It will not be written to the database but overwrite the respective module's XML file.

If role-specific permissions have been assigned in the Role configuration (i.e. a permission is not set to "Default"), that custom permission applies, and the value set here does not apply.

Please note: The global native permissions cannot be changed via an admin snap-in.

You can find an overview of all global and module-specific native permissions here.

# Feature Permissions

Feature permissions are permissions that extend the native permissions. The system considers the permission values of individual features at system start. They can be read via code, conditions, layouts, renderers, the template engine, etc.
The default values are stored in the file system's XMLs (storage).

Feature permissions apply per feature and per role. Certain features of a module can thus be enabled or disabled for a role. Some features are disabled by default and must be enabled in their feature permissions if you want your users to use it.

Feature permissions can be both global and module specific, they can be used for all modules or only for a certain module.
Example: Feature permission "allow_version" (to enable/disable versioning of records) can be set for all modules, where feature permission "allow_image_editing" is Files module specific.

Feature permissions can only be changed by an admin ("has_superadmin"). Admins can:

# Configure Feature Permissions

To configure a module's feature permissions, go to admin snap-in General system configuration/User settings/Role configuration, tab "Role-based module settings". Click on a module from the list to open its Permission pop-up:


Feature Permission pop-up of the "Collections" module in the role-based module settings

The pop-up lists all the feature permissions and presets available for that module. These can be both global and module-specific. If a module includes system e-mail notifications, you can predefine whether users in this role should receive these e-mails.

Please note: You can only set a default for presets and notifications (which are also presets) here. Both can be changed by the users themselves in their profile details.

# Edit or Create Feature Permissions

To edit the default and create feature permissions, go to admin snap-ins

  • General system configuration/User settings/Feature permissions
    for global permissions that either appear once in the system (like has_superadmin) or apply to all modules (will appear in every module's permission pop-up/a user's profile, like use_recent_object)
  • Module configuration/{module}/Feature permissions
    for module specific permissions that apply only to a specific module (will appear only in that specific module's permission pop-up/a user's profile)

These snap-ins give you an overview of all permissions (and presets). The values as shown in a snap-in apply to all roles if no custom changes were made in the role configurations.
Double-click an entry for a detail view:


Feature permission snap-in of the "Files" module with detail view of permission "allow_evolution_tree"

Field Attribute Description
Name name Unique key for the permission/preset which can be used in conditions.
Authorization type permission_type Tells if this is a feature permission or a preset (presets can usually be changed by a user).
User is allowed to edit the value user_access Tells whether users are allowed or not allowed to edit this permission's/preset's value in the database.
Admins always have the right to edit.
Grouping group Tells if this permission/preset is sorted to a specific group in a module's permission pop-up (e.g. "Rating").
Value type value_type Tells whether the permission's/preset's type is varchar, text, boolean, or number (which also affects the display in the permission pop-up).
Default value value_boolean, value_double, value_string or value_text Tells the default value for this permission/preset (e.g. "false" in boolean permission "has_superadmin" or "automatic" in varchar permission "gui_theme").
Value options
(type "varchar" only)		 value_option Tells if a permission/preset uses a value option (which can be found in a module's snap-in Value options, e.g. permission "warning_time" in the tasks module).
FieldRenderer field_renderer Gives you the option to add a field renderer configuration in XML to specify e.g. attributes, value options, default values, or labels (more details]).
Order order Use this field to control the sorting of a permission/preset in a module's permission pop-up. The lower the number, the higher the position in the pop-up.
Note that the default value is 0 and the group with the lowest number will appear first.
Note that permissions with the same value will be sorted by their translation.
Apply to each module * propagate_to_modules If set to "true", this feature permission/preset appears in all module permission pop-ups.

* Switch only appears in the global feature permission snap-in.

Please note: A client type (e.g. for web, desktop, smartphone ...) cannot be set via this snap-in. The database supports "client_type", though.

Storage of Changes

If you overwrite and change the standard values, your changes are stored in a copy of the respective XML file in your custom folder (reload and logout/login required).

# Presets

With presets, users themselves have the possibility to change certain permissions. E.g. preset "keyboard_shortcut_windows" for the custom assignment of shortcuts.
Users can configure their presets in their profile.

Admins can get an overview of all global presets in admin snap-in General system configurations/User settings/Feature permissions and of all module specific presets in admin snap-in Module configurations/{module}/Feature permissions. Here, they can also edit a preset and e.g. change a user's edit right (details).

Admin Rights

Note that admins are not allowed to read the presets of a user. But they can

  • remove modules from the profile's tab "System settings" (see below)
  • edit a preset's edit right

# Personal Settings: Presets in the GUI

In the GUI, most presets are accessed via a user's profile, tabs "System settings", "Shortcuts", and "Notifications". Presets can be global and available for every module as well as module specific.


Tab "System settings" offers a list of general and module specific presets (selected: tab "Generally")

# System Settings

Tab "Generally" has presets to configure the general looks of the system:

  • Theming (gui_theme): Users can select a theme if they have several to choose from (theming details)
  • Menu structure (module_menu_structure): Users can change the order of modules in the mega menu, select their startup module, select favourites, and hide modules from the mega menu (the default structure is defined by admins in the role configurations).

Restrict General Presets

Admins can restrict a user's right to edit both presets "Theming" (gui_theme) and "Menu structure" (module_menu_structure).
For this, the presets' right "User access permission" must be changed from "Edit access" (default) to "Read access". Both can be found in admin snap-in General system configuration/User settings/Feature permissions.

Below "General" is a list of modules. Each module has global as well as specific module presets to configure specific features:


Presets for module "File transfers" with global preset "Allow history" (filetransfer.use_recent_object) and module specific presets

Per default, modules "Files", "File transfers", "User" and "Collections" are displayed.

Define the List of Modules

Admins can define what modules are listed here for users to see. To edit this list, go to a module's snap-in Module configurations/{module}/Module definition and edit field "Personal settings" (more details).

# Shortcuts

Users can customize the default shortcuts in tab "Shortcuts". The default depends on either windows (keyboard_shortcut_windows) or mac (keyboard_shortcut_mac):

# Notifications

Users can activate and deactivate system e-mails in tab "Notifications". A list shows all modules available to a user. When clicking a module, all possible e-mail notifications are listed, allowing users to individually disable e-mails they no longer wish to receive.

Per default, the e-mails of modules Tasks, Collections, Markups, and Approvals are available here. All notifications are active per default:

Define a Default

Administrators can make default notification settings for a role in a module's feature permission pop-up (via admin snap-in General system configuration/User settings/Role configuration, tab Role-based module settings).

# Create a Custom Feature Permission or Preset

If you want to create a new permission or preset, you need to ...

  1. go to admin snap-in General system configuration/User settings/Feature permissions for a global permission, or Module configuration/{module}/Feature permissions for a module specific permission
  2. click "Create" in the toolbox
  3. configure all snap-in fields (details) depending on your needs.
    • User is allowed to edit the value: For feature permissions, the user should get only read access. For presets, they need edit access.
  4. save your permission or preset, reload your 4ALLPORTAL and login again. It will now show in a module's permission pop-up/a user's profile.
  5. translate the keys in admin snap-in Translation studio or its respective properties file in the locale folder(s).
  6. implement it. You can use a permission or preset everywhere conditions are possible to use, e.g. in actions, module configurations or user-defined module authorizations.

Please note: Newly created feature permissions are not automatically implemented. You can use them in action configurations, layouts, or object renderers for example.

Attention: If you make changes in a custom permission/preset and use toolbox action "Restore to default", all fields will be cleared (because the system default of form "Create new" is blank)!

# Field Renderer Configuration

The system automatically generates a field renderer for permissions and presets. If you want to change that default, you may add all possible field renderer specifications to field FieldRenderer in XML, e.g. to:

  • set new label keys for the permission, its tooltip, its group, its placeholder
  • use field attributes like visual_type
  • set a default value
  • make it read-only
  • change the size
  • delimiter value options

Example:

If you want a preset to have a hidden text entry, you could use visual_type password like this:

<field_renderer>
        <field_renderer_attributes>
            <entry key="visual_type">password</entry>
        </field_renderer_attributes>
</field_renderer>

Please note: Use only specifications allowed for element <field_renderer>. Element <field> with tags <type> or <name> must not be added here, they are set in the snap-in fields above. <field> values will be ignored here.

# Naming Rules

The naming of feature permissions and presets must follow some rules:

  • Global permissions start with "global" (global.has_superadmin)
  • Module permissions start with the respective {module name} (contact.allow_create_notification)
  • Do not use characters :, \\, /, *, ?, |, <, >, ": Feature permissions and presets with one of these characters in their file name will not be saved.
    • For already existing names, these characters will be converted to _.

Important

If a feature permission or preset with an old name was used, the source code or front end code has to be changed to support the new name.

# .4apmsetup Conversion With 3.10

From Core Engine release 3.10, the system works only with the following configuration files:

  • global/defaults/native_permissions.xml
  • global/defaults/permissions/
  • modules/MODULE/setup.xml
  • modules/MODULE/native_permissions.xml
  • modules/MODULE/ois.xml
  • modules/MODULE/permissions/
  • modules/file/check_references.xml (only if 4App DAM is active)

They replace former configuration files

  • global/defaults/module.4apmsetup
  • global/defaults/permission.4apmsetup
  • modules/MODULE/setup.4apmsetup

Versions 3.10 and higher require the new split configuration files. The respective configuration admin snap-ins (also released with 3.10) work only with these new files and folders.

Automatic upgrade tool: With an upgrade to 3.10, your former configuration files from apps and custom folder will be automatically converted.

Attention!

Note that only version 3.10 has the automatic upgrade tool. In 4.0, the automatic conversion is deleted.

Custom apps: It is required to upgrade your custom apps with the new files before upgrading your 4ALLPORTAL to 4.0.

Make sure you do not skip version 3.10 if you require the automatic file conversion.

# File Differences

Splitting the configuration files prevents them from being overwritten by 4Apps or custom configurations. Thus, new standards that come with an 4App upgrade can be applied to your system even if you work with custom permissions or configurations.

Also, we removed the following methods and types:

  • Block allowed_method is removed from .4apmsetup configuration files and not used anymore.
  • client_type from feature permission and preset configurations removed. Note that the database will further support field client_type.

# Automatic Conversion Tool

As long as an app has not yet been upgraded, former configuration files

  • global/defaults/module.4apmsetup
  • global/defaults/permission.4apmsetup
  • modules/MODULE/setup.4apmsetup

from 4Apps, custom apps, and the custom folder are automatically converted to the required new files.

Only version 3.10 has the automatic upgrade tool with the following functions. In 4.0, the automatic conversion is deleted.

# Apps

For 4Apps and custom apps, the required files are converted and created automatically in folder _runtime with each system start.

  • The system converts all XML elements processed. If an error occurs, a log entry is written to folder custom/errors/upgrade_4apmsetup.
  • If it is not possible to read a file, the system tries to read with ignore additional XML elements, and again writes a log entry if that is not possible.
  • If it is not possible to convert a 4apmsetup file, the module will be ignored on 4ALLPORTAL startup.

Please note: 4apmsetup configuration files cannot be converted automatically in their 4App zip archive. Therefore, this conversion is performed again with every system start until the 4App's configuration files have been upgraded (see How to upgrade a 4App).

How do I know the automatic conversion worked?

Check your 4ALLPORTAL log or for folder custom/errors/upgrade_4apmsetup after upgrading to 3.10. If the folder does not exist or is empty, everything is OK. If there is a folder containing errors, follow our instructions from here.
Delete this folder when all problems logged here are solved.

# Custom Folder

All files from the custom folder are also converted. This happens only once, at startup after upgrading to 3.10.
For this, update script 107.LO.xml from Core Engine (cmconfig-4app/updates) is used:

  1. Creates a backup of the customer folder (in 4App 4allportal-customization in folder apps_repository)
  2. Creates a _runtime folder without any custom changes
  3. Checks if the content of the custom files differs from the content of the just created files in _runtime folder
  4. Converts the old configuration file(s) in the custom folder to new configuration files in the custom folder and delete the old files
  5. Deletes the intermediate _runtime folder
  6. The backup in 4App 4allportal-customization remains

With database select

select description, name, type, version, status from update_mngt where description = 'Convert content of *.4apmsetup files in the customer folder';

you can check the result:

description name type version status
Converts contents of *.4apmsetup files in the customer folder 107.LO db 20210201-0001 3

If status is 3 everything is OK, and the content from your custom folder upgraded. The script will not run again.
If status is not 3, the system tries to execute the script on next startup. Other fields of the table contain addition information if errors occur.

# Log Warnings and Errors

Warnings: The 4ALLPORTAL log should not contain warnings because of old configuration files. Check your log for the following warning:

  • [WARN] [2021-07-07 10:01:28,630] [main] c.c.c.m.s.s.i.Convert4apmsetupOnStartupUtil Support of setup file {file} from {app} ends. Please change before upgrade to next major version.
    • {file}: the path to an old configuration file
    • {app}: name of the 4App (if file from 4App) or null (if file from your custom folder)

This is only a warning, to remind you of upgrading custom 4Apps. The system should work with the automatic conversion until the next major release 4.0.

If warning "Please change before upgrade to next major version" shows, please inform the creator(s) of the 4App(s) and request to deliver an update until the next major release 4.0.

In case you are the creator of a 4App: Make sure you upgrade your custom 4Apps until 4.0 at the latest. Check here how to upgrade your 4Apps.

Errors: The 4ALLPORTAL log should not contain errors because of not readable old configuration files. Check your log for the following errors:

  • DefaultValidationEventHandler: [ERROR]: unexpected element (URI:"", lokal:"module_name"). Expected elements are <{}object_image>,<{}allowed_method>,<{}assigneduser_validation>,<{}defaults>,<{}friendlyname_template>,<{}show_in_role_config>,<{}create_table>,<{}additional_permission_assignments>,<{}enable_tree_structure>
    Location: line 3

    • These errors start with DefaultValidationEventHandler: [ERROR]. If they start with DefaultValidationEventHandler: [ERROR]: unexpected element, it may be no problem, because first read with validate elements and then without validate.
      • If unexpected elements are not needed: You have no problem. The 4ALLPORTAL will start. Please remove unused elements from setup files in your custom folder and inform the creators of the respective 4App that these elements must be removed.
      • If unexpected elements are needed: Inform the creator of the respective 4App that they will not be supported in the default setup files, and they have to create an own admin snap-in

  • [ERROR] [2021-07-07 10:22:00,115] [main] c.c.c.m.s.s.i.ModuleSetupFileUpgrader Exception reading setup file {file}
    ...

    • With this error it is not possible to parse the old configuration file. In this case you have to fix the file or remove it if it is not needed.
    • The ... means that there is a stack trace with additional information about the error.

# How to Upgrade Apps With New Configuration Files

From Core Engine version 4.0, only the following configuration files are supported:

  • global/defaults/native_permissions.xml
  • global/defaults/permissions/
  • modules/MODULE/setup.xml
  • modules/MODULE/native_permissions.xml
  • modules/MODULE/ois.xml
  • modules/MODULE/permissions/
  • modules/file/check_references.xml (only if 4App DAM is active)

From Core Engine version 4.0, all former .4apmsetup configuration files will not be supported anymore, and the automatic conversion ends.

  • 4ALLPORTAL 4Apps: If you download 4Apps from publisher 4ALLPORTAL you can be sure we upgrade for you.
  • Custom 4Apps: If you work with custom 4Apps, please make sure to upgrade as soon as possible (best before upgrading to 3.10, at the latest before upgrading to 4.0). .

There are two ways to upgrade a 4App:

# Use a Plain Installation

Do the following steps for one 4App you want to upgrade at a time:

  1. Install a new 4ALLPORTAL with all dependent 4Apps your custom 4App requires (e.g. Core Engine, DAM, Essentials which are converted already), but that does not require 4App Core Engine 4.0 or higher.
  2. Add all .4apmsetup configuration files from the custom 4App you want to update to your custom folder.
  3. Start your 4ALLPORTAL. The update script 107.LO.xml from Core Engine will convert all .4apmsetup files from the custom folder and delete the old configuration files.
  4. Copy the new files and folders to your custom 4App.
  5. Delete the old .4apmsetup configuration files from your 4App.

With a plain 4ALLPORTAL installation, only changes to the dependent 4Apps are created. This means for example, if your custom 4App contains a preset which is identical with a preset in one of the dependent 4Apps, no new file will be created.

# Upgrade With Class ModuleSetupFileUpgrader From Core Engine

Java class ModuleSetupFileUpgrader allows to upgrade the contents from a cmconfig-4app folder in a 4App project:

var service = new ModuleSetupFileUpgrader
service.setDeleteConfig(true); // this will delete old configuration files
service.setOverwrite(true); // this will overwrite new configuration files if exists
service.upgradeProjectFolder(Paths.get(".../4allportal-dam/cmconfig-4app"));

Attention

Upgrading with class ModuleSetupFileUpgrader has the disadvantage that files will be generated without knowledge of the dependent 4Apps. As a consequence, e.g. permission files are generated for feature permissions / presets which may just be the same as the file from the dependent project.

We recommend upgrading a 4App with this class only if it contains unique modules which are no part of other 4Apps. Else, manually check which files have to be added to the 4App.

← Role Configuration →

Request missing documentation