IPS_CreateRole

 bool IPS_CreateRole (string $Role) 

Parameters

Returns

If the function succeeds, it returns TRUE, otherwise FALSE.

Description

The function creates a new role with the name Role. A new role has no permissions yet. They are added with IPS_AddPermissionToRole. Afterwards the role can be assigned to any number of users with IPS_AddRoleToUser, who thereby receive all permissions of the role. Roles can also be managed in the Permission Control.

The name must not be empty ("Role cannot be empty") and must be unique, otherwise the function fails with "Role with name '…' already exists". The name is case-sensitive. The role @admin always exists and grants all permissions.

The executing user must be an administrator (see IPS_IsAdministrator), otherwise the function fails with "Administrator permissions are required for this action!".

Role management is only available with a license that includes the RBAC feature. Otherwise the function fails with "This function is only available for licenses with the RBAC feature enabled!". If more users exist than the license allows, the function fails with "Your license is currently limited to … users. Please consider upgrading the license to more users!".

Example

if (!IPS_RoleExists('Residents')) {
    IPS_CreateRole('Residents');
}

// Allow access to the visualization with the ID 12345
IPS_AddPermissionToRole('Residents', 12345, 'VISUALIZATION', false);

// Assign the role to a user
IPS_AddRoleToUser('anna', 'Residents');