[Rt-commit] rt branch 4.4/preview-searches created. rt-4.4.6-94-g378e2b5286
BPS Git Server
git at git.bestpractical.com
Fri Aug 25 14:59:01 UTC 2023
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 created
at 378e2b528619add807c23a4b9879e0d251e17b20 (commit)
- Log -----------------------------------------------------------------
commit 378e2b528619add807c23a4b9879e0d251e17b20
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
diff --git a/lib/RT/Search/Simple.pm b/lib/RT/Search/Simple.pm
index 80ebd9f6cd..3d70d19c2f 100644
--- a/lib/RT/Search/Simple.pm
+++ b/lib/RT/Search/Simple.pm
@@ -48,13 +48,29 @@
=head1 NAME
- RT::Search::Simple
+RT::Search::Simple
=head1 SYNOPSIS
+ rt-crontool --search RT::Search::Simple \
+ --search-arg "23" \
+ --action RT::Action \
+ --verbose \
+ --log debug
+
=head1 DESCRIPTION
-Use the argument passed in as a simple set of keywords
+The Simple search performs a ticket search using the same mechanism as
+the "Simple Search" web UI.
+
+It expects one Argument which is a string representing the search term.
+The behavior varies a bit depending on RT configuration and user
+preference, check out ticket "Simple Search" page that contains syntax
+and behavior details.
+
+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
@@ -84,11 +100,30 @@ sub _Init {
$self->SUPER::_Init(%args);
}
+=head2 Describe
+
+Returns a localized string describing the module's function.
+
+=cut
+
sub Describe {
my $self = shift;
return ( $self->loc( "Keyword and intuition-based searching", ref $self ) );
}
+
+=head2 Prepare
+
+Runs a simple search on the associated L<RT::Tickets> object, using
+the 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
+
sub Prepare {
my $self = shift;
my $tql = $self->QueryToSQL( $self->Argument );
commit 72d33d42c9ca9d9ec285f49e7d6a5f948f3a2d88
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 fbfb64ddbc..7038903709 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,13 +139,16 @@ if ( $Search ) {
Argument => $SearchArg,
CurrentUser => $session{CurrentUser},
);
- $search->Prepare();
+ $ok = $search->Prepare();
}
else {
$RT::Logger->error("Couldn't load $Search: $@");
Abort( loc( "Couldn't load [_1]", $Search ) );
}
}
+else {
+ $ok = 1;
+}
</%INIT>
commit 0f1e24bdba466c0f9a9c6268f33b4452e7b31e19
Author: sunnavy <sunnavy at bestpractical.com>
Date: Thu Mar 12 01:50:10 2020 +0800
Add new page where admins can preview results of search modules
diff --git a/share/html/Elements/Tabs b/share/html/Elements/Tabs
index 1cb6b17208..228cc7a644 100644
--- a/share/html/Elements/Tabs
+++ b/share/html/Elements/Tabs
@@ -698,6 +698,12 @@ my $build_main_nav = sub {
);
}
+ $tools->child( preview_searches =>
+ title => loc('Search Modules'),
+ description => loc('Preview results of search modules'),
+ path => '/Tools/PreviewSearches.html',
+ );
+
if ( $session{'CurrentUser'}->HasRight( Right => 'ShowConfigTab', Object => RT->System ) )
{
$build_admin_menu->(Menu());
diff --git a/share/html/Tools/PreviewSearches.html b/share/html/Tools/PreviewSearches.html
new file mode 100644
index 0000000000..fbfb64ddbc
--- /dev/null
+++ b/share/html/Tools/PreviewSearches.html
@@ -0,0 +1,152 @@
+%# BEGIN BPS TAGGED BLOCK {{{
+%#
+%# COPYRIGHT:
+%#
+%# This software is Copyright (c) 1996-2019 Best Practical Solutions, LLC
+%# <sales at bestpractical.com>
+%#
+%# (Except where explicitly superseded by other copyright notices)
+%#
+%#
+%# LICENSE:
+%#
+%# This work is made available to you under the terms of Version 2 of
+%# the GNU General Public License. A copy of that license should have
+%# been provided with this software, but in any event can be snarfed
+%# from www.gnu.org.
+%#
+%# This work is distributed in the hope that it will be useful, but
+%# WITHOUT ANY WARRANTY; without even the implied warranty of
+%# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+%# General Public License for more details.
+%#
+%# You should have received a copy of the GNU General Public License
+%# along with this program; if not, write to the Free Software
+%# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+%# 02110-1301 or visit their web page on the internet at
+%# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+%#
+%#
+%# CONTRIBUTION SUBMISSION POLICY:
+%#
+%# (The following paragraph is not intended to limit the rights granted
+%# to you to modify and distribute this software under the terms of
+%# the GNU General Public License and is only of importance to you if
+%# you choose to contribute your changes and enhancements to the
+%# community by submitting them to Best Practical Solutions, LLC.)
+%#
+%# By intentionally submitting any modifications, corrections or
+%# derivatives to this work, or any other work intended for use with
+%# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+%# you are the copyright holder for those contributions and you grant
+%# Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable,
+%# royalty-free, perpetual, license to use, copy, create derivative
+%# works based on those contributions, and sublicense and distribute
+%# those contributions and any derivatives thereof.
+%#
+%# END BPS TAGGED BLOCK }}}
+<& /Elements/Header, Title => loc('Preview results of search modules') &>
+<& /Elements/Tabs &>
+
+<&| /Widgets/TitleBox, title => loc('Search Modules') &>
+ <p>
+ <&|/l&>RT can use searches packaged in modules for some utilities like rt-crontool. This page allows you to run the searches from these modules in the web UI to confirm they find the tickets you expect.</&>
+ </p>
+
+ <p>
+ <&|/l&>Note that the web version of the search will run as the logged in user. To see exactly the same results as rt-crontool, view the search with the user mapped via the Unix Login field or make sure your user account has the same rights as the user running rt-crontool.</&>
+ </p>
+</&>
+
+<form method="POST" action="PreviewSearches.html">
+ <table>
+ <tr>
+ <td align="right"><&|/l&>Search Module</&>:</td>
+ <td>
+ <select name="Search">
+% for my $module ( @modules ) {
+ <option value="<% $module %>" <% $module eq $Search ? 'selected="selected"' : '' |n%>><% $module %></option>
+% }
+ </select>
+ </td>
+ </tr>
+ <tr>
+ <td align="right"><&|/l&>Search argument</&>:</td>
+ <td><input name="SearchArg" size="60" value="<% $SearchArg %>" /></td>
+ </tr>
+% if ( $ShowFormat ) {
+ <tr>
+ <td align="right"><&|/l&>Format</&>:</td>
+ <td><textarea name="Format" rows="8" cols="72"><% $Format %></textarea></td>
+ </tr>
+% }
+ <tr>
+ <td align="right"><&|/l&>Rows per page</&>:</td>
+ <td>
+ <& /Elements/SelectResultsPerPage, Name => "Rows", Default => $Rows &>
+ </td>
+ </tr>
+ </table>
+ <& /Elements/Submit, Label => loc('Search') &>
+</form>
+
+% if ( $tickets ) {
+
+<&| /Widgets/TitleBox, title => loc('Found [quant,_1,ticket,tickets]', $tickets->CountAll) &>
+
+<& /Elements/CollectionList,
+ Collection => $tickets,
+ AllowSorting => 1,
+ Rows => $Rows,
+ Page => $Page,
+ Format => $Format,
+ SearchArg => $SearchArg,
+ Search => $Search,
+ PassArguments => [qw(Format Rows Page Order OrderBy Search SearchArg)],
+&>
+
+</&>
+% }
+
+<%INIT>
+
+use List::MoreUtils 'uniq';
+my @modules;
+for my $root (@INC) {
+ my $mask = File::Spec->catfile( $root, qw(RT Search *.pm) );
+ for my $file ( glob $mask ) {
+ my ($name) = $file =~ /(\w+).pm$/;
+ next if $name =~ /_(?:Overlay|Vendor|Local)$/;
+ push @modules, "RT::Search::$name";
+ }
+}
+
+ at modules = sort( uniq(@modules) );
+
+my $tickets;
+if ( $Search ) {
+ if ( $Search->require ) {
+ $tickets = RT::Tickets->new( $session{CurrentUser} );
+ my $search = $Search->new(
+ TicketsObj => $tickets,
+ Argument => $SearchArg,
+ CurrentUser => $session{CurrentUser},
+ );
+ $search->Prepare();
+ }
+ else {
+ $RT::Logger->error("Couldn't load $Search: $@");
+ Abort( loc( "Couldn't load [_1]", $Search ) );
+ }
+}
+
+</%INIT>
+
+<%ARGS>
+$Search => ''
+$SearchArg => ''
+$Format => RT->Config->Get('DefaultSearchResultFormat')
+$ShowFormat => undef
+$Page => 1
+$Rows => 50
+</%ARGS>
-----------------------------------------------------------------------
hooks/post-receive
--
rt
More information about the rt-commit
mailing list