rt4-doc-html 4.0.19-1 / usr / share / doc / rt4-doc-html / RT / Tickets.html

<ul id="index">
  <li><a href="#NAME">NAME</a></li>
  <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="#METHODS">METHODS</a>
    <ul>
      <li><a href="#SortFields">SortFields</a></li>
    </ul>
  </li>
  <li><a href="#Limit-Helper-Routines">Limit Helper Routines</a>
    <ul>
      <li><a href="#IdLimit">_IdLimit</a></li>
      <li><a href="#EnumLimit">_EnumLimit</a></li>
      <li><a href="#IntLimit">_IntLimit</a></li>
      <li><a href="#LinkLimit">_LinkLimit</a></li>
      <li><a href="#DateLimit">_DateLimit</a></li>
      <li><a href="#StringLimit">_StringLimit</a></li>
      <li><a href="#TransDateLimit">_TransDateLimit</a></li>
      <li><a href="#TransLimit">_TransLimit</a></li>
      <li><a href="#TransContentLimit">_TransContentLimit</a></li>
      <li><a href="#WatcherLimit">_WatcherLimit</a></li>
      <li><a href="#WatcherJoin">_WatcherJoin</a></li>
      <li><a href="#WatcherMembershipLimit">_WatcherMembershipLimit</a></li>
      <li><a href="#CustomFieldDecipher">_CustomFieldDecipher</a></li>
      <li><a href="#CustomFieldJoin">_CustomFieldJoin</a></li>
      <li><a href="#CustomFieldLimit">_CustomFieldLimit</a></li>
      <li><a href="#OrderByCols-ARRAY">OrderByCols ARRAY</a></li>
      <li><a href="#Limit">Limit</a></li>
      <li><a href="#LimitQueue">LimitQueue</a></li>
      <li><a href="#LimitStatus">LimitStatus</a></li>
      <li><a href="#IgnoreType">IgnoreType</a></li>
      <li><a href="#LimitType">LimitType</a></li>
      <li><a href="#LimitSubject">LimitSubject</a></li>
      <li><a href="#LimitId">LimitId</a></li>
      <li><a href="#LimitPriority">LimitPriority</a></li>
      <li><a href="#LimitInitialPriority">LimitInitialPriority</a></li>
      <li><a href="#LimitFinalPriority">LimitFinalPriority</a></li>
      <li><a href="#LimitTimeWorked">LimitTimeWorked</a></li>
      <li><a href="#LimitTimeLeft">LimitTimeLeft</a></li>
      <li><a href="#LimitContent">LimitContent</a></li>
      <li><a href="#LimitFilename">LimitFilename</a></li>
      <li><a href="#LimitContentType">LimitContentType</a></li>
      <li><a href="#LimitOwner">LimitOwner</a></li>
      <li><a href="#LimitWatcher">LimitWatcher</a></li>
      <li><a href="#LimitLinkedTo">LimitLinkedTo</a></li>
      <li><a href="#LimitLinkedFrom">LimitLinkedFrom</a></li>
      <li><a href="#LimitDate-FIELD-DateField-OPERATOR-oper-VALUE-ISODate">LimitDate (FIELD =&gt; &#39;DateField&#39;, OPERATOR =&gt; $oper, VALUE =&gt; $ISODate)</a></li>
      <li><a href="#LimitTransactionDate-OPERATOR-oper-VALUE-ISODate">LimitTransactionDate (OPERATOR =&gt; $oper, VALUE =&gt; $ISODate)</a></li>
      <li><a href="#LimitCustomField">LimitCustomField</a></li>
      <li><a href="#NextIndex">_NextIndex</a></li>
      <li><a href="#ItemsArrayRef">ItemsArrayRef</a></li>
      <li><a href="#LoadRestrictions">LoadRestrictions</a></li>
      <li><a href="#DescribeRestrictions">DescribeRestrictions</a></li>
      <li><a href="#RestrictionValues-FIELD">RestrictionValues FIELD</a></li>
      <li><a href="#ClearRestrictions">ClearRestrictions</a></li>
      <li><a href="#DeleteRestriction">DeleteRestriction</a></li>
      <li><a href="#ProcessRestrictions-PARAMHASH">_ProcessRestrictions PARAMHASH</a></li>
      <li><a href="#BuildItemMap">_BuildItemMap</a></li>
      <li><a href="#ItemMap">ItemMap</a></li>
      <li><a href="#PrepForSerialization">PrepForSerialization</a></li>
    </ul>
  </li>
  <li><a href="#FLAGS">FLAGS</a>
    <ul>
      <li><a href="#NewItem">NewItem</a></li>
    </ul>
  </li>
</ul>

<h1 id="NAME"><a href="#___top">NAME</a></h1>

<pre><code>  RT::Tickets - A collection of Ticket objects</code></pre>

<h1 id="SYNOPSIS"><a href="#___top">SYNOPSIS</a></h1>

<pre><code>  use RT::Tickets;
  my $tickets = RT::Tickets-&gt;new($CurrentUser);</code></pre>

<h1 id="DESCRIPTION"><a href="#___top">DESCRIPTION</a></h1>

<pre><code>   A collection of RT::Tickets.</code></pre>

<h1 id="METHODS"><a href="#___top">METHODS</a></h1>

<h2 id="SortFields"><a href="#___top">SortFields</a></h2>

<p>Returns the list of fields that lists of tickets can easily be sorted by</p>

<h1 id="Limit-Helper-Routines"><a href="#___top">Limit Helper Routines</a></h1>

<p>These routines are the targets of a dispatch table depending on the type of field. They all share the same signature:</p>

<pre><code>  my ($self,$field,$op,$value,@rest) = @_;</code></pre>

<p>The values in @rest should be suitable for passing directly to DBIx::SearchBuilder::Limit.</p>

<p>Essentially they are an expanded/broken out (and much simplified) version of what ProcessRestrictions used to do. They&#39;re also much more clearly delineated by the TYPE of field being processed.</p>

<h2 id="IdLimit"><a href="#___top">_IdLimit</a></h2>

<p>Handle ID field.</p>

<h2 id="EnumLimit"><a href="#___top">_EnumLimit</a></h2>

<p>Handle Fields which are limited to certain values, and potentially need to be looked up from another class.</p>

<p>This subroutine actually handles two different kinds of fields. For some the user is responsible for limiting the values. (i.e. Status, Type).</p>

<p>For others, the value specified by the user will be looked by via specified class.</p>

<p>Meta Data: name of class to lookup in (Optional)</p>

<h2 id="IntLimit"><a href="#___top">_IntLimit</a></h2>

<p>Handle fields where the values are limited to integers. (For example, Priority, TimeWorked.)</p>

<p>Meta Data: None</p>

<h2 id="LinkLimit"><a href="#___top">_LinkLimit</a></h2>

<p>Handle fields which deal with links between tickets. (MemberOf, DependsOn)</p>

<p>Meta Data: 1: Direction (From, To) 2: Link Type (MemberOf, DependsOn, RefersTo)</p>

<h2 id="DateLimit"><a href="#___top">_DateLimit</a></h2>

<p>Handle date fields. (Created, LastTold..)</p>

<p>Meta Data: 1: type of link. (Probably not necessary.)</p>

<h2 id="StringLimit"><a href="#___top">_StringLimit</a></h2>

<p>Handle simple fields which are just strings. (Subject,Type)</p>

<p>Meta Data: None</p>

<h2 id="TransDateLimit"><a href="#___top">_TransDateLimit</a></h2>

<p>Handle fields limiting based on Transaction Date.</p>

<p>The inpupt value must be in a format parseable by Time::ParseDate</p>

<p>Meta Data: None</p>

<h2 id="TransLimit"><a href="#___top">_TransLimit</a></h2>

<p>Limit based on the ContentType or the Filename of a transaction.</p>

<h2 id="TransContentLimit"><a href="#___top">_TransContentLimit</a></h2>

<p>Limit based on the Content of a transaction.</p>

<h2 id="WatcherLimit"><a href="#___top">_WatcherLimit</a></h2>

<p>Handle watcher limits. (Requestor, CC, etc..)</p>

<p>Meta Data: 1: Field to query on</p>

<h2 id="WatcherJoin"><a href="#___top">_WatcherJoin</a></h2>

<p>Helper function which provides joins to a watchers table both for limits and for ordering.</p>

<h2 id="WatcherMembershipLimit"><a href="#___top">_WatcherMembershipLimit</a></h2>

<p>Handle watcher membership limits, i.e. whether the watcher belongs to a specific group or not.</p>

<p>Meta Data: 1: Field to query on</p>

<p>SELECT DISTINCT main.* FROM Tickets main, Groups Groups_1, CachedGroupMembers CachedGroupMembers_2, Users Users_3 WHERE ( (main.EffectiveId = main.id) ) AND ( (main.Status != &#39;deleted&#39;) ) AND ( (main.Type = &#39;ticket&#39;) ) AND ( ( (Users_3.EmailAddress = &#39;22&#39;) AND (Groups_1.Domain = &#39;RT::Ticket-Role&#39;) AND (Groups_1.Type = &#39;RequestorGroup&#39;) ) ) AND Groups_1.Instance = main.id AND Groups_1.id = CachedGroupMembers_2.GroupId AND CachedGroupMembers_2.MemberId = Users_3.id ORDER BY main.id ASC LIMIT 25</p>

<h2 id="CustomFieldDecipher"><a href="#___top">_CustomFieldDecipher</a></h2>

<p>Try and turn a CF descriptor into (cfid, cfname) object pair.</p>

<p>Takes an optional second parameter of the CF LookupType, defaults to Ticket CFs.</p>

<h2 id="CustomFieldJoin"><a href="#___top">_CustomFieldJoin</a></h2>

<p>Factor out the Join of custom fields so we can use it for sorting too</p>

<h2 id="CustomFieldLimit"><a href="#___top">_CustomFieldLimit</a></h2>

<p>Limit based on CustomFields</p>

<p>Meta Data: none</p>

<h2 id="OrderByCols-ARRAY"><a href="#___top">OrderByCols ARRAY</a></h2>

<p>A modified version of the OrderBy method which automatically joins where <code>ALIAS</code> is set to the name of a watcher type.</p>

<h2 id="Limit"><a href="#___top">Limit</a></h2>

<p>Takes a paramhash with the fields FIELD, OPERATOR, VALUE and DESCRIPTION Generally best called from LimitFoo methods</p>

<h2 id="LimitQueue"><a href="#___top">LimitQueue</a></h2>

<p>LimitQueue takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. (It defaults to =). VALUE is a queue id or Name.</p>

<h2 id="LimitStatus"><a href="#___top">LimitStatus</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a status.</p>

<p>RT adds Status != &#39;deleted&#39; until object has allow_deleted_search internal property set. $tickets-&gt;{&#39;allow_deleted_search&#39;} = 1; $tickets-&gt;LimitStatus( VALUE =&gt; &#39;deleted&#39; );</p>

<h2 id="IgnoreType"><a href="#___top">IgnoreType</a></h2>

<p>If called, this search will not automatically limit the set of results found to tickets of type &quot;Ticket&quot;. Tickets of other types, such as &quot;project&quot; and &quot;approval&quot; will be found.</p>

<h2 id="LimitType"><a href="#___top">LimitType</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=, it defaults to &quot;=&quot;. VALUE is a string to search for in the type of the ticket.</p>

<h2 id="LimitSubject"><a href="#___top">LimitSubject</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a string to search for in the subject of the ticket.</p>

<h2 id="LimitId"><a href="#___top">LimitId</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a ticket Id to search for</p>

<h2 id="LimitPriority"><a href="#___top">LimitPriority</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a value to match the ticket&#39;s priority against</p>

<h2 id="LimitInitialPriority"><a href="#___top">LimitInitialPriority</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a value to match the ticket&#39;s initial priority against</p>

<h2 id="LimitFinalPriority"><a href="#___top">LimitFinalPriority</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a value to match the ticket&#39;s final priority against</p>

<h2 id="LimitTimeWorked"><a href="#___top">LimitTimeWorked</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a value to match the ticket&#39;s TimeWorked attribute</p>

<h2 id="LimitTimeLeft"><a href="#___top">LimitTimeLeft</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, &gt;, &lt; or !=. VALUE is a value to match the ticket&#39;s TimeLeft attribute</p>

<h2 id="LimitContent"><a href="#___top">LimitContent</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a string to search for in the body of the ticket</p>

<h2 id="LimitFilename"><a href="#___top">LimitFilename</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a string to search for in the body of the ticket</p>

<h2 id="LimitContentType"><a href="#___top">LimitContentType</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of =, LIKE, NOT LIKE or !=. VALUE is a content type to search ticket attachments for</p>

<h2 id="LimitOwner"><a href="#___top">LimitOwner</a></h2>

<p>Takes a paramhash with the fields OPERATOR and VALUE. OPERATOR is one of = or !=. VALUE is a user id.</p>

<h2 id="LimitWatcher"><a href="#___top">LimitWatcher</a></h2>

<pre><code>  Takes a paramhash with the fields OPERATOR, TYPE and VALUE.
  OPERATOR is one of =, LIKE, NOT LIKE or !=.
  VALUE is a value to match the ticket&#39;s watcher email addresses against
  TYPE is the sort of watchers you want to match against. Leave it undef if you want to search all of them</code></pre>

<h2 id="LimitLinkedTo"><a href="#___top">LimitLinkedTo</a></h2>

<p>LimitLinkedTo takes a paramhash with two fields: TYPE and TARGET TYPE limits the sort of link we want to search on</p>

<p>TYPE = { RefersTo, MemberOf, DependsOn }</p>

<p>TARGET is the id or URI of the TARGET of the link</p>

<h2 id="LimitLinkedFrom"><a href="#___top">LimitLinkedFrom</a></h2>

<p>LimitLinkedFrom takes a paramhash with two fields: TYPE and BASE TYPE limits the sort of link we want to search on</p>

<p>BASE is the id or URI of the BASE of the link</p>

<h2 id="LimitDate-FIELD-DateField-OPERATOR-oper-VALUE-ISODate"><a href="#___top">LimitDate (FIELD =&gt; &#39;DateField&#39;, OPERATOR =&gt; $oper, VALUE =&gt; $ISODate)</a></h2>

<p>Takes a paramhash with the fields FIELD OPERATOR and VALUE.</p>

<p>OPERATOR is one of &gt; or &lt; VALUE is a date and time in ISO format in GMT FIELD is one of Starts, Started, Told, Created, Resolved, LastUpdated</p>

<p>There are also helper functions of the form LimitFIELD that eliminate the need to pass in a FIELD argument.</p>

<h2 id="LimitTransactionDate-OPERATOR-oper-VALUE-ISODate"><a href="#___top">LimitTransactionDate (OPERATOR =&gt; $oper, VALUE =&gt; $ISODate)</a></h2>

<p>Takes a paramhash with the fields FIELD OPERATOR and VALUE.</p>

<p>OPERATOR is one of &gt; or &lt; VALUE is a date and time in ISO format in GMT</p>

<h2 id="LimitCustomField"><a href="#___top">LimitCustomField</a></h2>

<p>Takes a paramhash of key/value pairs with the following keys:</p>

<dl>

<dt id="CUSTOMFIELD---CustomField-name-or-id.-If-a-name-is-passed-an-additional-parameter-QUEUE-may-also-be-passed-to-distinguish-the-custom-field">CUSTOMFIELD - CustomField name or id. If a name is passed, an additional parameter QUEUE may also be passed to distinguish the custom field.</dt>
<dd>

</dd>
<dt id="OPERATOR---The-usual-Limit-operators">OPERATOR - The usual Limit operators</dt>
<dd>

</dd>
<dt id="VALUE---The-value-to-compare-against">VALUE - The value to compare against</dt>
<dd>

</dd>
</dl>

<h2 id="NextIndex"><a href="#___top">_NextIndex</a></h2>

<p>Keep track of the counter for the array of restrictions</p>

<h2 id="ItemsArrayRef"><a href="#___top">ItemsArrayRef</a></h2>

<p>Returns a reference to the set of all items found in this search</p>

<h2 id="LoadRestrictions"><a href="#___top">LoadRestrictions</a></h2>

<p>LoadRestrictions takes a string which can fully populate the TicketRestrictons hash. TODO It is not yet implemented</p>

<h2 id="DescribeRestrictions"><a href="#___top">DescribeRestrictions</a></h2>

<p>takes nothing. Returns a hash keyed by restriction id. Each element of the hash is currently a one element hash that contains DESCRIPTION which is a description of the purpose of that TicketRestriction</p>

<h2 id="RestrictionValues-FIELD"><a href="#___top">RestrictionValues FIELD</a></h2>

<p>Takes a restriction field and returns a list of values this field is restricted to.</p>

<h2 id="ClearRestrictions"><a href="#___top">ClearRestrictions</a></h2>

<p>Removes all restrictions irretrievably</p>

<h2 id="DeleteRestriction"><a href="#___top">DeleteRestriction</a></h2>

<p>Takes the row Id of a restriction (From DescribeRestrictions&#39; output, for example. Removes that restriction from the session&#39;s limits.</p>

<h2 id="ProcessRestrictions-PARAMHASH"><a href="#___top">_ProcessRestrictions PARAMHASH</a></h2>

<p># The new _ProcessRestrictions is somewhat dependent on the SQL stuff, # but isn&#39;t quite generic enough to move into Tickets_SQL.</p>

<h2 id="BuildItemMap"><a href="#___top">_BuildItemMap</a></h2>

<p>Build up a <a href="#ItemMap">&quot;ItemMap&quot;</a> of first/last/next/prev items, so that we can display search nav quickly.</p>

<h2 id="ItemMap"><a href="#___top">ItemMap</a></h2>

<p>Returns an a map of all items found by this search. The map is a hash of the form:</p>

<pre><code>    {
        first =&gt; &lt;first ticket id found&gt;,
        last =&gt; &lt;last ticket id found or undef&gt;,

        &lt;ticket id&gt; =&gt; {
            prev =&gt; &lt;the ticket id found before&gt;,
            next =&gt; &lt;the ticket id found after&gt;,
        },
        &lt;ticket id&gt; =&gt; {
            prev =&gt; ...,
            next =&gt; ...,
        },
    }</code></pre>

<h2 id="PrepForSerialization"><a href="#___top">PrepForSerialization</a></h2>

<p>You don&#39;t want to serialize a big tickets object, as the {items} hash will be instantly invalid _and_ eat lots of space</p>

<h1 id="FLAGS"><a href="#___top">FLAGS</a></h1>

<p>RT::Tickets supports several flags which alter search behavior:</p>

<p>allow_deleted_search (Otherwise never show deleted tickets in search results) looking_at_type (otherwise limit to type=ticket)</p>

<p>These flags are set by calling</p>

<p>$tickets-&gt;{&#39;flagname&#39;} = 1;</p>

<p>BUG: There should be an API for this</p>

<h2 id="NewItem"><a href="#___top">NewItem</a></h2>

<p>Returns an empty new RT::Ticket item</p>

<a href="./../">&larr; Back to index</a>