--- name: "RT::Client::REST::Object" 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::Object" --- # RT::Client::REST::Object(3pm) base class for RT objects ## NAME RT::Client::REST::Object - base class for RT objects ## VERSION version 0.72 ## SYNOPSIS ``` # Create a new type package RT::Client::REST::MyType; use parent qw(RT::Client::REST::Object); sub _attributes {{ myattribute => { validation => { type => SCALAR, }, }, }} sub rt_type { "mytype" } 1; ``` ## DESCRIPTION The RT::Client::REST::Object module is a superclass providing a whole bunch of class and object methods in order to streamline the development of RT's REST client interface. ## ATTRIBUTES Attributes are defined by method `"_attributes"` that should be defined in your class. This method returns a reference to a hash whose keys are the attributes. The values of the hash are attribute settings, which are as follows: - list If set to true, this is a list attribute. See "LIST ATTRIBUTE PROPERTIES" below. - validation A hash reference. This is passed to validation routines when associated mutator is called. See Params::Validate for reference. - rest\_name This specifies this attribute's REST name. For example, attribute "final\_priority" corresponds to RT REST's "FinalPriority". This option may be omitted if the two only differ in first letter capitalization. - form2value Convert form value (one that comes from the server) into attribute-digestible format. - value2form Convert value into REST form format. Example: ``` sub _attributes {{ id => { validation => { type => SCALAR, regex => qr/^\d+$/, }, form2value => sub { shift =~ m~^ticket/(\d+)$~i; return $1; }, value2form => sub { return 'ticket/' . shift; }, }, admin_cc => { validation => { type => ARRAYREF, }, list => 1, rest_name => 'AdminCc', }, }} ``` ## LIST ATTRIBUTE PROPERTIES List attributes have the following properties: - • When called as accessors, return a list of items - • When called as mutators, only accept an array reference - • Convenience methods "add\_attr" and "delete\_attr" are available. For example: ``` # Get the list my @requestors = $ticket->requestors; # Replace with a new list $ticket->requestors( [qw(dude@localhost)] ); # Add some random guys to the current list $ticket->add_requestors('randomguy@localhost', 'evil@local'); ``` ## SPECIAL ATTRIBUTES **id** and **parent\_id** are special attributes. They are used by various DB-related methods and are especially relied upon by: - autostore - autosync - autoget ## METHODS - new Constructor - \_generate\_methods This class method generates accessors and mutators based on **\_attributes** method which your class should provide. For items that are lists, 'add\_' and 'delete\_' methods are created. For instance, the following two attributes specified in **\_attributes** will generate methods 'creator', 'cc', 'add\_cc', and 'delete\_cc': ``` creator => { validation => { type => SCALAR }, }, cc => { list => 1, validation => { type => ARRAYREF }, }, ``` - \_mark\_dirty($attrname) Mark an attribute as dirty. - \_dirty Return the list of dirty attributes. - \_mark\_dirty\_cf($attrname) Mark an custom flag as dirty. - \_dirty\_cf Return the list of dirty custom flags. - to\_form($all) Convert the object to 'form' (used by REST protocol). This is done based on **\_attributes** method. If `$all` is true, create a form from all of the object's attributes and custom flags, otherwise use only dirty (see **\_dirty** method) attributes and custom flags. Defaults to the latter. - from\_form Set object's attributes from form received from RT server. - param($name, $value) Set an arbitrary parameter. - cf(\[$name, \[$value\]\]) Given no arguments, returns the list of custom field names. With one argument, returns the value of custom field `$name`. With two arguments, sets custom field `$name` to `$value`. Given a reference to a hash, uses it as a list of custom fields and their values, returning the new list of all custom field names. - rt Get or set the 'rt' object, which should be of type RT::Client::REST. ## DB METHODS The following are methods that have to do with reading, creating, updating, and searching objects. - count Takes the same arguments as `"search()"` but returns the actual count of the found items. Throws the same exceptions. - retrieve Retrieve object's attributes. Note that 'id' attribute must be set for this to work. - search (%opts) This method is used for searching objects. It returns an object of type RT::Client::REST::SearchResult, which can then be used to process results. `%opts` is a list of key-value pairs, which are as follows: - limits This is a reference to array containing hash references with limits to apply to the search (think SQL limits). - orderby Specifies attribute to sort the result by (in ascending order). - reverseorder If set to a true value, sorts by attribute specified by **orderby** in descending order. If the client cannot construct the query from the specified arguments, or if the server cannot make it out, `"RT::Client::REST::Object::InvalidSearchParametersException"` is thrown. - store Store the object. If 'id' is set, this is an update; otherwise, a new object is created and the 'id' attribute is set. Note that only changed (dirty) attributes are sent to the server. ## CLASS METHODS - use\_single\_rt This method takes a single argument -- RT::Client::REST object and makes this class use it for all instantiations. For example: ``` my $rt = RT::Client::REST->new(%args); # Make all tickets use this RT: RT::Client::REST::Ticket->use_single_rt($rt); # Now make all objects use it: RT::Client::REST::Object->use_single_rt($rt); ``` - use\_autostore Turn *autostoring* on and off. *Autostoring* means that you do not have to explicitly call `"store()"` on an object - it will be called when the object goes out of scope. ``` # Autostore tickets: RT::Client::REST::Ticket->use_autostore(1); my $ticket = RT::Client::REST::Ticket->new(%opts)->retrieve; $ticket->priority(10); # Don't have to call store(). ``` - use\_autoget Turn *autoget* feature on or off (off by default). When set to on, `"retrieve()"` will be automatically called from the constructor if it is called with that object's special attributes (see "SPECIAL ATTRIBUTES" above). ``` RT::Client::Ticket->use_autoget(1); my $ticket = RT::Client::Ticket->new(id => 1); # Now all attributes are available: my $subject = $ticket->subject; ``` - use\_autosync Turn *autosync* feature on or off (off by default). When set, every time an attribute is changed, `"store()"` method is invoked. This may be pretty expensive. - be\_transparent This turns on **autosync** and **autoget**. Transparency is a neat idea, but it may be expensive and slow. Depending on your circumstances, you may want a finer control of your objects. Transparency makes `"retrieve()"` and `"store()"` calls invisible: ``` RT::Client::REST::Ticket->be_transparent($rt); my $ticket = RT::Client::REST::Ticket->new(id => $id); # retrieved $ticket->add_cc('you@localhost.localdomain'); # stored $ticket->status('stalled'); # stored # etc. ``` Do not forget to pass RT::Client::REST object to this method. ## SEE ALSO RT::Client::REST::Ticket, RT::Client::REST::SearchResult. ## 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.