- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
  - SortFields
- Limit Helper Routines
  - _IdLimit
  - _EnumLimit
  - _IntLimit
  - _LinkLimit
  - _DateLimit
  - _StringLimit
  - _QueueLimit
  - _TransDateLimit
  - _TransLimit
  - _TransContentLimit
  - _CustomRoleDecipher
  - _WatcherLimit
  - _WatcherMembershipLimit
  - _CustomFieldDecipher
  - _CustomFieldLimit
  - OrderByCols ARRAY
  - LimitField
  - LimitQueue
  - LimitStatus
  - LimitToActiveStatus
  - LimitToInactiveStatus
  - IgnoreType
  - LimitType
  - LimitSubject
  - LimitId
  - LimitPriority
  - LimitInitialPriority
  - LimitFinalPriority
  - LimitTimeWorked
  - LimitTimeLeft
  - LimitContent
  - LimitFilename
  - LimitContentType
  - LimitOwner
  - LimitWatcher
  - LimitLinkedTo
  - LimitLinkedFrom
  - LimitDate (FIELD => 'DateField', OPERATOR => $oper, VALUE => $ISODate)
  - LimitTransactionDate (OPERATOR => $oper, VALUE => $ISODate)
  - LimitCustomField
  - _NextIndex
  - ItemsArrayRef
  - ClearRestrictions
  - ClausesToSQL
  - _BuildItemMap
  - ItemMap
  - PrepForSerialization
- FLAGS
  - FromSQL
  - Query

# NAME

      RT::Tickets - A collection of Ticket objects

# SYNOPSIS

      use RT::Tickets;
      my $tickets = RT::Tickets->new($CurrentUser);

# DESCRIPTION

       A collection of RT::Tickets.

# METHODS

## SortFields

Returns the list of fields that lists of tickets can easily be sorted by

# Limit Helper Routines

These routines are the targets of a dispatch table depending on the type of field. They all share the same signature:

      my ($self,$field,$op,$value,@rest) = @_;

The values in @rest should be suitable for passing directly to DBIx::SearchBuilder::Limit.

Essentially they are an expanded/broken out (and much simplified) version of what ProcessRestrictions used to do. They're also much more clearly delineated by the TYPE of field being processed.

## _IdLimit

Handle ID field.

## _EnumLimit

Handle Fields which are limited to certain values, and potentially need to be looked up from another class.

This subroutine actually handles two different kinds of fields. For some the user is responsible for limiting the values. (i.e. Status, Type).

For others, the value specified by the user will be looked by via specified class.

Meta Data: name of class to lookup in (Optional)

## _IntLimit

Handle fields where the values are limited to integers. (For example, Priority, TimeWorked.)

Meta Data: None

## _LinkLimit

Handle fields which deal with links between tickets. (MemberOf, DependsOn)

Meta Data: 1: Direction (From, To) 2: Link Type (MemberOf, DependsOn, RefersTo)

## _DateLimit

Handle date fields. (Created, LastTold..)

Meta Data: 1: type of link. (Probably not necessary.)

## _StringLimit

Handle simple fields which are just strings. (Subject,Type)

Meta Data: None

## _QueueLimit

Handle Queue field supporting both "is" and "match".

Input should be a queue name or a partial string.

## _TransDateLimit

Handle fields limiting based on Transaction Date.

The inpupt value must be in a format parseable by Time::ParseDate

Meta Data: None

## _TransLimit

Limit based on the ContentType or the Filename of a transaction.

## _TransContentLimit

Limit based on the Content of a transaction.

## _CustomRoleDecipher

Try and turn a custom role descriptor (e.g. `CustomRole.{Engineer}`) into (role, column, original name).

## _WatcherLimit

Handle watcher limits. (Requestor, CC, etc..)

Meta Data: 1: Field to query on

## _WatcherMembershipLimit

Handle watcher membership limits, i.e. whether the watcher belongs to a specific group or not.

Meta Data: 1: Role to query on

## _CustomFieldDecipher

Try and turn a CF descriptor into (cfid, cfname) object pair.

Takes an optional second parameter of the CF LookupType, defaults to Ticket CFs.

## _CustomFieldLimit

Limit based on CustomFields

Meta Data: none

## OrderByCols ARRAY

A modified version of the OrderBy method which automatically joins where `ALIAS` is set to the name of a watcher type.

## LimitField

Takes a paramhash with the fields FIELD, OPERATOR, VALUE and DESCRIPTION Generally best called from LimitFoo methods

## LimitQueue

