IPS_AddPermissionToRole

 bool IPS_AddPermissionToRole (string $Role, int $ObjectID, string $Operation, bool $Recursive) 

Parameters

Returns

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

Description

The function grants the role Role the permission to perform Operation on the object ObjectID. All users the role is assigned to thereby receive this permission.

If Recursive is enabled, the permission applies to the object and all objects below it – a recursive permission on the root object (ID 0) therefore applies to all objects. A permission is identified by ObjectID, Operation and Recursive together; the same ObjectID and Operation can therefore be added once recursively and once non-recursively.

Operation must be an operation registered in the system, otherwise the function fails with "Cannot verify unsupported operation". The operation is case-sensitive. Currently there is the operation VISUALIZATION (access to a visualization with all its objects). It is registered as soon as a visualization instance (e.g. Tile Visualization) exists and is checked against the ID of the visualization instance.

The checks are performed in this order: operation, role ("Role with name '…' does not exist"), object ("Object #… does not exist"). If the same permission already exists, the function fails with "Role already has this permission".

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

// The role may open the visualization with the ID 12345
IPS_AddPermissionToRole('Residents', 12345, 'VISUALIZATION', false);