Skip to main content

Roles

Roles can be seen as distinct tasks or activities of an application. It is best practice to define roles during development, since it requires detailed knowledge of the application's functionality.

You can add or modify roles in the Roles screen. You should carefully evaluate the tasks or activities to minimize overlap in rights between different roles. Furthermore, clear and consistent role naming is essential for the IAM administrators who are responsible for managing application authorizations. Since IAM administrators often have limited insight into the application's functionality, they must be able to determine the purpose of a role from its name and description. Roles are often named after the corresponding activity, such as Approve hours or Report a ticket.

Set up a role​

Create a role​

To create a role:

menu Access control > Roles > tab Role > tab Form

  1. Enter a name for the Role. We advise you to use lowercase characters, which is a common convention to maintain consistency and readability.

    note

    In IAM, the role translations are shown so that main administrators, application administrators, and application owners can see the roles in their own language.

  2. Optional: Select the Role group from the drop-down list. See Create a role group. As soon as a role is assigned to a group, the group appears in the grid so you can drag/drop other roles into it.

  3. Only for the administrator role: select the checkbox All rights. All other roles should provide a minimum set of rights required for the corresponding task or feature.

  4. Only for public API calls: select the checkbox Allow as public API. For more information, see Public API roles.

  5. Synchronize the role to IAM to make it available there. For more information, see Synchronization to IAM

If necessary, you can add a tag to a role in tab Role tags. For more information, see Tags.

Create a role

Create a role group​

Role groups are a grouping of roles to support setting up and viewing role authorization. You can use them to display roles in a logical and process-oriented manner.

  • The role translations are synchronized to IAM so that the main administrators, application administrators, and application owners can see the roles in their own language.
  • For users who create Personal Access Tokens (PATs) for their application, role groups give context to the roles (permissions) in the PAT screen. Add a good translation that they can understand. Without a role group, the roles are listed in a virtual group Miscellaneous.
note

Do not confuse role groups with default user groups and modules. For more information, see Default user groups and Modules.

To create a role group:

menu Access control > Roles > tab Role groups > tab Form

  1. Enter a name for the Role group. We advise you to use lowercase characters, which is a common convention to maintain consistency and readability.
  2. Go to the tab Translations and add a translation that users can understand.

The role group is now available for selection if you create or edit a role.

Public API roles​

To integrate your application with other systems, you can use Indicium calls with authentication. For example, as a client application or with an OpenID provider.

However, methods like webhooks or subscriptions do not always allow authentication.

In these cases, you can make the API call public for access without authentication. You can use this for actions like processing appointments and emails with Microsoft Graph. For more information about the base URL for a public API call, see Public API call.

note

You can only use this for individual API calls. Authentication is always required for your application if you use it with the Universal GUI.

To make a role suitable for a public API call:

menu Access control > Roles > tab Role > tab Form

  1. Select the checkbox Allow as public API. This option does not affect how the role is used in a GUI.
  2. Configure the role by assigning rights for objects. See Assign role rights to a role.
  3. Synchronize the role to IAM as usual.
  4. In IAM, an application administrator or application owner can complete the configuration. See Configure a public API role in IAM.

Assign role rights to a role​

After you have created a role, you can assign role rights to it that define what a role is allowed to do with an object. Rights can be assigned to the following objects: menus, tables, tasks, reports, process flows, and subroutines. Examples of role rights are Read, Insert and Delete.

To assign role rights to a role:

