- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
  - Create { PARAMHASH }
  - UpdateObjectCustomFieldValues
  - ValidateName STRING
  - GenerateAnonymousName
  - AnonymizeUser { ClearCustomfields => 1|0 }
  - ValidatePassword STRING
  - SetPrivileged BOOL
  - Privileged
  - Load
  - LoadByEmail
  - LoadOrCreateByEmail ADDRESS
  - ValidateEmailAddress ADDRESS
  - SetName
  - SetEmailAddress
  - EmailFrequency
  - URI
  - CanonicalizeEmailAddress ADDRESS
  - CanonicalizeUserInfo HASH of ARGS
  - CanonicalizeUserInfoFromExternalAuth
  - Password and authentication related functions
    - SetRandomPassword
    - ResetPassword
    - GenerateRandomPassword MIN_LEN and MAX_LEN
    - SetPassword
    - _GeneratePassword PASSWORD [, SALT]
    - HasPassword
    - IsPassword
    - AuthToken
    - GenerateAuthToken
    - GenerateAuthString
    - ValidateAuthString
  - SetDisabled
  - Disabled
  - PrincipalObj
  - PrincipalId
  - HasGroupRight
  - OwnGroups Recursively => 1|0
  - HasRight
  - CurrentUserCanSee [FIELD]
  - CurrentUserCanModify RIGHT
  - CurrentUserHasRight
  - Preferences NAME/OBJ DEFAULT
  - SetPreferences NAME/OBJ VALUE
  - DeletePreferences NAME/OBJ VALUE
  - Stylesheet
  - WatchedQueues ROLE_LIST
  - _Value
  - FriendlyName
  - Format
  - PreferredKey
  - Bookmarks
  - HasBookmark TICKET
  - ToggleBookmark TICKET
  - RecentlyViewedTickets TICKET
  - AddRecentlyViewedTicket TICKET
  - Create PARAMHASH
  - id
  - Name
  - SetName VALUE
  - Password
  - SetPassword VALUE
  - AuthToken
  - SetAuthToken VALUE
  - Comments
  - SetComments VALUE
  - Signature
  - SetSignature VALUE
  - EmailAddress
  - SetEmailAddress VALUE
  - FreeformContactInfo
  - SetFreeformContactInfo VALUE
  - Organization
  - SetOrganization VALUE
  - RealName
  - SetRealName VALUE
  - NickName
  - SetNickName VALUE
  - Lang
  - SetLang VALUE
  - Gecos
  - SetGecos VALUE
  - HomePhone
  - SetHomePhone VALUE
  - WorkPhone
  - SetWorkPhone VALUE
  - MobilePhone
  - SetMobilePhone VALUE
  - PagerPhone
  - SetPagerPhone VALUE
  - Address1
  - SetAddress1 VALUE
  - Address2
  - SetAddress2 VALUE
  - City
  - SetCity VALUE
  - State
  - SetState VALUE
  - Zip
  - SetZip VALUE
  - Country
  - SetCountry VALUE
  - Timezone
  - SetTimezone VALUE
  - SMIMECertificate
  - SetSMIMECertificate VALUE
  - Creator
  - Created
  - LastUpdatedBy
  - LastUpdated

# NAME

RT::User - RT User object

# SYNOPSIS

      use RT::User;

# DESCRIPTION

Object to operate on a single RT user record.

# METHODS

## Create { PARAMHASH }

Create accepts all core RT::User fields (Name, EmailAddress, etc.) and user custom fields in the form UserCF.Foo where Foo is the name of the custom field.

        my ($ret, $msg) = $user->Create( Name => 'mycroft',
                                         EmailAddress => 'mycroft@example.com',
                                         UserCF.Relationship => 'Brother' );

If no Name is passed, it is set to the same value as EmailAddress.

## UpdateObjectCustomFieldValues

Set User CFs from incoming args in the form UserCF.Foo.

## ValidateName STRING

Returns either (0, "failure reason") or 1 depending on whether the given name is valid.

## GenerateAnonymousName

Generate a random username proceeded by 'anon_' and then a random string, Returns the AnonymousName string.

## AnonymizeUser { ClearCustomfields => 1|0 }

Remove all personal identifying information on the user record, but keep the user record alive. Additionally replace the username with an anonymous name. Submit ClearCustomfields in a paramhash, if true all customfield values applied to the user record will be cleared.

## ValidatePassword STRING

Returns either (0, "failure reason") or 1 depending on whether the given password is valid.

## SetPrivileged BOOL

