RT 4.4.1 Documentation

RT::Record::Role::Roles

Go to latest version →

NAME
REQUIRES
- RT::Record::Role
PROVIDES

NAME

RT::Record::Role::Roles - Common methods for records which "watchers" or "roles"

REQUIRES

PROVIDES

RegisterRole

Registers an RT role which applies to this class for role-based access control. Arguments:

Name

Required. The role name (i.e. Requestor, Owner, AdminCc, etc).

EquivClasses

Optional. Array ref of classes through which this role percolates up to RT::System. You can think of this list as:

    map { ref } $record_object->ACLEquivalenceObjects;

You should not include RT::System itself in this list.

Simply calls RegisterRole on each equivalent class.

Single

Optional. A true value indicates that this role may only contain a single user as a member at any given time. When adding a new member to a Single role, any existing member will be removed. If all members are removed, "Nobody" in RT is added automatically.

Column

Optional, implies Single. Specifies a column on the announcing class into which the single role member's user ID is denormalized. The column will be kept updated automatically as the role member changes. This is used, for example, for ticket owners and makes searching simpler (among other benefits).

ACLOnly

Optional. A true value indicates this role is only used for ACLs and should not be populated with members.

This flag is advisory only, and the Perl API still allows members to be added to ACLOnly roles.

ACLOnlyInEquiv

Optional. Automatically sets the ACLOnly flag for all EquivClasses, but not the announcing class.

SortOrder

Optional. A numeric value indicating the position of this role when sorted ascending with other roles in a list. Roles with the same sort order are ordered alphabetically by name within themselves.

UserDefined

Optional. A true value indicates that this role was created by the user and as such is not managed by the core codebase or an extension.

CreateGroupPredicate

Optional. A subroutine whose return value indicates whether the group for this role should be created as part of "_CreateRoleGroups". When this subroutine is not provided, the group will be created. The same parameters that will be passed to "CreateRoleGroup" in RT::Group are passed to your predicate (including Object)

AppliesToObjectPredicate

Optional. A subroutine which decides whether a specific object in the class has the role or not.

LabelGenerator

Optional. A subroutine which returns the name of the role as suitable for displaying to the end user. Will receive as an argument a specific object.

UnregisterRole

Removes an RT role which applies to this class for role-based access control. Any roles on equivalent classes (via EquivClasses passed to "RegisterRole") are also unregistered.

Takes a role name as the sole argument.

Use this carefully: Objects created after a role is unregistered will not have an associated RT::Group for the removed role. If you later decide to stop unregistering the role, operations on those objects created in the meantime will fail when trying to interact with the missing role groups.

Unregistering a role may break code which assumes the role exists.

Role

Takes a role name; returns a hashref describing the role. This hashref contains the same attributes used to register the role (see "RegisterRole"), as well as some extras, including:

Class: The original class which announced the role. This is set automatically by "RegisterRole" and is the same across all EquivClasses.

Returns an empty hashref if the role doesn't exist.

Roles

Returns a list of role names registered for this object, sorted ascending by SortOrder and then alphabetically by name.

Optionally takes a hash specifying attributes the returned roles must possess or lack. Testing is done on a simple truthy basis and the actual values of the role attributes and arguments you pass are not compared string-wise or numerically; they must simply evaluate to the same truthiness.

For example:

    # Return role names which are not only for ACL purposes
    $object->Roles( ACLOnly => 0 );

    # Return role names which are denormalized into a column; note that the
    # role's Column attribute contains a string.
    $object->Roles( Column => 1 );

Principal: The RT::Principal if you've already got it.
PrincipalId: The ID of the RT::Principal object.
User: The Name or EmailAddress of an RT::User. If an email address is given, but a user matching it cannot be found, a new user will be created.
Group: The Name of an RT::Group.

AddRoleMember

Adds the described RT::Principal to the specified role group for this record.

Takes a set of key-value pairs:

Principal, PrincipalId, User, or Group: Required. Canonicalized through "CanonicalizePrincipal".
Type: Required. One of the valid roles for this record, as returned by "Roles".
ACL: Optional. A subroutine reference which will be passed the role type and principal being added. If it returns false, the method will fail with a status of "Permission denied".

Returns a tuple of (principal object which was added, message).

DeleteRoleMember

Removes the specified RT::Principal from the specified role group for this record.

Takes a set of key-value pairs:

PrincipalId: Optional. The ID of the RT::Principal object to remove.
User: Optional. The Name or EmailAddress of an RT::User to use as the principal
Type: Required. One of the valid roles for this record, as returned by "Roles".
ACL: Optional. A subroutine reference which will be passed the role type and principal being removed. If it returns false, the method will fail with a status of "Permission denied".

One, and only one, of PrincipalId or User is required.

Returns a tuple of (principal object that was removed, message).

LabelForRole

Returns a label suitable for displaying the passed-in role to an end user.

← Back to index