- SYNOPSIS
- DESCRIPTION
- METHODS
  - Load
  - Create (ARGS)
  - _Parse822HeadersForAttributes Content
  - Import PARAMHASH
  - _CreateTicketGroups
  - OwnerGroup
  - AddWatcher
  - DeleteWatcher { Type => TYPE, PrincipalId => PRINCIPAL_ID, Email => EMAIL_ADDRESS }
  - SquelchMailTo [EMAIL]
  - UnsquelchMailTo ADDRESS
  - RequestorAddresses
  - AdminCcAddresses
  - CcAddresses
  - Requestors
  - Cc
  - AdminCc
  - IsWatcher { Type => TYPE, PrincipalId => PRINCIPAL_ID, Email => EMAIL }
  - IsRequestor PRINCIPAL_ID
  - IsCc PRINCIPAL_ID
  - IsAdminCc PRINCIPAL_ID
  - IsOwner
  - TransactionAddresses
  - QueueObj
  - SubjectTag
  - DueObj
  - DueAsString
  - ResolvedObj
  - FirstActiveStatus
  - FirstInactiveStatus
  - SetStarted
  - StartedObj
  - StartsObj
  - ToldObj
  - ToldAsString
  - TimeWorkedAsString
  - TimeLeftAsString
  - Comment
  - Correspond
  - _RecordNote
  - DryRun
  - DryRunCreate
  - DeleteLink
  - AddLink
  - _AddLink
  - MergeInto
  - Merged
  - OwnerObj
  - OwnerAsString
  - SetOwner
  - Take
  - Untake
  - Steal
  - ValidateStatus STATUS
  - SetStatus STATUS
  - Delete
  - SetTold ISO [TIMETAKEN]
  - _SetTold
  - SeenUpTo
  - RanTransactionBatch
  - TransactionBatch
  - ApplyTransactionBatch
  - _Value
  - _UpdateTimeTaken
  - CurrentUserHasRight
  - CurrentUserCanSee
  - HasRight
  - Reminders
  - Transactions
  - TransactionCustomFields
  - LoadCustomFieldByIdentifier
  - CustomFieldLookupType
  - ACLEquivalenceObjects
- AUTHOR
- SEE ALSO
  - id
  - EffectiveId
  - SetEffectiveId VALUE
  - Queue
  - SetQueue VALUE
  - Type
  - SetType VALUE
  - IssueStatement
  - SetIssueStatement VALUE
  - Resolution
  - SetResolution VALUE
  - Owner
  - SetOwner VALUE
  - Subject
  - SetSubject VALUE
  - InitialPriority
  - SetInitialPriority VALUE
  - FinalPriority
  - SetFinalPriority VALUE
  - Priority
  - SetPriority VALUE
  - TimeEstimated
  - SetTimeEstimated VALUE
  - TimeWorked
  - SetTimeWorked VALUE
  - Status
  - SetStatus VALUE
  - TimeLeft
  - SetTimeLeft VALUE
  - Told
  - SetTold VALUE
  - Starts
  - SetStarts VALUE
  - Started
  - SetStarted VALUE
  - Due
  - SetDue VALUE
  - Resolved
  - SetResolved VALUE
  - LastUpdatedBy
  - LastUpdated
  - Creator
  - Created
  - Disabled
  - SetDisabled VALUE

# 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 (Defined in RT::Queue)
      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

## _Parse822HeadersForAttributes Content

Takes an RFC822 style message and parses its attributes into a hash.

## Import PARAMHASH

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

Returns: TICKETID

## _CreateTicketGroups

Create the ticket groups and links for this ticket. This routine expects to be called from Ticket->Create _inside of a transaction_

It will create four groups for this ticket: Requestor, Cc, AdminCc and Owner.

It will return true on success and undef on failure.

## OwnerGroup

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

## AddWatcher

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

Type One of Requestor, Cc, AdminCc

PrincipalId The RT::Principal id of the user or group that's being added as a watcher

Email The email address of the new watcher. If a user with this email address can't be found, a new nonprivileged user will be created.

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

## DeleteWatcher { Type => TYPE, PrincipalId => PRINCIPAL_ID, Email => EMAIL_ADDRESS }

Deletes a Ticket watcher. Takes two arguments:

Type (one of Requestor,Cc,AdminCc)

and one of

PrincipalId (an RT::Principal Id of the watcher you want to remove) OR Email (the email address of an existing wathcer)

## 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

## Requestors

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 braces, 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

## 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

TODO: This should be deprecated

## 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

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

## DeleteLink

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

If Silent is true then no transaction would be recorded, in other case you can control creation of transactions on both base and target with SilentBase and SilentTarget respectively. By default both transactions are created.

## AddLink

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

If Silent is true then no transaction would be recorded, in other case you can control creation of transactions on both base and target with SilentBase and SilentTarget respectively. By default both transactions are created.

## _AddLink

Private non-acled variant of AddLink so that links can be added during create.

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

## 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, rejected or deleted.

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

## _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.

## CurrentUserCanSee

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

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

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

## LoadCustomFieldByIdentifier

Finds and returns the custom field of the given name for the ticket, overriding "LoadCustomFieldByIdentifier" in RT::Record to look for queue-specific CFs before global ones.

## CustomFieldLookupType

Returns the RT::Ticket lookup type, which can be passed to RT::CustomField->Create() via the 'LookupType' hash key.

## ACLEquivalenceObjects

This method returns a list of objects for which a user's rights also apply to this ticket. Generally, this is only the ticket's queue, but some RT extensions may make other objects available too.

This method is called from "HasRight" in RT::Principal.

# AUTHOR

Jesse Vincent, jesse@bestpractical.com

# SEE ALSO

RT

## id

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

## EffectiveId

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

## SetEffectiveId VALUE

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

## Queue

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

## SetQueue VALUE

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

## Type

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

## SetType VALUE

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

## IssueStatement

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

## SetIssueStatement VALUE

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

## Resolution

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

## SetResolution VALUE

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

## Owner

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

## SetOwner VALUE

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

## Subject

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

## SetSubject VALUE

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

## InitialPriority

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

## SetInitialPriority VALUE

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

## FinalPriority

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

## SetFinalPriority VALUE

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

## Priority

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

## SetPriority VALUE

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

## TimeEstimated

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

## SetTimeEstimated VALUE

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

## TimeWorked

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

## SetTimeWorked VALUE

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

## Status

Returns the current value of Status. (In the database, Status is stored as varchar(64).)

## SetStatus VALUE

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

## TimeLeft

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

## SetTimeLeft VALUE

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

## Told

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

## SetTold VALUE

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

## Starts

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

## SetStarts VALUE

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

## Started

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

## SetStarted VALUE

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

## Due

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

## SetDue VALUE

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

## Resolved

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

## SetResolved VALUE

Set Resolved to VALUE. Returns (1, 'Status message') on success and (0, 'Error Message') on failure. (In the database, Resolved will be stored as a 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.)

## 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.)

## Disabled

Returns the current value of Disabled. (In the database, Disabled is stored as smallint(6).)

## SetDisabled VALUE

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

← Back to index