RT 4.4.1 Documentation

RT::Record

NAME
SYNOPSIS
DESCRIPTION
METHODS
LockForUpdate

NAME

  RT::Record - Base class for RT record objects

SYNOPSIS

DESCRIPTION

METHODS

Id

Override "Id" in DBIx::SearchBuilder to avoid a few lookups RT doesn't do on a very common codepath

id is an alias to Id and is the preferred way to call this method.

Delete

Delete this record object from the database.

RecordType

Returns a string which is this record's type. It's not localized and by default last part (everything after last ::) of class name is returned.

Attributes

Return this object's attributes as an RT::Attributes object

AddAttribute { Name, Description, Content }

Adds a new attribute for this object.

SetAttribute { Name, Description, Content }

Like AddAttribute, but replaces all existing attributes with the same Name.

DeleteAttribute NAME

Deletes all attributes with the matching name for this object.

Returns the first attribute with the matching name for this object (as an RT::Attribute object), or undef if no such attributes exist. If there is more than one attribute with the matching name on the object, the first value that was set is returned.

Create PARAMHASH

Takes a PARAMHASH of Column -> Value pairs. If any Column has a Validate$PARAMNAME subroutine defined and the value provided doesn't pass validation, this routine returns an error.

If this object's table has any of the following atetributes defined as 'Auto', this routine will automatically fill in their values.

Created
Creator
LastUpdated
LastUpdatedBy

LoadByCols

Override DBIx::SearchBuilder::LoadByCols to do case-insensitive loads if the DB is case sensitive

_SetLastUpdated

This routine updates the LastUpdated and LastUpdatedBy columns of the row in question It takes no options. Arguably, this is a bug

CreatorObj

Returns an RT::User object with the RT account of the creator of this row

LastUpdatedByObj

  Returns an RT::User object of the last user to touch this object

URI

Returns this record's URI

ValidateName NAME

Validate the name of the record we're creating. Mostly, just make sure it's not a numeric ID, which is invalid for Name

SQLType attribute

return the SQL type for the attribute 'attribute' as stored in _ClassAccessible

_ClassAccessible

Overrides the "core" _ClassAccessible using $_TABLE_ATTR. Behaves identical to the version in DBIx::SearchBuilder::Record

_Accessible COLUMN ATTRIBUTE

returns the value of ATTRIBUTE for COLUMN

_EncodeLOB BODY MIME_TYPE FILENAME

Takes a potentially large attachment. Returns (ContentEncoding, EncodedBody, MimeType, Filename, NoteArgs) based on system configuration and selected database. Returns a custom (short) text/plain message if DropLongAttachments causes an attachment to not be stored.

Encodes your data as base64 or Quoted-Printable as needed based on your Databases's restrictions and the UTF-8ness of the data being passed in. Since we are storing in columns marked UTF8, we must ensure that binary data is encoded on databases which are strict.

This function expects to receive an octet string in order to properly evaluate and encode it. It will return an octet string.

NoteArgs is currently used to indicate caller that the message is too long and is truncated or dropped. It's a hashref which is expected to be passed to "_NewTransaction" in RT::Record.

_DecodeLOB `ContentType`, `ContentEncoding`, `Content`

Unpacks data stored in the database, which may be base64 or QP encoded because of our need to store binary and badly encoded data in columns marked as UTF-8. Databases such as PostgreSQL and Oracle care that you are feeding them invalid UTF-8 and will refuse the content. This function handles unpacking the encoded data.

Alternatively, if the data lives in external storage, it will be read (or downloaded) and returned.

_DecodeLOB returns textual data as a UTF-8 string which has been processed by Encode's PERLQQ filter which will replace the invalid bytes with \x{HH} so you can see the invalid byte but won't run into problems treating the data as UTF-8 later.

This is similar to how we filter all data coming in via the web UI in "DecodeARGS" in RT::Interface::Web. This filter should only end up being applied to old data from less UTF-8-safe versions of RT.

If the passed ContentType includes a character set, that will be used to decode textual data; the default character set is UTF-8. This is necessary because while we attempt to store textual data as UTF-8, the definition of "textual" has migrated over time, and thus we may now need to attempt to decode data that was previously not transcoded on insertion.

Important note: This function expects an octet string and returns a character string for non-binary data.

Update ARGSHASH

Updates fields on an object for you using the proper Set methods, skipping unchanged values.

 ARGSRef => a hashref of attributes => value for the update
 AttributesRef => an arrayref of keys in ARGSRef that should be updated
 AttributePrefix => a prefix that should be added to the attributes in AttributesRef
                    when looking up values in ARGSRef
                    Bare attributes are tried before prefixed attributes

Returns a list of localized results of the update

    "Ticket" # loc
    "User" # loc
    "Group" # loc
    "Queue" # loc

                                   "[_1] could not be set to [_2].",       # loc
                                   "That is already the current value",    # loc
                                   "No value sent to _Set!",               # loc
                                   "Illegal value for [_1]",               # loc
                                   "The new value has been set.",          # loc
                                   "No column specified",                  # loc
                                   "Immutable field",                      # loc
                                   "Nonexistant field?",                   # loc
                                   "Invalid data",                         # loc
                                   "Couldn't find row",                    # loc
                                   "Missing a primary key?: [_1]",         # loc
                                   "Found Object",                         # loc

