RT 4.2.12 Documentation

RT::Ticket

SYNOPSIS
DESCRIPTION
METHODS
AUTHOR
SEE ALSO

SYNOPSIS

  use RT::Ticket;
  my $ticket = RT::Ticket->new($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.

Create (ARGS)

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

  id 
  Queue  - Either a Queue object or a Queue Name
  Requestor -  A reference to a list of  email addresses or RT user Names
  Cc  - A reference to a list of  email addresses or Names
  AdminCc  - A reference to a  list of  email addresses or Names
  SquelchMailTo - A reference to a list of email addresses - 
                  who should this ticket not mail
  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
  Priority -- an integer from 0 to 99
  InitialPriority -- an integer from 0 to 99
  FinalPriority -- an integer from 0 to 99
  Status -- any valid status for Queue's Lifecycle, otherwises uses on_create from Lifecycle default
  TimeEstimated -- an integer. estimated time for this task in minutes
  TimeWorked -- an integer. time worked so far in minutes
  TimeLeft -- an integer. time remaining in minutes
  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.
  CustomField-<n> -- a scalar or array of values for the customfield with the id <n>

Ticket links can be set up during create by passing the link type as a hask key and the ticket id to be linked to as a value (or a URI when linking to other objects). Multiple links of the same type can be created by passing an array ref. For example:

  Parents => 45,
  DependsOn => [ 15, 22 ],
  RefersTo => 'http://www.bestpractical.com',

Supported link types are MemberOf, HasMember, RefersTo, ReferredToBy, DependsOn and DependedOnBy. Also, Parents is alias for MemberOf and Members and Children are aliases for HasMember.

Returns: TICKETID, Transaction Object, Error Message

OwnerGroup

A constructor which returns an RT::Group object containing the owner of this ticket.

AddWatcher

Applies access control checking, then calls "AddRoleMember" in RT::Record::Role::Roles. Additionally, Email is accepted as an alternative argument name for User.

Returns a tuple of (status, message).

DeleteWatcher

Applies access control checking, then calls "DeleteRoleMember" in RT::Record::Role::Roles. Additionally, Email is accepted as an alternative argument name for User.

Returns a tuple of (status, message).

SquelchMailTo [EMAIL]

Takes an optional email address to never email about updates to this ticket.

Returns an array of the RT::Attribute objects for this ticket's 'SquelchMailTo' attributes.

UnsquelchMailTo ADDRESS

Takes an address and removes it from this ticket's "SquelchMailTo" list. If an address appears multiple times, each instance is removed.

Returns a tuple of (status, message)

RequestorAddresses

Returns String: All Ticket Requestor email addresses as a string.

AdminCcAddresses

returns String: All Ticket AdminCc email addresses as a string

CcAddresses

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

Requestor

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

Cc

Takes nothing. Returns an RT::Group object which contains this ticket's Ccs. If the user doesn't have "ShowTicket" permission, returns an empty group

AdminCc

Takes nothing. Returns an RT::Group object which contains this ticket's AdminCcs. If the user doesn't have "ShowTicket" permission, returns an empty group

IsWatcher { Type => TYPE, PrincipalId => PRINCIPAL_ID, Email => EMAIL }

Takes a param hash with the attributes Type and either PrincipalId or Email

Type is one of Requestor, Cc, AdminCc and Owner

PrincipalId is an RT::Principal id, and Email is an email address.

Returns true if the specified principal (or the one corresponding to the specified address) is a member of the group Type for this ticket.

XX TODO: This should be Memoized.

IsRequestor PRINCIPAL_ID

Takes an RT::Principal id.

Returns true if the principal is a requestor of the current ticket.

IsCc PRINCIPAL_ID

  Takes an RT::Principal id.
  Returns true if the principal is a Cc of the current ticket.

IsAdminCc PRINCIPAL_ID

  Takes an RT::Principal id.
  Returns true if the principal is an AdminCc of the current ticket.

IsOwner

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

TransactionAddresses

Returns a composite hashref of the results of "Addresses" in RT::Transaction for all this ticket's Create, Comment or Correspond transactions. The keys are stringified email addresses. Each value is an Email::Address object.

NOTE: For performance reasons, this method might want to skip transactions and go straight for attachments. But to make that work right, we're going to need to go and walk around the access control in Attachment.pm's sub _Value.

QueueObj

Takes nothing. returns this ticket's queue object

SubjectTag

Takes nothing. Returns SubjectTag for this ticket. Includes queue's subject tag or rtname if that is not set, ticket id and brackets, for example:

    [support.example.com #123456]

DueObj

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

DueAsString

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

DEPRECATED and will be removed in 4.4; use $ticket->DueObj->AsString instead.

ResolvedObj

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

FirstActiveStatus

Returns the first active status that the ticket could transition to, according to its current Queue's lifecycle. May return undef if there is no such possible status to transition to, or we are already in it. This is used in RT::Action::AutoOpen, for instance.

FirstInactiveStatus

Returns the first inactive status that the ticket could transition to, according to its current Queue's lifecycle. May return undef if there is no such possible status to transition to, or we are already in it. This is used in resolve action in UnsafeEmailCommands, for instance.

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

DEPRECATED and will be removed in 4.4; use $ticket->ToldObj->AsString instead.

TimeWorkedAsString

Returns the amount of time worked on this ticket as a text string.

TimeLeftAsString

Returns the amount of time left on this ticket as a text string.

TimeEstimatedAsString

Returns the amount of time estimated on this ticket as a text string.

Comment

Comment on this ticket. Takes a hash with the following attributes: If MIMEObj is undefined, Content will be used to build a MIME::Entity for this comment.

MIMEObj, TimeTaken, CcMessageTo, BccMessageTo, Content, DryRun

If DryRun is defined, this update WILL NOT BE RECORDED. Scrips will not be committed. They will, however, be prepared and you'll be able to access them through the TransactionObj

Returns: Transaction id, Error Message, Transaction Object (note the different order from Create()!)

Correspond

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

MIMEObj, TimeTaken, CcMessageTo, BccMessageTo, Content, DryRun

if there's no MIMEObj, Content is used to build a MIME::Entity object

If DryRun is defined, this update WILL NOT BE RECORDED. Scrips will not be committed. They will, however, be prepared and you'll be able to access them through the TransactionObj

Returns: Transaction id, Error Message, Transaction Object (note the different order from Create()!)

_RecordNote

the meat of both comment and correspond.

Performs no access control checks. hence, dangerous.

DryRun

Builds a MIME object from the given UpdateSubject and UpdateContent, then calls "Comment" or "Correspond" with DryRun => 1, and returns the transaction so produced.

DryRunCreate

Prepares a MIME mesage with the given Subject, Cc, and Content, then calls "Create" with DryRun => 1 and returns the resulting RT::Transaction.

MergeInto

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

Merged

Returns list of tickets' ids that's been merged into this ticket.

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 'Set'. 'Steal' is also a valid option.

CurrentUserCanSetOwner

Confirm the current user can set the owner of the current ticket.

There are several different rights to manage owner changes and this method evaluates these rights, guided by parameters provided.

This method evaluates these rights in the context of the state of the current ticket. For example, it evaluates Take for tickets that are owned by Nobody because that is the context appropriate for the TakeTicket right. If you need to strictly test a user for a right, use HasRight to check for the right directly.

For some custom types of owner changes (Take and Steal), it also verifies that those actions are possible given the current ticket owner.

Rights to Set Owner

The current user can set or change the Owner field in the following cases:

ReassignTicket unconditionally grants the right to set the owner to any user who has OwnTicket. This can be used to break an Owner lock held by another user (see below) and can be a convenient right for managers or administrators who need to assign tickets without necessarily owning them.
ModifyTicket grants the right to set the owner to any user who has OwnTicket, provided the ticket is currently owned by the current user or is not owned (owned by Nobody). (See the details on the Force parameter below for exceptions to this.)
If the ticket is currently not owned (owned by Nobody), TakeTicket is sufficient to set the owner to yourself (but not an arbitrary person), but only if you have OwnTicket. It is thus a subset of the possible changes provided by ModifyTicket. This exists to allow granting TakeTicket freely, and the broader ModifyTicket only to Owners.
If the ticket is currently owned by someone who is not you or Nobody, StealTicket is sufficient to set the owner to yourself, but only if you have OwnTicket. This is hence non-overlapping with the changes provided by ModifyTicket, and is used to break a lock held by another user.

Parameters

This method returns ($result, $message) with $result containing true or false indicating if the current user can set owner and $message containing a message, typically in the case of a false response.

If called with no parameters, this method determines if the current user could set the owner of the current ticket given any permutation of the rights described above. This can be useful when determining whether to make owner-setting options available in the GUI.

This method accepts the following parameters as a paramshash:

NewOwnerObj: Optional; an RT::User object representing the proposed new owner of the ticket.
Type: Optional; the type of set owner operation. Valid values are Take, Steal, or Force. Note that if the type is Take, this method will return false if the current user is already the owner; similarly, it will return false for Steal if the ticket has no owner or the owner is the current user.

As noted above, there are exceptions to the standard ticket-based rights described here. The Force option allows for these and is used when moving tickets between queues, for reminders (because the full owner rights system is too complex for them), and optionally during bulk update.

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.

SetStatus STATUS

Set this ticket's status.

Alternatively, you can pass in a list of named parameters (Status => STATUS, Force => FORCE, SetStarted => SETSTARTED ). If FORCE is true, ignore unresolved dependencies and force a status change. if SETSTARTED is true (it's the default value), set Started to current datetime if Started is not set and the status is changed from initial to not initial.

Delete

Takes no arguments. Marks this ticket for garbage collection

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.

SeenUpTo

RanTransactionBatch

Acts as a guard around running TransactionBatch scrips.

Should be false until you enter the code that runs TransactionBatch scrips

Accepts an optional argument to indicate that TransactionBatch Scrips should no longer be run on this object.

TransactionBatch

Returns an array reference of all transactions created on this ticket during this ticket object's lifetime or since last application of a batch, or undef if there were none.

Only works when the UseTransactionBatch config option is set to true.

ApplyTransactionBatch

Applies scrips on the current batch of transactions and shinks it. Usually batch is applied when object is destroyed, but in some cases it's too late.

_Value

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

Attachments

Customization of "Attachments" in RT::Record for tickets.

TextAttachments

Customization of "TextAttachments" in RT::Record for tickets.

_UpdateTimeTaken

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

CurrentUserCanSee

Returns true if the current user can see the ticket, using ShowTicket

Reminders

Return the Reminders object for this ticket. (It's an RT::Reminders object.) It isn't acutally a searchbuilder collection itself.

Transactions

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

TransactionCustomFields

    Returns the custom fields that transactions on tickets will have.

AUTHOR

Jesse Vincent, jesse@bestpractical.com