If passed a true value, makes this user a member of the "Privileged" PseudoGroup. Otherwise, makes this user a member of the "Unprivileged" pseudogroup.

Returns a standard RT tuple of (val, msg);

## Privileged

Returns true if this user is privileged. Returns undef otherwise.

## Load

Load a user object from the database. Takes a single argument. If the argument is numerical, load by the column 'id'. If a user object or its subclass passed then loads the same user by id. Otherwise, load by the "Name" column which is the user's textual username.

## LoadByEmail

Tries to load this user object from the database by the user's email address.

## LoadOrCreateByEmail ADDRESS

Attempts to find a user who has the provided email address. If that fails, creates an unprivileged user with the provided email address and loads them. Address can be provided either as Email::Address object or string which is parsed using the module.

Returns a tuple of the user's id and a status message. 0 will be returned in place of the user's id in case of failure.

## ValidateEmailAddress ADDRESS

Returns true if the email address entered is not in use by another user or is undef or ''. Returns false if it's in use.

## SetName

Check to make sure someone else isn't using this name already

## SetEmailAddress

Check to make sure someone else isn't using this email address already so that a better email address can be returned

## EmailFrequency

Takes optional Ticket argument in paramhash. Returns a string, suitable for localization, describing any notable properties about email delivery to the user. This includes lack of email address, ticket-level squelching (if `Ticket` is provided in the paramhash), or user email delivery preferences.

Returns the empty string if there are no notable properties.

## URI

Returns this user's URI

## CanonicalizeEmailAddress ADDRESS

CanonicalizeEmailAddress converts email addresses into canonical form. it takes one email address in and returns the proper canonical form. You can dump whatever your proper local config is in here. Note that it may be called as a static method; in this case the first argument is class name not an object.

## CanonicalizeUserInfo HASH of ARGS

CanonicalizeUserInfo can convert all User->Create options. it takes a hashref of all the params sent to User->Create and returns that same hash, by default nothing is done. If external auth is enabled CanonicalizeUserInfoFromExternalAuth is called.

This function is intended to allow users to have their info looked up via an outside source and modified upon creation.

## CanonicalizeUserInfoFromExternalAuth

Convert an LDAP entry in to fields that can be used by RT as specified by the `attr_map` configuration in the `$ExternalSettings` variable for RT::Authen::ExternalAuth.

## Password and authentication related functions

### SetRandomPassword

Takes no arguments. Returns a status code and a new password or an error message. If the status is 1, the second value returned is the new password. If the status is anything else, the new value returned is the error code.

### ResetPassword

Returns status, [ERROR or new password]. Resets this user's password to a randomly generated pronounceable password and emails them, using a global template called "PasswordChange".

This function is currently unused in the UI, but available for local scripts.

### GenerateRandomPassword MIN_LEN and MAX_LEN

Returns a random password between MIN_LEN and MAX_LEN characters long.

### SetPassword

Takes a string. Checks the string's length and sets this user's password to that string.

### _GeneratePassword PASSWORD [, SALT]

Returns a string to store in the database. This string takes the form:

       !method!salt!hash

By default, the method is currently `bcrypt`.

### HasPassword

Returns true if the user has a valid password, otherwise returns false.

### IsPassword

Returns true if the passed in value is this user's password. Returns undef otherwise.

### AuthToken

Returns an authentication string associated with the user. This string can be used to generate passwordless URLs to integrate RT with services and programs like calendar managers, RSS readers and other.

### GenerateAuthToken

Generate a random authentication string for the user.

### GenerateAuthString

Takes a string and returns back a hex hash string. Later you can use this pair to make sure it's generated by this user using "ValidateAuthString"

### ValidateAuthString

Takes auth string and protected string. Returns true if protected string has been protected by user's "AuthToken". See also "GenerateAuthString".

## SetDisabled

Toggles the user's disabled flag. If this flag is set, all password checks for this user will fail. All ACL checks for this user will fail. The user will appear in no user listings.

## Disabled

Returns true if user is disabled or false otherwise

## PrincipalObj

Returns the principal object for this user. returns an empty RT::Principal if there's no principal object matching this user. The response is cached. PrincipalObj should never ever change.

## PrincipalId

Returns this user's PrincipalId

## HasGroupRight

Takes a paramhash which can contain these items: GroupObj => RT::Group or Group => integer Right => 'Right'

Returns 1 if this user has the right specified in the paramhash for the Group passed in.

Returns undef if they don't.

## OwnGroups Recursively => 1|0

Returns a group collection object containing the groups of which this user is a member, recursively by default.