LimitQueue takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. (It defaults to =). VALUE is a queue id or Name.

## LimitStatus

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a status.

RT adds Status != 'deleted' until object has allow_deleted_search internal property set. $tickets->{'allow_deleted_search'} = 1; $tickets->LimitStatus( VALUE => 'deleted' );

## LimitToActiveStatus

Limits the status to "ActiveStatusArray" in RT::Queue

TODO: make this respect lifecycles for the queues associated with the search

## LimitToInactiveStatus

Limits the status to "InactiveStatusArray" in RT::Queue

TODO: make this respect lifecycles for the queues associated with the search

## IgnoreType

If called, this search will not automatically limit the set of results found to tickets of type "Ticket". Tickets of other types, such as "project" and "approval" will be found.

## LimitType

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=, it defaults to "=". VALUE is a string to search for in the type of the ticket.

## LimitSubject

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a string to search for in the subject of the ticket.

## LimitId

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a ticket Id to search for

## LimitPriority

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a value to match the ticket's priority against

## LimitInitialPriority

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a value to match the ticket's initial priority against

## LimitFinalPriority

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a value to match the ticket's final priority against

## LimitTimeWorked

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a value to match the ticket's TimeWorked attribute

## LimitTimeLeft

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, >, < or !=. VALUE is a value to match the ticket's TimeLeft attribute

## LimitContent

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a string to search for in the body of the ticket

## LimitFilename

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a string to search for in the body of the ticket

## LimitContentType

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a content type to search ticket attachments for

## LimitOwner

Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a user id.

## LimitWatcher

      Takes a paramhash with the fields OPERATOR, TYPE and VALUE.
      OPERATOR is one of =, LIKE, NOT LIKE or !=.
      VALUE is a value to match the ticket's watcher email addresses against
      TYPE is the sort of watchers you want to match against. Leave it undef if you want to search all of them

## LimitLinkedTo

LimitLinkedTo takes a paramhash with two fields: TYPE and TARGET TYPE limits the sort of link we want to search on

TYPE = { RefersTo, MemberOf, DependsOn }

TARGET is the id or URI of the TARGET of the link

## LimitLinkedFrom

LimitLinkedFrom takes a paramhash with two fields: TYPE and BASE TYPE limits the sort of link we want to search on

BASE is the id or URI of the BASE of the link

## LimitDate (FIELD => 'DateField', OPERATOR => $oper, VALUE => $ISODate)

Takes a paramhash with the fields FIELD OPERATOR and VALUE.

OPERATOR is one of > or < VALUE is a date and time in ISO format in GMT FIELD is one of Starts, Started, Told, Created, Resolved, LastUpdated

There are also helper functions of the form LimitFIELD that eliminate the need to pass in a FIELD argument.

## LimitTransactionDate (OPERATOR => $oper, VALUE => $ISODate)

Takes a paramhash with the fields FIELD OPERATOR and VALUE.

OPERATOR is one of > or < VALUE is a date and time in ISO format in GMT

## LimitCustomField

Takes a paramhash of key/value pairs with the following keys:

CUSTOMFIELD - CustomField name or id. If a name is passed, an additional parameter QUEUE may also be passed to distinguish the custom field.
OPERATOR - The usual Limit operators
VALUE - The value to compare against

## _NextIndex

Keep track of the counter for the array of restrictions

## ItemsArrayRef

Returns a reference to the set of all items found in this search

## ClearRestrictions

Removes all restrictions irretrievably

## ClausesToSQL

## _BuildItemMap

Build up a "ItemMap" of first/last/next/prev items, so that we can display search nav quickly.

## ItemMap

Returns an a map of all items found by this search. The map is a hash of the form:

        {
            first => <first ticket id found>,
            last => <last ticket id found or undef>,

            <ticket id> => {
                prev => <the ticket id found before>,
                next => <the ticket id found after>,
            },
            <ticket id> => {
                prev => ...,
                next => ...,
            },
        }

## PrepForSerialization

You don't want to serialize a big tickets object, as the {items} hash will be instantly invalid _and_ eat lots of space

# FLAGS

RT::Tickets supports several flags which alter search behavior:

allow_deleted_search (Otherwise never show deleted tickets in search results)

These flags are set by calling

$tickets->{'flagname'} = 1;

BUG: There should be an API for this

## FromSQL

Convert a RT-SQL string into a set of SearchBuilder restrictions.

Returns (1, 'Status message') on success and (0, 'Error Message') on failure.

## Query

Returns the last string passed to "FromSQL".

← Back to index