RT::Ticket(3)

NAME
  RT::Ticket - RT ticket object

SYNOPSIS
  use RT::Ticket;
  my $ticket = new RT::Ticket($CurrentUser);
  $ticket->Load($ticket_id);

DESCRIPTION
This module lets you manipulate RT\'s ticket object.

METHODS

  Load
Takes a single argument. This can be a ticket id, ticket alias or local ticket uri. If the ticket can't be loaded, returns undef. Otherwise, returns the ticket id.

  LoadByURI
Given a local ticket URI, loads the specified ticket.

  Create (ARGS)
Arguments: ARGS is a hash of named parameters. Valid parameters are:

  Queue  - Either a Queue object or a Queue Name
  Requestor -  A reference to a list of RT::User objects, email addresses or RT user Names
  Cc  - A reference to a list of RT::User objects, email addresses or Names
  AdminCc  - A reference to a  list of RT::User objects, email addresses or Names
  Type -- The ticket\'s type. ignore this for now
  Owner -- This ticket\'s owner. either an RT::User object or this user\'s id
  Subject -- A string describing the subject of the ticket
  InitialPriority -- an integer from 0 to 99
  FinalPriority -- an integer from 0 to 99
  Status -- any valid status (Defined in RT::Queue)
  TimeWorked -- an integer
  TimeLeft -- an integer
  Starts -- an ISO date describing the ticket\'s start date and time in GMT
  Due -- an ISO date describing the ticket\'s due date and time in GMT
  MIMEObj -- a MIME::Entity object with the content of the initial ticket request.

  KeywordSelect-<id> -- an array of keyword ids for that keyword select

Returns: TICKETID, Transaction Object, Error Message

  Import PARAMHASH
Import a ticket. Doesn\'t create a transaction. Doesn\'t supply queue defaults, etc.

Arguments are identical to Create(), with the addition of
    Id - Ticket Id

Returns: TICKETID

  AddWatcher
AddWatcher takes a parameter hash. The keys are as follows:

Email Type Owner

If the watcher you\'re trying to set has an RT account, set the Owner paremeter to their User Id. Otherwise, set the Email parameter to their Email address.

  AddRequestor
AddRequestor takes what AddWatcher does, except it presets the "Type" parameter to \'Requestor\'

  AddCc
AddCc takes what AddWatcher does, except it presets the "Type" parameter to \'Cc\'

  AddAdminCc
AddAdminCc takes what AddWatcher does, except it presets the "Type" parameter to \'AdminCc\'

  DeleteWatcher id [type]
DeleteWatcher takes a single argument which is either an email address or a watcher id. If the first argument is an email address, you need to specify the watcher type you're talking about as the second argument. Valid values are 'Requestor', 'Cc' or 'AdminCc'. It removes that watcher from this Ticket\'s list of watchers.

  DeleteRequestor EMAIL
Takes an email address. It calls DeleteWatcher with a preset type of 'Requestor'

  DeleteCc EMAIL
Takes an email address. It calls DeleteWatcher with a preset type of 'Cc'

  DeleteAdminCc EMAIL
Takes an email address. It calls DeleteWatcher with a preset type of 'AdminCc'

  Watchers
Watchers returns a Watchers object preloaded with this ticket\'s watchers.

# It should return only the ticket watchers. the actual FooAsString # methods capture the queue watchers too. I don't feel thrilled about this, # but we don't want the Cc Requestors and AdminCc objects to get filled up # with all the queue watchers too. we've got seperate objects for that.
  # should we rename these as s/(.*)AsString/$1Addresses/ or somesuch?

  RequestorsAsString
 B<Returns> String: All Ticket Requestor email addresses as a string.

  WatchersAsString
Returns String: All Ticket Watchers email addresses as a string

  AdminCcAsString
returns String: All Ticket AdminCc email addresses as a string

  CcAsString
returns String: All Ticket Ccs as a string of email addresses

  Requestors
Takes nothing. Returns this ticket's Requestors as an RT::Watchers object

  Cc
Takes nothing. Returns a watchers object which contains this ticket's Cc watchers

  AdminCc
Takes nothing. Returns this ticket\'s administrative Ccs as an RT::Watchers object

  IsWatcher