## HasRight

Shim around PrincipalObj->HasRight. See RT::Principal.

## CurrentUserCanSee [FIELD]

Returns true if the current user can see the user, based on if it is public, ourself, or we have AdminUsers

## CurrentUserCanModify RIGHT

If the user has rights for this object, either because he has 'AdminUsers' or (if he's trying to edit himself and the right isn't an admin right) 'ModifySelf', return 1. otherwise, return undef.

## CurrentUserHasRight

Takes a single argument. returns 1 if $Self->CurrentUser has the requested right. returns undef otherwise

## Preferences NAME/OBJ DEFAULT

Obtain user preferences associated with given object or name. Returns DEFAULT if no preferences found. If DEFAULT is a hashref, override the entries with user preferences.

## SetPreferences NAME/OBJ VALUE

Set user preferences associated with given object or name.

## DeletePreferences NAME/OBJ VALUE

Delete user preferences associated with given object or name.

## Stylesheet

Returns a list of valid stylesheets take from preferences.

## WatchedQueues ROLE_LIST

Returns a RT::Queues object containing every queue watched by the user.

Takes a list of roles which is some subset of ('Cc', 'AdminCc'). Defaults to:

$user->WatchedQueues('Cc', 'AdminCc');

## _Value

Takes the name of a table column. Returns its value as a string, if the user passes an ACL check

## FriendlyName

Return the friendly name

## Format

Class or object method.

Returns a string describing a user in the current user's preferred format.

May be invoked in three ways:

        $UserObj->Format;
        RT::User->Format( User => $UserObj );   # same as above
        RT::User->Format( Address => $AddressObj, CurrentUser => $CurrentUserObj );

Possible arguments are:

User

  An RT::User object representing the user to format. Preferred to Address.

Address

  An Email::Address object representing the user address to format. Address will be used to lookup an RT::User if possible.

CurrentUser

  Required when Format is called as a class method with an Address argument. Otherwise, this argument is ignored in preference to the CurrentUser of the involved RT::User object.

Format

  Specifies the format to use, overriding any set from the config or current user's preferences.

## PreferredKey

Returns the preferred key of the user. If none is set, then this will query GPG and set the preferred key to the maximally trusted key found (and then return it). Returns `undef` if no preferred key can be found.

## Bookmarks

Returns an unordered list of IDs representing the user's bookmarked tickets.

## HasBookmark TICKET

Returns whether the provided ticket is bookmarked by the user.

## ToggleBookmark TICKET

Toggles whether the provided ticket is bookmarked by the user.

## RecentlyViewedTickets TICKET

Returns a list of hashrefs { id => <ticket_id>, subject => <ticket_subject> } ) ordered by recently viewed first.

If a ticket cannot be loaded (e.g. because it has been shredded) or is duplicated (e.g. because 2 tickets on the list have been merged), it is not returned and the user's RecentlyViewedTickets list is updated

## AddRecentlyViewedTicket TICKET

Takes an RT::Ticket object and adds it to the current user's RecentlyViewedTickets

## Create PARAMHASH

Create takes a hash of values and creates a row in the database:

      varchar(200) 'Name'.
      varbinary(256) 'Password'.
      varchar(16) 'AuthToken'.
      text 'Comments'.
      text 'Signature'.
      varchar(120) 'EmailAddress'.
      text 'FreeformContactInfo'.
      varchar(200) 'Organization'.
      varchar(120) 'RealName'.
      varchar(16) 'NickName'.
      varchar(16) 'Lang'.
      varchar(16) 'Gecos'.
      varchar(30) 'HomePhone'.
      varchar(30) 'WorkPhone'.
      varchar(30) 'MobilePhone'.
      varchar(30) 'PagerPhone'.
      varchar(200) 'Address1'.
      varchar(200) 'Address2'.
      varchar(100) 'City'.
      varchar(100) 'State'.
      varchar(16) 'Zip'.
      varchar(50) 'Country'.
      varchar(50) 'Timezone'.

## id

Returns the current value of id. (In the database, id is stored as int(11).)

## Name

Returns the current value of Name. (In the database, Name is stored as varchar(200).)

## SetName VALUE

Set Name to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Name will be stored as a varchar(200).)

## Password

Returns the current value of Password. (In the database, Password is stored as varchar(256).)

## SetPassword VALUE

Set Password to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Password will be stored as a varchar(256).)

## AuthToken

Returns the current value of AuthToken. (In the database, AuthToken is stored as varchar(16).)

## SetAuthToken VALUE

