X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=rt%2Flib%2FRT%2FAction%2FCreateTickets.pm;fp=rt%2Flib%2FRT%2FAction%2FCreateTickets.pm;h=80308020f3fd11dd468ba67f5401ac2b90ee3030;hb=7588a4ac90a9b07c08a3107cd1107d773be1c991;hp=efd2bdaf6e1f9227a92229db94df15dfc4c2aa9a;hpb=98d2b25256055abb0dfcb9f586b434474fa97afd;p=freeside.git diff --git a/rt/lib/RT/Action/CreateTickets.pm b/rt/lib/RT/Action/CreateTickets.pm index efd2bdaf6..80308020f 100644 --- a/rt/lib/RT/Action/CreateTickets.pm +++ b/rt/lib/RT/Action/CreateTickets.pm @@ -2,7 +2,7 @@ # # COPYRIGHT: # -# This software is Copyright (c) 1996-2012 Best Practical Solutions, LLC +# This software is Copyright (c) 1996-2013 Best Practical Solutions, LLC # # # (Except where explicitly superseded by other copyright notices) @@ -56,14 +56,11 @@ use MIME::Entity; =head1 NAME - RT::Action::CreateTickets - -Create one or more tickets according to an externally supplied template. - +RT::Action::CreateTickets - Create one or more tickets according to an externally supplied template =head1 SYNOPSIS - ===Create-Ticket codereview + ===Create-Ticket: codereview Subject: Code review for {$Tickets{'TOP'}->Subject} Depended-On-By: TOP Content: Someone has created a ticket. you should review and approve it, @@ -72,18 +69,14 @@ Create one or more tickets according to an externally supplied template. =head1 DESCRIPTION +The CreateTickets ScripAction allows you to create automated workflows in RT, +creating new tickets in response to actions and conditions from other +tickets. -Using the "CreateTickets" ScripAction and mandatory dependencies, RT now has -the ability to model complex workflow. When a ticket is created in a queue -that has a "CreateTickets" scripaction, that ScripAction parses its "Template" - - - -=head2 FORMAT - -CreateTickets uses the template as a template for an ordered set of tickets -to create. The basic format is as follows: +=head2 Format +CreateTickets uses the RT template configured in the scrip as a template +for an ordered set of tickets to create. The basic format is as follows: ===Create-Ticket: identifier Param: Value @@ -98,19 +91,24 @@ to create. The basic format is as follows: Content: Blah ENDOFCONTENT - -Each ===Create-Ticket: section is evaluated as its own -Text::Template object, which means that you can embed snippets -of perl inside the Text::Template using {} delimiters, but that -such sections absolutely can not span a ===Create-Ticket boundary. - -After each ticket is created, it's stuffed into a hash called %Tickets -so as to be available during the creation of other tickets during the -same ScripAction, using the key 'create-identifier', where -C is the id you put after C<===Create-Ticket:>. The hash +As shown, you can put one or more C<===Create-Ticket:> sections in +a template. Each C<===Create-Ticket:> section is evaluated as its own +L object, which means that you can embed snippets +of Perl inside the L using C<{}> delimiters, but that +such sections absolutely can not span a C<===Create-Ticket:> boundary. + +Note that each C must come right after the C on the same +line. The C param can extend over multiple lines, but the text +of the first line must start right after C. Don't try to start +your C section with a newline. + +After each ticket is created, it's stuffed into a hash called C<%Tickets> +making it available during the creation of other tickets during the +same ScripAction. The hash key for each ticket is C, +where C<[identifier]> is the value you put after C<===Create-Ticket:>. The hash is prepopulated with the ticket which triggered the ScripAction as -$Tickets{'TOP'}; you can also access that ticket using the shorthand -TOP. +C<$Tickets{'TOP'}>. You can also access that ticket using the shorthand +C. A simple example: @@ -121,22 +119,20 @@ A simple example: so they can finish their work ENDOFCONTENT - - -A convoluted example +A convoluted example: ===Create-Ticket: approval { # Find out who the administrators of the group called "HR" # of which the creator of this ticket is a member my $name = "HR"; - + my $groups = RT::Groups->new(RT->SystemUser); $groups->LimitToUserDefinedGroups(); $groups->Limit(FIELD => "Name", OPERATOR => "=", VALUE => "$name"); $groups->WithMember($TransactionObj->CreatorObj->Id); - + my $groupid = $groups->First->Id; - + my $adminccs = RT::Users->new(RT->SystemUser); $adminccs->WhoHaveRight( Right => "AdminGroup", @@ -145,10 +141,10 @@ A convoluted example IncludeSuperusers => 0, IncludeSubgroupMembers => 0, ); - - my @admins; + + our @admins; while (my $admin = $adminccs->Next) { - push (@admins, $admin->EmailAddress); + push (@admins, $admin->EmailAddress); } } Queue: ___Approvals @@ -170,50 +166,51 @@ A convoluted example Refers-To: {$Tickets{"create-approval"}->Id} Queue: ___Approvals Content-Type: text/plain - Content: - Your approval is requred for this ticket, too. + Content: Your approval is requred for this ticket, too. ENDOFCONTENT - -=head2 Acceptable fields -A complete list of acceptable fields for this beastie: +As shown above, you can include a block with Perl code to set up some +values for the new tickets. If you want to access a variable in the +template section after the block, you must scope it with C rather +than C. Just as with other RT templates, you can also include +Perl code in the template sections using C<{}>. +=head2 Acceptable Fields + +A complete list of acceptable fields: * Queue => Name or id# of a queue Subject => A text string - ! Status => A valid status. defaults to 'new' + ! Status => A valid status. Defaults to 'new' Due => Dates can be specified in seconds since the epoch to be handled literally or in a semi-free textual format which RT will attempt to parse. - - - - Starts => - Started => - Resolved => - Owner => Username or id of an RT user who can and should own + Starts => + Started => + Resolved => + Owner => Username or id of an RT user who can and should own this ticket; forces the owner if necessary + Requestor => Email address - + Cc => Email address - + AdminCc => Email address + + Cc => Email address + + AdminCc => Email address + RequestorGroup => Group name + CcGroup => Group name + AdminCcGroup => Group name - TimeWorked => - TimeEstimated => - TimeLeft => - InitialPriority => - FinalPriority => - Type => - +! DependsOn => + TimeWorked => + TimeEstimated => + TimeLeft => + InitialPriority => + FinalPriority => + Type => + +! DependsOn => +! DependedOnBy => +! RefersTo => - +! ReferredToBy => + +! ReferredToBy => +! Members => - +! MemberOf => - Content => content. Can extend to multiple lines. Everything + +! MemberOf => + Content => Content. Can extend to multiple lines. Everything within a template after a Content: header is treated - as content until we hit a line containing only + as content until we hit a line containing only ENDOFCONTENT ContentType => the content-type of the Content field. Defaults to 'text/plain' @@ -225,31 +222,22 @@ A complete list of acceptable fields for this beastie: CF-name => custom field value CustomField-name => custom field value -Fields marked with an * are required. +Fields marked with an C<*> are required. -Fields marked with a + may have multiple values, simply +Fields marked with a C<+> may have multiple values, simply by repeating the fieldname on a new line with an additional value. -Fields marked with a ! are postponed to be processed after all -tickets in the same actions are created. Except for 'Status', those -field can also take a ticket name within the same action (i.e. -the identifiers after ===Create-Ticket), instead of raw Ticket ID +Fields marked with a C have processing postponed until after all +tickets in the same actions are created. Except for C, those +fields can also take a ticket name within the same action (i.e. +the identifiers after C<===Create-Ticket:>), instead of raw ticket ID numbers. -When parsed, field names are converted to lowercase and have -s stripped. -Refers-To, RefersTo, refersto, refers-to and r-e-f-er-s-tO will all -be treated as the same thing. - - +When parsed, field names are converted to lowercase and have hyphens stripped. +C, C, C, C and C will +all be treated as the same thing. - -=head1 AUTHOR - -Jesse Vincent - -=head1 SEE ALSO - -perl(1). +=head1 METHODS =cut @@ -537,12 +525,16 @@ sub UpdateByTemplate { return @results; } -=head2 Parse TEMPLATE_CONTENT, DEFAULT_QUEUE, DEFAULT_REQEUESTOR ACTIVE +=head2 Parse + +Takes (in order) template content, a default queue, a default requestor, and +active (a boolean flag). -Parse a template from TEMPLATE_CONTENT +Parses a template in the template content, defaulting queue and requestor if +unspecified in the template to the values provided as arguments. -If $active is set to true, then we'll use Text::Template to parse the templates, -allowing you to embed active perl in your templates. +If the active flag is true, then we'll use L to parse the +templates, allowing you to embed active Perl in your templates. =cut @@ -576,9 +568,9 @@ sub Parse { Parses mulitline templates. Things like: - ===Create-Ticket ... + ===Create-Ticket: ... -Takes the same arguments as Parse +Takes the same arguments as L. =cut @@ -834,9 +826,10 @@ sub ParseLines { } -=head2 _ParseXSVTemplate +=head2 _ParseXSVTemplate -Parses a tab or comma delimited template. Should only ever be called by Parse +Parses a tab or comma delimited template. Should only ever be called by +L. =cut