Takes a param hash with the attributes Type and User. User is either a user object or string containing an email address. Returns true if that user or string is a ticket watcher. Returns undef otherwise

  IsRequestor
  Takes an email address, RT::User object or integer (RT user id)
  Returns true if the string is a requestor of the current ticket.

  IsCc
Takes a string. Returns true if the string is a Cc watcher of the current ticket.

  IsAdminCc
Takes a string. Returns true if the string is an AdminCc watcher of the current ticket.

  IsOwner
  Takes an RT::User object. Returns true if that user is this ticket's owner.
returns undef otherwise

  QueueObj
Takes nothing. returns this ticket's queue object

  DueObj
  Returns an RT::Date object containing this ticket's due date

  DueAsString
Returns this ticket's due date as a human readable string

  GraceTimeAsString
Return the time until this ticket is due as a string

  ResolvedObj
  Returns an RT::Date object of this ticket's 'resolved' time.

  SetStarted
Takes a date in ISO format or undef Returns a transaction id and a message The client calls "Start" to note that the project was started on the date in $date. A null date means "now"

  StartedObj
  Returns an RT::Date object which contains this ticket's
'Started' time.

  StartsObj
  Returns an RT::Date object which contains this ticket's
'Starts' time.

  ToldObj
  Returns an RT::Date object which contains this ticket's
'Told' time.

  ToldAsString
A convenience method that returns ToldObj->AsString

TODO: This should be deprecated

  TimeWorkedAsString
Returns the amount of time worked on this ticket as a Text String

  Comment
Comment on this ticket. Takes a hashref with the follwoing attributes:

MIMEObj, TimeTaken, CcMessageTo, BccMessageTo

  Correspond
Correspond on this ticket. Takes a hashref with the following attributes:

MIMEObj, TimeTaken, CcMessageTo, BccMessageTo

  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

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

  DeleteLink
Delete a link. takes a paramhash of Base, Target and Type. Either Base or Target must be null. The null value will be replaced with this ticket\'s id

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

  URI
Returns this ticket's URI

  MergeInto MergeInto take the id of the ticket to merge this ticket into.

  KeywordsObj [KEYWORD_SELECT_ID]
  Returns an B<RT::ObjectKeywords> object preloaded with this ticket's ObjectKeywords.
If the optional KEYWORD_SELECT_ID parameter is set, limit the keywords object to that keyword
select.

  AddKeyword
Takes a paramhash of Keyword and KeywordSelect. If Keyword is a valid choice for KeywordSelect, creates a KeywordObject. If the KeywordSelect says this should be a single KeywordObject, automatically removes the old value.

 Issues: probably doesn't enforce the depth restrictions or make sure that keywords
are coming from the right part of the tree. really should.

  DeleteKeyword
  Takes a paramhash. Deletes the Keyword denoted by the I<Keyword> parameter from this
  ticket's object keywords.

  OwnerObj
Takes nothing and returns an RT::User object of this ticket's owner

  OwnerAsString
Returns the owner's email address

  SetOwner
Takes two arguments:
     the Id or Name of the owner and (optionally) the type of the SetOwner Transaction. It defaults to 'Give'. 'Steal' is also a valid option.

  Take
A convenince method to set the ticket's owner to the current user

  Untake
Convenience method to set the owner to 'nobody' if the current user is the owner.

  Steal
A convenience method to change the owner of the current ticket to the current user. Even if it's owned by another user.

  ValidateStatus STATUS
Takes a string. Returns true if that status is a valid status for this ticket. Returns false otherwise.

  SetStatus STATUS
Set this ticket\'s status. STATUS can be one of: new, open, stalled, resolved or dead.

  Kill
Takes no arguments. Marks this ticket for garbage collection

  Stall
Sets this ticket's status to stalled

  Open
Sets this ticket\'s status to Open

  Resolve
Sets this ticket\'s status to Resolved

  SetTold ISO [TIMETAKEN]
Updates the told and records a transaction

  _SetTold
Updates the told without a transaction or acl check. Useful when we're sending replies.

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

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

  _UpdateTimeTaken
This routine will increment the timeworked counter. it should only be called from _NewTransaction

  CurrentUserHasRight
  Takes the textual name of a Ticket scoped right (from RT::ACE) and returns
1 if the user has that right. It returns 0 if the user doesn't have that right.

  HasRight
 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.

AUTHOR
Jesse Vincent, jesse@fsck.com

SEE ALSO
RT