Members

  This returns an RT::Links object which references all the tickets 
which are 'MembersOf' this ticket

MemberOf

  This returns an RT::Links object which references all the tickets that this
ticket is a 'MemberOf'

RefersTo

  This returns an RT::Links object which shows all references for which this ticket is a base

ReferredToBy

This returns an RT::Links object which shows all references for which this ticket is a target

DependedOnBy

  This returns an RT::Links object which references all the tickets that depend on this one

HasUnresolvedDependencies

Takes a paramhash of Type (default to '__any'). Returns the number of unresolved dependencies, if $self->UnresolvedDependencies returns an object with one or more members of that type. Returns false otherwise.

UnresolvedDependencies

Returns an RT::Tickets object of tickets which this ticket depends on and which have a status of new, open or stalled. (That list comes from RT::Queue->ActiveStatusArray

AllDependedOnBy

Returns an array of RT::Ticket objects which (directly or indirectly) depends on this ticket; takes an optional 'Type' argument in the param hash, which will limit returned tickets to that type, as well as cause tickets with that type to serve as 'leaf' nodes that stops the recursive dependency search.

AllDependsOn

Returns an array of RT::Ticket objects which this ticket (directly or indirectly) depends on; takes an optional 'Type' argument in the param hash, which will limit returned tickets to that type, as well as cause tickets with that type to serve as 'leaf' nodes that stops the recursive dependency search.

DependsOn

  This returns an RT::Links object which references all the tickets that this ticket depends on

Links DIRECTION [TYPE]

Return links (RT::Links) to/from this object.

DIRECTION is either 'Base' or 'Target'.

TYPE is a type of links to return, it can be omitted to get links of any type.

FormatType

Takes a Type and returns a string that is more human readable.

FormatLink

Takes either a Target or a Base and returns a string of human friendly text.

_AddLink

Takes a paramhash of Type and one of Base or Target. Adds that link to this object.

If Silent is true then no transactions will be recorded. You can individually control transactions on both base and target and with SilentBase and SilentTarget respectively. By default both transactions are created.

If the link destination is a local object and does the RT::Record::Role::Status role, this method ensures object Status is not "deleted". Linking to deleted objects is forbidden.

If the link destination (i.e. not $self) is a local object and the $StrictLinkACL option is enabled, this method checks the appropriate right on the destination object (if any, as returned by the "ModifyLinkRight" method). The subclass is expected to check the appropriate right on the source object (i.e. $self) before calling this method. This allows a different right to be used on the source object during creation, for example.

Returns a tuple of (link ID, message, flag if link already existed).

_DeleteLink

Takes a paramhash of Type and one of Base or Target. Removes that link from this object.

Returns a tuple of (status flag, message).

LockForUpdate

In a database transaction, gains an exclusive lock on the row, to prevent race conditions. On SQLite, this is a "RESERVED" lock on the entire database.

_NewTransaction PARAMHASH

Private function to create a new RT::Transaction object for this ticket update

Transactions

Returns an RT::Transactions object of all transactions on this record object

SortedTransactions

Returns the result of "Transactions" ordered per the OldestTransactionsFirst preference/option.

Attachments

Returns an RT::Attachments object of all attachments on this record object (for all its "Transactions").

By default Content and Headers of attachments are not fetched right away from database. Use WithContent and WithHeaders options to override this.

TextAttachments

Returns an RT::Attachments object of all attachments, like Attachments, but only those that are text.

By default Content and Headers are fetched. Use WithContent and WithHeaders options to override this.

CustomFieldLookupType

Returns the path RT uses to figure out which custom fields apply to this object.

AddCustomFieldValue { Field => FIELD, Value => VALUE }

VALUE should be a string. FIELD can be any identifier of a CustomField supported by "LoadCustomFieldByIdentifier" method.

Adds VALUE as a value of CustomField FIELD. If this is a single-value custom field, deletes the old value. If VALUE is not a valid value for the custom field, returns (0, 'Error message' ) otherwise, returns ($id, 'Success Message') where $id is ID of created ObjectCustomFieldValue object.

AddCustomFieldDefaultValues

Add default values to object's empty custom fields.

CustomFieldValueIsEmpty { Field => FIELD, Value => VALUE }

Check if the custom field value is empty.

Some custom fields could have other special empty values, e.g. "1970-01-01" is empty for Date cf

Return 1 if it is empty, 0 otherwise.

DeleteCustomFieldValue { Field => FIELD, Value => VALUE }

Deletes VALUE as a value of CustomField FIELD.

VALUE can be a string, a CustomFieldValue or a ObjectCustomFieldValue.

If VALUE is not a valid value for the custom field, returns (0, 'Error message' ) otherwise, returns (1, 'Success Message')

FirstCustomFieldValue FIELD

Return the content of the first value of CustomField FIELD for this ticket Takes a field id or name

CustomFieldValuesAsString FIELD

Return the content of the CustomField FIELD for this ticket. If this is a multi-value custom field, values will be joined with newlines.

Takes a field id or name as the first argument

Takes an optional Separator => "," second and third argument if you want to join the values using something other than a newline

 Takes a paramhash with the attributes 'Right' and 'Principal'
  'Right' is a ticket-scoped textual right from RT::ACE 
  'Principal' is an RT::User object

  Returns 1 if the principal has the right. Returns undef if not.