Set AuthToken to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, AuthToken will be stored as a varchar(16).)

## Comments

Returns the current value of Comments. (In the database, Comments is stored as text.)

## SetComments VALUE

Set Comments to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Comments will be stored as a text.)

## Signature

Returns the current value of Signature. (In the database, Signature is stored as text.)

## SetSignature VALUE

Set Signature to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Signature will be stored as a text.)

## EmailAddress

Returns the current value of EmailAddress. (In the database, EmailAddress is stored as varchar(120).)

## SetEmailAddress VALUE

Set EmailAddress to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, EmailAddress will be stored as a varchar(120).)

## FreeformContactInfo

Returns the current value of FreeformContactInfo. (In the database, FreeformContactInfo is stored as text.)

## SetFreeformContactInfo VALUE

Set FreeformContactInfo to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, FreeformContactInfo will be stored as a text.)

## Organization

Returns the current value of Organization. (In the database, Organization is stored as varchar(200).)

## SetOrganization VALUE

Set Organization to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Organization will be stored as a varchar(200).)

## RealName

Returns the current value of RealName. (In the database, RealName is stored as varchar(120).)

## SetRealName VALUE

Set RealName to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, RealName will be stored as a varchar(120).)

## NickName

Returns the current value of NickName. (In the database, NickName is stored as varchar(16).)

## SetNickName VALUE

Set NickName to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, NickName will be stored as a varchar(16).)

## Lang

Returns the current value of Lang. (In the database, Lang is stored as varchar(16).)

## SetLang VALUE

Set Lang to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Lang will be stored as a varchar(16).)

## Gecos

Returns the current value of Gecos. (In the database, Gecos is stored as varchar(16).)

## SetGecos VALUE

Set Gecos to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Gecos will be stored as a varchar(16).)

## HomePhone

Returns the current value of HomePhone. (In the database, HomePhone is stored as varchar(30).)

## SetHomePhone VALUE

Set HomePhone to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, HomePhone will be stored as a varchar(30).)

## WorkPhone

Returns the current value of WorkPhone. (In the database, WorkPhone is stored as varchar(30).)

## SetWorkPhone VALUE

Set WorkPhone to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, WorkPhone will be stored as a varchar(30).)

## MobilePhone

Returns the current value of MobilePhone. (In the database, MobilePhone is stored as varchar(30).)

## SetMobilePhone VALUE

Set MobilePhone to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, MobilePhone will be stored as a varchar(30).)

## PagerPhone

Returns the current value of PagerPhone. (In the database, PagerPhone is stored as varchar(30).)

## SetPagerPhone VALUE

Set PagerPhone to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, PagerPhone will be stored as a varchar(30).)

## Address1

Returns the current value of Address1. (In the database, Address1 is stored as varchar(200).)

## SetAddress1 VALUE

Set Address1 to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Address1 will be stored as a varchar(200).)

## Address2

Returns the current value of Address2. (In the database, Address2 is stored as varchar(200).)

## SetAddress2 VALUE

Set Address2 to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Address2 will be stored as a varchar(200).)

## City

Returns the current value of City. (In the database, City is stored as varchar(100).)

## SetCity VALUE

Set City to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, City will be stored as a varchar(100).)

## State

Returns the current value of State. (In the database, State is stored as varchar(100).)

## SetState VALUE

Set State to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, State will be stored as a varchar(100).)

## Zip

Returns the current value of Zip. (In the database, Zip is stored as varchar(16).)

## SetZip VALUE

Set Zip to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Zip will be stored as a varchar(16).)

## Country

Returns the current value of Country. (In the database, Country is stored as varchar(50).)

## SetCountry VALUE

Set Country to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Country will be stored as a varchar(50).)

## Timezone

Returns the current value of Timezone. (In the database, Timezone is stored as varchar(50).)

## SetTimezone VALUE

Set Timezone to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Timezone will be stored as a varchar(50).)

## SMIMECertificate

Returns the current value of SMIMECertificate. (In the database, SMIMECertificate is stored as text.)

## SetSMIMECertificate VALUE

Set SMIMECertificate to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, SMIMECertificate will be stored as a text.)

## Creator

Returns the current value of Creator. (In the database, Creator is stored as int(11).)

## Created

Returns the current value of Created. (In the database, Created is stored as datetime.)

## LastUpdatedBy

Returns the current value of LastUpdatedBy. (In the database, LastUpdatedBy is stored as int(11).)

## LastUpdated

Returns the current value of LastUpdated. (In the database, LastUpdated is stored as datetime.)

← Back to index