--- name: "RT::Client::REST::Ticket" section: "3pm" platform: "linux" package: "librt-client-rest-perl" version: "1:0.72-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/RT::Client::REST::Ticket" --- # RT::Client::REST::Ticket(3pm) ticket object representation. ## NAME RT::Client::REST::Ticket - ticket object representation. ## VERSION version 0.72 ## SYNOPSIS ``` my $rt = RT::Client::REST->new(server => $ENV{RTSERVER}); # Create a new ticket: my $ticket = RT::Client::REST::Ticket->new( rt => $rt, queue => "General", subject => $subject, )->store(text => "This is the initial text of the ticket"); print "Created a new ticket, ID ", $ticket->id, "\n"; # Update my $ticket = RT::Client::REST::Ticket->new( rt => $rt, id => $id, priority => 10, )->store; # Retrieve my $ticket => RT::Client::REST::Ticket->new( rt => $rt, id => $id, )->retrieve; unless ($ticket->owner eq $me) { $ticket->steal; # Give me more work! } ``` ## DESCRIPTION **RT::Client::REST::Ticket** is based on RT::Client::REST::Object. The representation allows one to retrieve, edit, comment on, and create tickets in RT. ## ATTRIBUTES - **id** This is the numeric ID of the ticket. - **queue** This is the **name** of the queue (not numeric id). - **owner** Username of the owner. - **creator** Username of RT user who created the ticket. - **subject** Subject of the ticket. - **status** The status is usually one of the following: "new", "open", "resolved", "stalled", "rejected", and "deleted". However, custom RT installations sometimes add their own statuses. - **priority** Ticket priority. Usually a numeric value. - **initial\_priority** - **final\_priority** - **requestor** This is the attribute for setting the requestor on ticket creation. If you use requestors to do this in 3.8, the recipient may not receive an auto-reply from RT because the ticket is initially created as the user your REST session is connected as. It is a list attribute (for explanation of list attributes, see **LIST ATTRIBUTE PROPERTIES** in RT::Client::REST::Object). - **requestors** This contains e-mail addresses of the requestors. It is a list attribute (for explanation of list attributes, see **LIST ATTRIBUTE PROPERTIES** in RT::Client::REST::Object). - **cc** A list of e-mail addresses used to notify people of 'correspond' actions. - **admin\_cc** A list of e-mail addresses used to notify people of all actions performed on a ticket. - **created** Time at which ticket was created. Note that this is an immutable field and therefore the value cannot be changed.. - **starts** - **started** - **due** - **resolved** - **told** - **time\_estimated** - **time\_worked** - **time\_left** - **last\_updated** ### Attributes storing a time The attributes which store a time stamp have an additional accessor with the suffix `"_datetime"` (e.g. `"resolved_datetime"`). This allows you can get and set the stored value as a DateTime object. Internally, it is converted into the date-time string which RT uses, which is assumed to be in UTC. ## DB METHODS For full explanation of these, please see **"DB METHODS"** in RT::Client::REST::Object documentation. - **retrieve** Retrieve RT ticket from database. - **store (\[text =\> $text\])** Create or update the ticket. When creating a new ticket, optional 'text' parameter can be supplied to set the initial text of the ticket. - **search** Search for tickets that meet specific conditions. ## TICKET-SPECIFIC METHODS - **comment** (message =\> $message, %opts) Comment on this ticket with message `$message`. `%opts` is a list of key-value pairs as follows: - **attachments** List of filenames (an array reference) that should be attached to the ticket along with the comment. - **cc** List of e-mail addresses to send carbon copies to (an array reference). - **bcc** List of e-mail addresses to send blind carbon copies to (an array reference). - **correspond** (message =\> $message, %opts) Add correspondence to the ticket. Takes exactly the same arguments as the **comment** method above. - **attachments** Get attachments associated with this ticket. What is returned is an object of type RT::Client::REST::SearchResult which can then be used to get at objects of type RT::Client::REST::Attachment. - **transactions** Get transactions associated with this ticket. Optionally, you can specify exactly what types of transactions you want listed, for example: ``` my $result = $ticket->transactions(type => [qw(Comment Correspond)]); ``` Please reference RT::Client::REST documentation for the full list of valid transaction types. Return value is an object of type RT::Client::REST::SearchResult which can then be used to iterate over transaction objects (RT::Client::REST::Transaction). - **take** Take this ticket. If you already the owner of this ticket, `"RT::Client::REST::Object::NoopOperationException"` will be thrown. - **untake** Untake this ticket. If Nobody is already the owner of this ticket, `"RT::Client::REST::Object::NoopOperationException"` will be thrown. - **steal** Steal this ticket. If you already the owner of this ticket, `"RT::Client::REST::Object::NoopOperationException"` will be thrown. ## CUSTOM FIELDS This class inherits 'cf' method from RT::Client::REST::Object. To create a ticket with a bunch of custom fields, use the following approach: ``` RT::Client::REST::Ticket->new( rt => $rt, # blah blah cf => { 'field one' => $value1, 'field two' => $another_value, }, )->store; ``` Some more examples: ``` # Update a custom field value: $ticket->cf('field one' => $value1); $ticket->store; # Get a custom field value: my $another value = $ticket->cf('field two'); # Get a list of ticket's custom field names: my @custom_fields = $ticket->cf; ``` ## INTERNAL METHODS - **rt\_type** Returns 'ticket'. ## SEE ALSO RT::Client::REST, RT::Client::REST::Object, RT::Client::REST::Attachment, RT::Client::REST::SearchResult, RT::Client::REST::Transaction. ## AUTHOR Dean Hamstead \ ## COPYRIGHT AND LICENSE This software is copyright (c) 2023, 2020 by Dmitri Tikhonov. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.