- NAME
- REQUIRES
  - RT::Record::Role
- PROVIDES
  - RegisterRole
  - UnregisterRole
  - Role
  - Roles
  - HasRole
  - RoleGroup
  - CanonicalizePrincipal
  - AddRoleMember
  - DeleteRoleMember
  - LabelForRole

# NAME

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

# REQUIRES

## RT::Record::Role

# 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 );

## HasRole

Returns true if the name provided is a registered role for this class. Otherwise returns false.

## RoleGroup

Expects a role name as the first parameter which is used to load the RT::Group for the specified role on this record. Returns an unloaded RT::Group object on failure.

## CanonicalizePrincipal

Takes some description of a principal (see below) and returns the corresponding RT::Principal. `Type`, as in role name, is a required parameter for producing error messages.

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