[Bps-public-commit] rt-extension-admin-conditions-and-actions branch, master, updated. da50b8937e494bc7402c97779e06658686b9f613
Jim Brandt
jbrandt at bestpractical.com
Thu Dec 19 15:26:32 EST 2013
The branch, master has been updated
via da50b8937e494bc7402c97779e06658686b9f613 (commit)
via 82a20a1c49d0bf257d4c142a8cb8c9e3546a4d32 (commit)
from 53c82d988461e7ac9c16679c5f3f902361023d66 (commit)
Summary of changes:
MANIFEST | 34 ++++
README | 255 ++++++++++++++++++++++++++
inc/Module/Install/RTx.pm | 11 +-
inc/Module/Install/ReadmeFromPod.pm | 2 +-
lib/RT/Extension/AdminConditionsAndActions.pm | 5 +
5 files changed, 304 insertions(+), 3 deletions(-)
create mode 100644 MANIFEST
- Log -----------------------------------------------------------------
commit 82a20a1c49d0bf257d4c142a8cb8c9e3546a4d32
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Mon Dec 2 11:41:50 2013 -0500
Note RT versions supported
diff --git a/lib/RT/Extension/AdminConditionsAndActions.pm b/lib/RT/Extension/AdminConditionsAndActions.pm
index 60e42bf..5c8918d 100644
--- a/lib/RT/Extension/AdminConditionsAndActions.pm
+++ b/lib/RT/Extension/AdminConditionsAndActions.pm
@@ -72,6 +72,11 @@ RT-Extension-AdminConditionsAndActions - Admin Conditions And Actions
A web UI for managing RT conditions and actions.
+=head1 RT VERSIONS
+
+This version of this extension is intended to work with the following versions
+of RT: 4.0, 4.2
+
=head1 INSTALLATION
=over
commit da50b8937e494bc7402c97779e06658686b9f613
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Mon Dec 2 11:42:38 2013 -0500
Prep for initial 0.01 release
diff --git a/MANIFEST b/MANIFEST
new file mode 100644
index 0000000..f109a24
--- /dev/null
+++ b/MANIFEST
@@ -0,0 +1,34 @@
+html/Admin/Actions/autohandler
+html/Admin/Actions/Create.html
+html/Admin/Actions/Display.html
+html/Admin/Actions/Elements/EditBasics
+html/Admin/Actions/Elements/ShowBasics
+html/Admin/Actions/Modify.html
+html/Admin/Conditions/autohandler
+html/Admin/Conditions/Create.html
+html/Admin/Conditions/Display.html
+html/Admin/Conditions/Elements/EditBasics
+html/Admin/Conditions/Elements/ShowBasics
+html/Admin/Conditions/Modify.html
+html/Admin/Elements/EditActions
+html/Admin/Elements/EditConditions
+html/Admin/Global/Actions.html
+html/Admin/Global/Conditions.html
+html/Callbacks/AdminConditionsAndActions/Elements/Tabs/Privileged
+html/Elements/RT__ScripAction/ColumnMap
+html/Elements/RT__ScripCondition/ColumnMap
+inc/Module/Install.pm
+inc/Module/Install/Base.pm
+inc/Module/Install/Can.pm
+inc/Module/Install/Fetch.pm
+inc/Module/Install/Makefile.pm
+inc/Module/Install/Metadata.pm
+inc/Module/Install/ReadmeFromPod.pm
+inc/Module/Install/RTx.pm
+inc/Module/Install/Win32.pm
+inc/Module/Install/WriteAll.pm
+lib/RT/Extension/AdminConditionsAndActions.pm
+Makefile.PL
+MANIFEST This list of files
+META.yml
+README
diff --git a/README b/README
index 9770d7a..0169f87 100644
--- a/README
+++ b/README
@@ -1,6 +1,13 @@
NAME
RT-Extension-AdminConditionsAndActions - Admin Conditions And Actions
+DESCRIPTION
+ A web UI for managing RT conditions and actions.
+
+RT VERSIONS
+ This version of this extension is intended to work with the following
+ versions of RT: 4.0, 4.2
+
INSTALLATION
"perl Makefile.PL"
"make"
@@ -35,6 +42,254 @@ INSTALLATION
Restart your webserver
+USAGE
+ The core building blocks of scrips in RT are the conditions and actions
+ you select when configuring the scrip. A condition defines the criteria
+ for an action to run in the context of the current transaction. The
+ result is true or false: if true, the condition is satisfied and the
+ action runs, if false, the action is skipped. Actions define something
+ to be done when a condition is true and they can be anything you can
+ capture in code, either changing things in RT or calling out to other
+ systems, DBs, or APIs.
+
+ You can view all of the scrips that come standard with RT by going to
+ Tools > Global > Scrips (RT 4.0) or Admin > Global > Scrips (RT 4.2). In
+ the scrips list you'll see each has a condition and an action and these
+ are provided with the initial RT installation. You might also see
+ additional conditions and actions added by extensions or through a local
+ customization.
+
+ This extension provides a web UI to allow you to easily register your
+ own conditions and actions in RT, making it easier than ever to
+ customize RT for your specific needs.
+
+ User Defined Conditions and Actions
+ The simplest way to add a custom condition or action is to create a new
+ scrip and select "User Defined" as the Condition or Action. You can then
+ put your custom code right in the "User Defined" boxes on the bottom of
+ the scrip modification page.
+
+ However, you might prefer writing your condition or action in a module
+ with the code in a file. This allows you to track it in version control
+ and call it from other places like "rt-crontool". The following sections
+ describe how to create these modules.
+
+ Custom Conditions
+ Let's assume you have a custom lifecycle with a status called 'review'
+ and you want an 'On Review Needed' condition so you can trigger actions
+ when a ticket is put in review status. You notice RT already has 'On
+ Resolve' and other similar conditions, so you look at the configuration
+ at Admin > Global > Conditions and click on 'On Resolve' (in RT 4.0,
+ select Tools > Global > Conditions.)
+
+ The condition has a Name, which is displayed in the Condition dropdown
+ when you create a scrip, and a Description to identify it. The Condition
+ Module is the RT module that executes the condition, in this case
+ "StatusChange". You can find the code in
+ "/opt/rt4/lib/RT/Condition/StatusChange.pm" and view the documentation
+ on the Best Practical "documentation site". (Confirm your RT version
+ when checking the documentation.)
+
+ Parameters to Pass shows the actual parameter that is passed to the
+ module when this condition is executed. When you look at the module
+ documentation it makes sense when you see that "StatusChange" accepts a
+ valid status and returns true if the transaction is setting the status
+ to the provided value. Finally, Applicable Transaction Types lists the
+ transactions for which this condition will run, and in this case it's
+ Status transactions.
+
+ This is really close to what we might need for our 'On Review Needed' so
+ you can click the Copy Condition button to copy the current condition.
+ On the new condition page, you can update the Name and Description and
+ set the Parameters to Pass to 'review'. Then click save and you have
+ your new condition. You can now create a new scrip and select it from
+ the Condition dropdown.
+
+ Custom Condition Module
+ Now assume we have an additional requirement to check if a custom field
+ value 'Special' is selected when we check the review status. For this
+ one we'll need to write some code. To start, create a new file for your
+ new SpecialReviewNeeded module here:
+
+ /opt/rt4/local/lib/RT/Condition/SpecialReviewNeeded.pm
+
+ Creating it in the "local" directory will keep it safe when you apply RT
+ upgrades in the future.
+
+ The basics of a condition module are as follows:
+
+ package RT::Condition::SpecialReviewNeeded;
+
+ use strict;
+ use warnings;
+ use base 'RT::Condition';
+
+ sub IsApplicable {
+ my $self = shift;
+
+ # Your code here
+
+ return 1; # True if condition is true, false if not
+ }
+
+ 1; # Don't forget module needs this
+
+ "IsApplicable" is the method you will override from the "RT::Condition"
+ base class. The return value of this method, true or false, determines
+ whether the condition passes or not.
+
+ $self gives you access to the ticket object and transaction object via:
+
+ $self->TransactionObj
+ $self->TicketObj
+
+ These are your main hooks into the current ticket and transaction.
+
+ To check review status and the custom field value, we might add
+ something like this:
+
+ # Setting status to review?
+ return 0 unless $self->TransactionObj->Type eq 'Status'
+ and $self->TransactionObj->NewValue eq 'review';
+
+ # Is 'Special' set to Yes?
+ return 0 unless $self->TicketObj->FirstCustomFieldValue('Special') eq 'Yes';
+
+ return 1;
+
+ We've hardcoded "review" and "Special" here, but as with "StatusChange",
+ you could pass a value from the Parameters to Pass field. You can access
+ this value by calling the "Argument" method.
+
+ my $arg = $self->Argument;
+
+ Using passed arguments can make your conditions and actions more general
+ and potentially reusable.
+
+ Once the file is created, return to the RT web UI and create a new
+ condition, possibly by editing On Review Needed and clicking Copy
+ Condition. You can name it Special Review Needed and set the Condition
+ Module to SpecialReviewNeeded.
+
+ Custom Actions
+ Once you have the correct condition you can now think about the action.
+ You want to send email to a group of people, so to start you look at
+ some of the existing actions on the action display page at Admin >
+ Global > Actions (in RT 4.0, Tools > Global > Actions). You find Notify
+ AdminCcs, which might be close. Taking a quick look you see it has a
+ Name and Description, like conditions, and the module it calls is
+ "Notify", which can be found at "/opt/rt4/lib/RT/Action/Notify.pm".
+
+ The Parameter to Pass is AdminCc, and if you look at other notification
+ actions you'll see many use Notify and just pass a different ticket
+ role.
+
+ Your reviewers aren't always AdminCcs on tickets, so you'd rather send a
+ notification to a group. You can create this new action using the
+ existing action module "NotifyGroup". On the action list page, click
+ Create and add something like the following:
+
+ Name Notify Review Group
+ Description Send notification to the review group
+ Action Module NotifyGroup
+ Parameters to Pass Review Group
+
+ The 'Review Group' can be whatever your group name is. Then you can
+ build a template with some custom ticket information for reviewers and
+ set up a new scrip to send email to the review group whenever a ticket
+ status is set to review.
+
+ Custom Action Modules
+ As part of the request to add a condition to check for the 'Special'
+ custom field, we now want to route these special requests to the person
+ who handles them. This extra bit of functionality will require a module,
+ maybe called "SetOwner". Create the new file in:
+
+ /local/lib/RT/Action/SetOwner.pm
+
+ The base action code looks like this:
+
+ package RT::Action::SetOwner;
+
+ use strict;
+ use warnings;
+ use base 'RT::Action';
+
+ sub Prepare {
+ my $self = shift;
+
+ # Your code here
+
+ return 1; # True if Commit should run, false if not
+ }
+
+ sub Commit {
+ my $self = shift;
+
+ # Your code here
+
+ return 1; # True if action was successful
+ }
+
+ 1; # Don't forget module needs this
+
+ Actions have two methods you can override. The "Prepare" method provides
+ you with a chance to make sure the action should actually run. If
+ "Prepare" returns false, "Commit" will not run. You'll typically handle
+ this in your condition, in which case you can just omit "Prepare" from
+ your action. However, when you have a condition that covers a common
+ general case, but you want to check one extra criteria for a particular
+ action, the "Prepare" method can be helpful. In our example, you might
+ choose to keep just the On Review Needed condition and add the check for
+ the 'Special' custom field to the "Prepare" method.
+
+ "Commit" is where you do the actual work of the action. It should return
+ true on success. On failure, you can use "RT::Logger" to write errors or
+ debugging information to RTs logs so you can track down the problem.
+
+ In actions, $self gives you access to the transaction and ticket
+ objects, just like conditions, via:
+
+ $self->TransactionObj
+ $self->TicketObj
+
+ For our "SetOwner" action, we don't need "Prepare" and can add the
+ following to "Commit":
+
+ my $user = RT::User->new(RT->SystemUser);
+ my ($ret, $msg) = $user->Load($self->Argument);
+ RT::Logger->error('Unable to load user: '
+ . $self->Argument . " $msg") unless $ret;
+
+ $self->TicketObj->SetOwner($user->Id);
+ return 1;
+
+ The "Argument" method returns the value set for Parameters to Pass in
+ the action configuration. This example expects the argument to be the
+ username of an RT user.
+
+ Now you can create the new action in RT. Go to the action page, click
+ Create, and enter the following:
+
+ Name Set Owner
+ Description Set owner
+ Action Module SetOwner
+ Parameters to Pass reviewer_username
+
+ Click save and the new action will be available when creating scrips.
+
+ Note that actions you perform in scrips can themselves create new
+ transactions, as is the case with "SetOwner". When this action runs, the
+ set owner transaction will fire the default On Owner Change Notify Owner
+ scrip, if it is enabled.
+
+ADDITIONAL INFORMATION
+ When writing actions and conditions, it's helpful to look at the actions
+ and conditions provided with RT. You can find more information about the
+ methods available from ticket and transaction objects in your RT
+ distribution and on the "Best Practical website"
+ <http://docs.bestpractical.com>.
+
AUTHOR
sunnavy <sunnavy at bestpractical.com>
diff --git a/inc/Module/Install/RTx.pm b/inc/Module/Install/RTx.pm
index c9fe996..ac04c79 100644
--- a/inc/Module/Install/RTx.pm
+++ b/inc/Module/Install/RTx.pm
@@ -8,7 +8,7 @@ no warnings 'once';
use Module::Install::Base;
use base 'Module::Install::Base';
-our $VERSION = '0.31';
+our $VERSION = '0.32';
use FindBin;
use File::Glob ();
@@ -136,6 +136,7 @@ install ::
$has_etc{acl}++;
}
if ( -e 'etc/initialdata' ) { $has_etc{initialdata}++; }
+ if ( -d 'etc/upgrade/' ) { $has_etc{upgrade}++; }
$self->postamble("$postamble\n");
unless ( $subdirs{'lib'} ) {
@@ -164,6 +165,12 @@ install ::
.
$self->postamble("initdb ::\n$initdb\n");
$self->postamble("initialize-database ::\n$initdb\n");
+ if ($has_etc{upgrade}) {
+ print "To upgrade from a previous version of this extension, use 'make upgrade-database'\n";
+ my $upgradedb = qq|\t\$(NOECHO) \$(PERL) -Ilib -I"$local_lib_path" -I"$lib_path" -Minc::Module::Install -e"RTxInitDB(qw(upgrade \$(NAME) \$(VERSION)))"\n|;
+ $self->postamble("upgrade-database ::\n$upgradedb\n");
+ $self->postamble("upgradedb ::\n$upgradedb\n");
+ }
}
}
@@ -209,4 +216,4 @@ sub requires_rt {
__END__
-#line 329
+#line 336
diff --git a/inc/Module/Install/ReadmeFromPod.pm b/inc/Module/Install/ReadmeFromPod.pm
index 6a80818..b5e03c3 100644
--- a/inc/Module/Install/ReadmeFromPod.pm
+++ b/inc/Module/Install/ReadmeFromPod.pm
@@ -7,7 +7,7 @@ use warnings;
use base qw(Module::Install::Base);
use vars qw($VERSION);
-$VERSION = '0.20';
+$VERSION = '0.22';
sub readme_from {
my $self = shift;
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list