menu Access control > Roles > tab Role

  1. Go to the tab of the object type, for example Tables, that you want to assign role rights to.

  2. Execute the task Assign rights assign rights or press Ctrl + T.

  3. Select the rights you want to assign by doing one of the following:

    • In the group Current object, select the rights you want to assign, for example Read.
    • For the object type Tables, you can select a Preset in the group Rights preset:
      • No rights - All rights checkboxes are cleared or left empty.
      • Read rights - Only read rights for the current object are included. The Include children preset is automatically set to Excluded.
      • Full rights - All rights for the current object are included. The Include children preset is automatically set to Included.
      • Custom - This option is automatically selected if you deviate from one of the previous options.

  4. If available, the checkbox Make parent rights available is enabled. This indicates that the required rights are granted to the parent objects of the selected object. If you do not wish to apply parent rights, clear the checkbox.

  5. If applicable, select the rights you want to assign to children by doing one of the following:

    • In the group Make child rights available, select the rights you want to assign, for example Table report rights.

    • For the object type Tables, you can select a Preset in the group Include children preset:

      • Included - All child rights checkboxes are automatically selected.
      • Excluded - All child rights checkboxes are automatically cleared.
      • Custom - This option is automatically selected if you deviate from one of the previous options.

  6. In the group Changes can be reviewed, select one of the following options:

    • Execute immediately - the changes are executed immediately.
    • Review changes - the changes can be reviewed before they are executed.

  7. Select Execute. If you have selected Review changes, an Enrichment screen will appear where you can review your changes.

Assign role rights to an object

Access types​

Available rights​

menu Access control > Roles > tab Tables/Tasks/Reports/Process flows/Subroutines/Menus

For each role, the colored icons indicate the resolved rights of an object, based on the granted rights and the availability:

  • Unauthorized Unauthorized (no rights) - The data is unknown to the user interface and any API, so it is impossible for the user to see the data or to approach the data through Indicium. This is the safest option when it comes to data security in general and to protect sensitive data in accordance with GDPR laws.
  • Visually hidden Visually hidden - The user is not allowed to see the data in the user interface, which is generally safe, but in some cases the data might still be approached through Indicium.
  • Read-only Read-only - The user can see the data but has no rights to add, edit or delete data.
  • Granted Granted (editable) - The user has more rights than read-only, for example, the right to read and to edit data. Other possible rights are to add and delete data.

Granted, read-only and visually hidden can be applied by combining two settings:

  • Column type in the data model (menu Data > Data model > tab Tables > tab Columns).
  • Access type (menu Access control > Roles > tab Tables/Reports/Tasks).
  • To fully anonymize data, see: Data sensitivity.
note

Unauthorized columns​

For columns, the option Unauthorized is set automatically by the Software Factory. It also combines the Column type and Access type to decide whether a column is unauthorized: if either the Column type or the Access type is hidden, the column will automatically get 'Unauthorized' as Effective access type.

Unauthorized column Unauthorized column

Unauthorized task and report parameters​

The same applies to task and report parameters. The first setting the Software Factory uses is the Column type used in the Task parameter or Report parameter (menu Processes > Tasks/Reports > tab Task parameters/Report parameters). The second setting is the parameter's Access type (menu Access control > Roles > tab Tasks/Reports > tab Task parameters/Report parameters). If either the Column type in a task or report parameter or the Access type applied to the task or report parameter is hidden, the column will automatically get 'Unauthorized' as Effective access type.

Unauthorized report parameter Unauthorized report parameter

Exceptions (never unauthorized)​

There are a few exceptions to these rules however. In some instances a column will never be unauthorized but only hidden because making data unauthorized would break the user interface:

  • A role is an administrator role with All rights assigned to it.
  • A column is used as a primary key.
  • A column is used as the primary look-up display column.
  • A column is used as a conditional layout target.
  • A column is used as a conditional layout condition.
  • A column is used by any extender in any way, shape or form.
  • A column is used in a tree for grouping (parent or child), display or icon (base or variant).
  • A column is used in default sorting of a variant default sorting.
  • A column is used by another column in the same role as look-up display field.
  • A column is used by a granted cube field in the same role.

The effective access type explained​

To get a better understanding of the effective access type, an explanation is available in the screens:

  • For table (variant) columns: menu Access control > Roles > tab Tables > tab Columns
  • For task (variant) parameters: menu Access control > Roles > tab Tasks > tab Task parameters
  • For report (variant) parameters: menu Access control > Roles > tab Reports > tab Report parameters

  1. Execute the Explain the effective access type task Explain effective access type to view why the column or parameter has certain rights.

    The reason for the effective access type is explained in a pop-up. See also Access types.

  2. Execute the Show variant effective rights task Explain to view why the variant column or parameter has certain rights.

Was this article helpful?