[Rt-commit] rt branch 4.4/preview-searches updated. rt-4.4.6-94-g2e5f6ac123

[BPS Git Server]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "rt".

The branch, 4.4/preview-searches has been updated
       via  2e5f6ac123c390340209f76e00eb1da7eb4b565f (commit)
       via  d27efe60a058c370c9c3867f953073cbfc313e4c (commit)
      from  815c333d44f7c5641b5b78378aaa1f1de821342d (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 2e5f6ac123c390340209f76e00eb1da7eb4b565f
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Tue Aug 22 10:35:57 2023 -0400

    Improve documentation for RT::Search modules
    
    The new RT::Search test page in the web UI may lead
    users to read the documentation for the search modules,
    so clean up and improve those pages.

diff --git a/lib/RT/Search/ActiveTicketsInQueue.pm b/lib/RT/Search/ActiveTicketsInQueue.pm
index 7153b26e9d..31e36e5feb 100644
--- a/lib/RT/Search/ActiveTicketsInQueue.pm
+++ b/lib/RT/Search/ActiveTicketsInQueue.pm
@@ -48,19 +48,22 @@
 
 =head1 NAME
 
-  RT::Search::ActiveTicketsInQueue
+RT::Search::ActiveTicketsInQueue
 
 =head1 SYNOPSIS
 
+    rt-crontool --search RT::Search::ActiveTicketsInQueue \
+        --search-arg "General" \
+        --action RT::Action \
+        --verbose \
+        --log debug
+
 =head1 DESCRIPTION
 
-Find all active tickets in the queue named in the argument passed in
+Find all active tickets in the queue named in the provided Argument.
 
 =head1 METHODS
 
-
-
-
 =cut
 
 package RT::Search::ActiveTicketsInQueue;
@@ -69,12 +72,30 @@ use strict;
 use warnings;
 use base qw(RT::Search);
 
+=head2 Describe
+
+Returns a localized string describing the module's function.
+
+=cut
 
 sub Describe  {
   my $self = shift;
-  return ($self->loc("No description for [_1]", ref $self));
+  return ($self->loc("Find active tickets in a queue [_1]", ref $self));
 }
 
+=head2 Prepare
+
+Runs a search on the associated L<RT::Tickets> object, limiting
+it to active tickets in the queue identified by the provided
+Argument.
+
+The search is performed in the context of the user running the
+command. For rt-crontool searches, this is the L<RT::User> account
+associated with the Linux account running rt-crontool via the
+"Unix login" setting.
+
+=cut
+
 sub Prepare  {
   my $self = shift;
 
diff --git a/lib/RT/Search/FromSQL.pm b/lib/RT/Search/FromSQL.pm
index 0064833b79..edfeeba1dd 100644
--- a/lib/RT/Search/FromSQL.pm
+++ b/lib/RT/Search/FromSQL.pm
@@ -48,18 +48,33 @@
 
 =head1 NAME
 
-  RT::Search::FromSQL
+RT::Search::FromSQL
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
+    rt-crontool --search RT::Search::FromSQL \
+        --search-arg "Owner = 'root'" \
+        --action RT::Action \
+        --verbose \
+        --log debug
 
-Find all tickets described by the SQL statement passed as an argument
+=head1 DESCRIPTION
 
-=head1 METHODS
+The FromSQL search performs a ticket search using the same
+mechanism as the RT Query Builder.
 
+It expects one Argument which is a TicketSQL string. Since the
+search is the same as the RT Query Builder, you can paste in
+a search directly from the Advanced tab. The search is then
+performed on the L<RT::Tickets> object associated with the running
+search.
 
+When running with a command-line utility such as
+rt-crontool, you may need to apply shell escapes or make
+other format changes to correctly pass special characters
+through the shell.
 
+=head1 METHODS
 
 =cut
 
@@ -82,9 +97,13 @@ sub Describe  {
 
 =head2 Prepare
 
-The meat of the module.  Runs a search on its Tickets object, using
-the SQL string described in its Argument object.  The Tickets object
-is reduced to those tickets matching the SQL query.
+Runs a search on the associated L<RT::Tickets> object, using
+the TicketSQL string provided in the Argument.
+
+The search is performed in the context of the user running the
+command. For rt-crontool searches, this is the L<RT::User> account
+associated with the Linux account running rt-crontool via the
+"Unix login" setting.
 
 =cut
 

commit d27efe60a058c370c9c3867f953073cbfc313e4c
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Tue Aug 22 10:12:23 2023 -0400

    Check the return value for Prepare
    
    Current searches always return true, even when the search
    fails to run as expected. Add a check to report failure
    for future updates to Prepare that return more helpful
    values.

diff --git a/share/html/Tools/PreviewSearches.html b/share/html/Tools/PreviewSearches.html
index d9eb7f2bbc..2454eb3158 100644
--- a/share/html/Tools/PreviewSearches.html
+++ b/share/html/Tools/PreviewSearches.html
@@ -108,6 +108,12 @@
 </&>
 % }
 
+% if ( not $ok ) {
+    <p>
+      <&|/l&>Your search did not run as expected. Confirm your argument is a value expected for the search and the format is correct. RT's logs may have more information.</&>
+    </p>
+% }
+
 <%INIT>
 
 use List::MoreUtils 'uniq';
@@ -124,6 +130,7 @@ for my $root (@INC) {
 @modules = sort( uniq(@modules) );
 
 my $tickets;
+my $ok;
 if ( $Search ) {
     if ( $Search->require ) {
         $tickets = RT::Tickets->new( $session{CurrentUser} );
@@ -132,7 +139,7 @@ if ( $Search ) {
             Argument    => $SearchArg,
             CurrentUser => $session{CurrentUser},
         );
-        $search->Prepare();
+        $ok = $search->Prepare();
     }
     else {
         $RT::Logger->error("Couldn't load $Search: $@");

-----------------------------------------------------------------------

Summary of changes:
 lib/RT/Search/ActiveTicketsInQueue.pm | 33 +++++++++++++++++++++++++++------
 lib/RT/Search/FromSQL.pm              | 33 ++++++++++++++++++++++++++-------
 share/html/Tools/PreviewSearches.html |  9 ++++++++-
 3 files changed, 61 insertions(+), 14 deletions(-)


hooks/post-receive
-- 
rt