Core Engine (3.10)

# Permissions and presets

With permissions and presets, administrators can define how users may use the modules and their records in the 4ALLPORTAL. We differ between:

  • Native permissions which are a module's standard permissions for the user rights Module access, Main menu entry, View a record, Delete, Edit, Assign, and Create.
  • Feature permissions to enable / disable specific module features or make further definitions for a module (e.g. "Allow image editor" or "Allow import tagging").
  • Presets for user-specific settings a user can edit (e.g. for a role's upload folder, the ZIP download name, or a user's keyboard shortcuts).

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

# Managing permissions and presets

Configuring default permissions and presets is done in the Role configuration, admin snap-in
General system configuration/User settings/Role configuration, tabs Advanced settings and Role-based module settings (click on a module). Some presets can also be configured in a user's Profile.

As soon as you change the system default role-specific, these changes are stored in the database (storage details).

Editing the default, deleting and creating permissions and presets can be done in admin snap-ins

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

Further module settings can be made in snap-ins

# Permissions storage and editing

The standard 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)

You can overwrite and change the standard values:

  • if you make custom settings in your admin snap-ins, these changes are stored in a copy of the respective XML file in your custom folder (reload and logout / login required)
  • if you make custom settings in your role configurations, these changes are stored in the database

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

# Feature permissions and presets storage in the database

The information of the role 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 NONE 0
AccessType READ 1
AccessType EDIT 2
ValueType VARCHAR 0
ValueType TEXT 1
ValueType BOOLEAN 2
ValueType DOUBLE 3

# How do permissions apply?

The native permissions for the Core Engine, for the single modules, the modules' feature permissions, and the presets of a user (e.g. "Does user X has reading rights for a file module's record?") are determined by the Core Engine when creating the session container.

# Native permissions

For the hierarchy order of native permissions, please refer here (role configuration documentation).

# Feature permissions and presets

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

Permissions are defined module-specific. They define whether a user has

  • Module access
  • a Main menu entry
  • the rights to view a record
  • the rights to delete a record
  • the rights to edit a record
  • the rights to assign other users or roles to a record
  • the rights to create a record

Permission values

For each right, different values (e.g. "Yes", "No", "Only own", etc.) are possible. You can find an overview and explanation of all possible permission values here.

Native permissions can be seen as the product standard or delivery status of a permission. They are shown as "default" in a module's permissions. They always apply if a value was not changed manually to another value.

According to the given rights, NativeOperations are only displayed for the data records to which the user has authorization.

Its values are stored in the system's XML files. You can overwrite these standard permissions by assigning further or fewer rights to a role in the role configuration.

# Native permissions snap-in

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


Native permission 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 and presets

Feature permissions and presets extend the native permissions of the Core Engine (read, write, create etc.). The permissions of the individual features are transferred to the Core Engine.

Feature permissions are assigned per feature. 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 only be changed by the admin (user with feature permission "has_superadmin").

A feature permission can be used for all modules or only for a certain module. E.g. 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.

With presets, a user themself has the possibility to change. E.g. preset "keyboard_shortcut_windows" for the custom assignment of shortcuts.
The admin is not allowed to read the presets of a user. They only get the possibility to delete keys with like ....

As soon as you change the system default, the custom settings from the custom folder apply.

Please note: The XML files will only be loaded on reload or restart of the 4ALLPORTAL.

  • If you want to enable or disable a feature permission, go to admin snap-in General system configuration/User settings/Role configuration.
  • If you want to edit or create or get technical details on a certain feature permission or preset, use the feature permission snap-ins.


Feature permission pop-up of the "files" module in the role-based module settings

# Feature permissions snap-ins

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

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

Please note: Newly created feature permissions are not automatically implemented. You can use them in action configurations, for example (more details).

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


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).
Administrator access permission admin_access Tells whether the admin has edit, read (= visible) or no rights for this permission's / preset's value in the database.
User access permission user_access Tells whether the user has edit, read (= visible) or no rights for this permission's / preset's value in the database.
Permission groups group Tells if this permission / preset is sorted to a specific group in the permission pop-up.
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 "user" in varchar permission "startup_module").
Value options 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).
For all modules * 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.

For the storage of feature permission and preset values in the database, please refer here.

# Create a custom feature permission or preset

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

  1. configure all snap-in fields like shown above, depending on your needs.
    • Administrator access permission: For feature permissions, the admin should get edit access. For presets only read access.
    • User access permission: For feature permissions, the user should get only read access. For presets edit access.
    • Selecting "No access" may cause problems when a user's rights are determined at system start.
  2. save your permission or preset, reload your 4ALLPORTAL and login again. It will now show in a module's permission pop-up.
  3. translate the keys in its respective properties file in the locale folder(s).
  4. 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.

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)!

# .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 updated 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.

# 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 {MODULENAME} (contact.allow_create_notification)
  • Do not use characters :, \, /, *, ?, |, <, >, " in their keys. Feature permissions and presets with one of these characters in their file name will not be saved.
  • In already existing keys, these characters will be converted to _.
  • If a key is used twice in a configuration file for a feature permission or preset, the first one is used, and an error is returned in the log.

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.

← Role Configuration →

Request missing documentation