• NAME
• REQUIRES
  • RT::Record::Role
• PROVIDES
  • RegisterRole
  • UnregisterRole
  • Role
  • Roles
  • HasRole
  • RoleGroup NAME, CheckRight => RIGHT_NAME, Create => 1|0
  • CanonicalizePrincipal
  • AddRoleMember
  • DeleteRoleMember
  • ParseInputPrincipals
  • LabelForRole
• OPTIONS
  • Lazy Role Groups
  • CustomRoleObj
  • RoleAddresses

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 NAME, CheckRight => RIGHT_NAME, Create => 1|0

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.

If the group is not created yet and Create parameter is true(default is false), it will create the group accordingly.

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:

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 removed. If it returns false, the method will fail with a status of "Permission denied".

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

ParseInputPrincipals

In the RT web UI, some watcher input fields can accept RT users identified by email address or RT username. On the ticket Create and Update pages, these fields can have multiple values submitted as a comma-separated list. This method parses such lists and returns an array of user objects found or created for each parsed value.

ParseEmailAddress in RT::EmailParser provides a similar function, but only handles email addresses, filtering out usernames. It also returns a list of Email::Address objects rather than RT objects.

Accepts: a string with usernames and email addresses

Returns: arrayref of RT::User objects, arrayref of any error strings

LabelForRole

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

OPTIONS

Lazy Role Groups

Role groups are typically created for all roles on a ticket or asset when that object is created. If you are creating a large number of tickets or assets automatically (e.g., with an automated import process) and you use custom roles in addition to core roles, this requires many additional rows to be created for each base ticket or asset. This adds time to the create process for each ticket or asset.

Roles support a lazy option that will defer creating the underlying role groups until the object is accessed later. This speeds up the initial create process with minimal impact if tickets or assets are accessed individually later (like a user loading a ticket and working on it).

This lazy behavior is off by default for backward compatibility. To enable it, set this package variable:

    $RT::Record::Role::Roles::LAZY_ROLE_GROUPS = 1;

If you are evaluating this option for performance, it's worthwhile to benchmark your ticket or asset create process before and after to confirm you see faster create times.

CustomRoleObj

Returns the RT::CustomRole object for this role if and only if it's backed by a custom role. If it's a core role (e.g. Ticket Requestors), returns undef.

RoleAddresses

Takes a role name and returns a string of all the email addresses for users in that role.

← Back to index