RT 5.0.3 Documentation
RT::Ticket
- SYNOPSIS
- DESCRIPTION
- METHODS
- Load
- Create (ARGS)
- OwnerGroup
- AddWatcher
- DeleteWatcher
- SquelchMailTo ADDRESSES
- UnsquelchMailTo ADDRESS
- RequestorAddresses
- AdminCcAddresses
- CcAddresses
- RoleAddresses
- Requestor
- Cc
- AdminCc
- IsWatcher { Type => TYPE, PrincipalId => PRINCIPAL_ID, Email => EMAIL }
- IsRequestor PRINCIPAL_ID
- IsCc PRINCIPAL_ID
- IsAdminCc PRINCIPAL_ID
- IsOwner
- TransactionAddresses
- QueueObj
- SubjectTag
- DueObj
- ResolvedObj
- FirstActiveStatus
- FirstInactiveStatus
- SetStarted
- StartedObj
- StartsObj
- ToldObj
- TimeWorkedAsString
- TimeLeftAsString
- TimeEstimatedAsString
- TotalTimeWorked
- TotalTimeWorkedAsString
- TimeWorkedPerUser
- TotalTimeWorkedPerUser
- Comment
- Correspond
- _RecordNote
- Atomic
- DryRun
- MergeInto
- Merged
- OwnerObj
- OwnerAsString
- SetOwner
- CurrentUserCanSetOwner
- Take
- Untake
- Steal
- SetStatus STATUS
- Delete
- SetTold ISO [TIMETAKEN]
- _SetTold
- SeenUpTo
- RanTransactionBatch
- TransactionBatch
- ApplyTransactionBatch
- _Value
- Attachments
- TextAttachments
- _UpdateTimeTaken
- CurrentUserCanSee
- Reminders
- Transactions
- TransactionCustomFields
- LoadCustomFieldByIdentifier
- CustomFieldLookupType
- ACLEquivalenceObjects
- ModifyLinkRight
- Forward Transaction => undef, To => '', Cc => '', Bcc => ''
- CurrentUserCanSeeTime
- id
- EffectiveId
- SetEffectiveId VALUE
- Queue
- SetQueue VALUE
- Type
- SetType 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
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>
LazyRoleGroups -- a boolean to control if to create role groups immediately or just when necessary
LazyRoleGroups defaults to $RT::Record::Role::Roles::LAZY_ROLE_GROUPS
, which is false by default.
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 ADDRESSES
Takes a list of email addresses to never email about updates to this ticket. Subsequent calls to this method add, rather than replace, the list of squelched addresses.
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
RoleAddresses
Takes a role name and returns a string of all the email addresses for users in that role
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
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 RT::Interface::Email::Action::Resolve, 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.
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.
TotalTimeWorked
Returns the amount of time worked on this ticket and all child tickets
TotalTimeWorkedAsString
Returns the amount of time worked on this ticket and all its children as a formatted duration string
TimeWorkedPerUser
Returns a hash of user id to the amount of time worked on this ticket for that user
TotalTimeWorkedPerUser
Returns the amount of time worked on this ticket and all child tickets calculated per user
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
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
if there's no MIMEObj, Content is used to build a MIME::Entity object
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.
Atomic
Takes one argument, a subroutine reference. Starts a transaction, taking a write lock on this ticket object, and runs the subroutine in the context of that transaction. Commits the transaction at the end of the block. Returns whatever the subroutine returns.
If the subroutine explicitly calls "Commit" in RT::Handle or "Rollback" in RT::Handle, this function respects that, and will skip is usual commit step. If the subroutine dies, this function will abort the transaction (unless it is already aborted or committed, per above), and will re-die with the error.
This method should be used to lock, and operate atomically on, all ticket changes via the UI (e.g. "ProcessTicketBasics" in RT::Interface::Web).
DryRun
Takes one argument, a subroutine reference. Like "Atomic", starts a transaction and obtains a write lock on this ticket object, running the subroutine in the context of that transaction.
In contrast to "Atomic", the transaction is always rolled back. As such, the body of the function should not call "Commit" in RT::Handle or "Rollback" in RT::Handle, as that would break this method's ability to inspect the entire transaction.
The return value of the subroutine reference is ignored. Returns the set of RT::Transaction objects that would have resulted from running the body of the 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
, orForce
. Note that if the type isTake
, this method will return false if the current user is already the owner; similarly, it will return false forSteal
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
Returns the first comment/correspond transaction not seen by current user.
In list context returns the first not-seen comment/correspond transaction and also the total number of such not-seen transactions.
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.
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.
ModifyLinkRight
Forward Transaction => undef, To => '', Cc => '', Bcc => ''
Forwards transaction with all attachments as 'message/rfc822'.
CurrentUserCanSeeTime
Returns true if the current user can see time worked, estimated, left
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).)
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. Accepts numeric and string values for priority. 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.)
← Back to index