.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "RT::Extension::RepeatTicket 3pm" .TH RT::Extension::RepeatTicket 3pm "2016-09-26" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" RT::Extension::RepeatTicket \- Repeat tickets based on schedule .SH "DESCRIPTION" .IX Header "DESCRIPTION" The RepeatTicket extension allows you to set up recurring tickets so new tickets are automatically created based on a schedule. The new tickets are populated with the subject and initial content of the original ticket in the recurrence. .PP After you activate the plugin by adding it to your RT_SiteConfig.pm file, all tickets will have a Recurrence tab on the create and edit pages. To set up a repeating ticket, click the checkbox to \*(L"Enable Recurrence\*(R" and fill out the schedule for the new tickets. .PP New tickets are created when you initially save the recurrence, if new tickets are needed, and when your daily cron job runs the rt-repeat-ticket script. .SH "INSTALLATION" .IX Header "INSTALLATION" .ie n .IP """perl Makefile.PL""" 4 .el .IP "\f(CWperl Makefile.PL\fR" 4 .IX Item "perl Makefile.PL" .PD 0 .ie n .IP """make""" 4 .el .IP "\f(CWmake\fR" 4 .IX Item "make" .ie n .IP """make install""" 4 .el .IP "\f(CWmake install\fR" 4 .IX Item "make install" .PD May need root permissions .ie n .IP """make initdb""" 4 .el .IP "\f(CWmake initdb\fR" 4 .IX Item "make initdb" Only run this the first time you install this module. .Sp If you run this twice, you may end up with duplicate data in your database. .Sp If you are upgrading this module, check for upgrading instructions in case changes need to be made to your database. .IP "Edit your \fI/opt/rt4/etc/RT_SiteConfig.pm\fR" 4 .IX Item "Edit your /opt/rt4/etc/RT_SiteConfig.pm" If you are using \s-1RT 4.2\s0 or greater, add this line: .Sp .Vb 1 \& Plugin(\*(AqRT::Extension::RepeatTicket\*(Aq); .Ve .Sp For \s-1RT 4.0,\s0 add this line: .Sp .Vb 1 \& Set(@Plugins, qw(RT::Extension::RepeatTicket)); .Ve .Sp or add \f(CW\*(C`RT::Extension::RepeatTicket\*(C'\fR to your existing \f(CW@Plugins\fR line. .IP "Clear your mason cache" 4 .IX Item "Clear your mason cache" .Vb 1 \& rm \-rf /opt/rt4/var/mason_data/obj .Ve .IP "Add \fIbin/rt\-repeat\-ticket\fR to the daily cron job." 4 .IX Item "Add bin/rt-repeat-ticket to the daily cron job." .PD 0 .IP "Restart your webserver" 4 .IX Item "Restart your webserver" .PD .SH "CONFIGURATION" .IX Header "CONFIGURATION" .ie n .SS "$RepeatTicketCoexistentNumber" .el .SS "\f(CW$RepeatTicketCoexistentNumber\fP" .IX Subsection "$RepeatTicketCoexistentNumber" The \f(CW$RepeatTicketCoexistentNumber\fR determines how many tickets can be in an active status for a recurrence at any time. A value of 1 means one ticket at a time can be active. New tickets will not be created until the current active ticket is resolved or set to some other inactive status. You can also set this value per recurrence, overriding this config value. The extension default is 1 ticket. .ie n .SS "$RepeatTicketLeadTime" .el .SS "\f(CW$RepeatTicketLeadTime\fP" .IX Subsection "$RepeatTicketLeadTime" The \f(CW$RepeatTicketLeadTime\fR becomes the ticket Starts value and sets how far in advance of a ticket's Due date you want the ticket to be created. This essentially is how long you want to give people to work on the ticket. .PP For example, if you create a weekly recurrence scheduled on Mondays and set the lead time to 7 days, each Monday a ticket will be created with the Starts date set to that Monday and a Due date of the following Monday. .PP The value you set in RT_SiteConfig.pm becomes the system default, but you can set this value on each ticket as well. The extension default is 14 days. .ie n .SS "$RepeatTicketSubjectFormat" .el .SS "\f(CW$RepeatTicketSubjectFormat\fP" .IX Subsection "$RepeatTicketSubjectFormat" By default, repeated tickets will have the same subject as the original ticket. You can modify this subject by setting a format with the \&\f(CW$RepeatTicketSubjectFormat\fR option. This option accepts formats in the same form as formats for \s-1RT\s0 searches. The placeholders take values from the repeated ticket, not the original ticket, so you can use the format to help differentiate the subjects in repeated tickets. .PP For example, if you wanted to put the due date in the subject, you could set the format to: .PP .Vb 1 \& Set($RepeatTicketSubjectFormat, \*(Aq_\|_Due_\|_ _\|_Subject_\|_\*(Aq); .Ve .PP You'll want to use values that you don't expect to change since the subject won't change if the ticket value (e.g., Due) is changed. .PP Since this uses \s-1RT\s0 formats, you can create a custom format by creating a new \s-1RT\s0 ColumnMap. You can see the available formats by looking at the columns available in the Display Columns portlet on the \s-1RT\s0 ticket search page. .SS "rt-repeat-ticket" .IX Subsection "rt-repeat-ticket" The rt-repeat-ticket utility evaluates all of your repeating tickets and creates any new tickets that are needed. With no parameters, it runs for \*(L"today\*(R" each day. You can also pass a \-\-date value in the form YYYY-MM-DD to run the script for a specific day. .PP .Vb 1 \& bin/rt\-repeat\-ticket \-\-date 2012\-07\-25 .Ve .PP This can be handy if your cron job doesn't run for some reason and you want to make sure no repeating tickets have been missed. Just go back and run the script for the days you missed. You can also pass dates in the future which might be handy if you want to experiment with recurrences in a test environment. .SH "USAGE" .IX Header "USAGE" .SS "Initial Tickets" .IX Subsection "Initial Tickets" The initial ticket you create for a recurrence stores the schedule and other details for the recurrence. If you need to change the recurrence in the future, to make it more frequent or less frequent or anything else, make the changes on the original ticket. To help you find this initial ticket, which may have been resolved long ago, a custom field is created on each ticket in the recurrence with link called \*(L"Original Ticket.\*(R" .PP When setting up the recurrence, you can use the original ticket as an actual work ticket. When doing this, you'll need to set the Starts and Due dates when you create the ticket. Scheduled tickets created subsequently will set these values based on the recurrence. Resolving the original ticket does not cancel the recurrence. .SS "Start Value" .IX Subsection "Start Value" You can set a Start date for a new recurrence. If you don't, it defaults to the day you create the recurrence. .SS "Cancelling Recurrences" .IX Subsection "Cancelling Recurrences" You can cancel or end a recurrence in two ways: .IP "\(bu" 4 Go to the original ticket in the recurrence and uncheck the Enable Recurrence checkbox. .IP "\(bu" 4 Set ending conditions on the recurrence with either a set number of recurrences or an end date. .SS "Recursive Recurrences" .IX Subsection "Recursive Recurrences" Creating recurrences on recurrences isn't supported and may do strange things. .SH "FAQ" .IX Header "FAQ" .IP "I'm not seeing new recurrences. Why not?" 4 .IX Item "I'm not seeing new recurrences. Why not?" A few things to check: .RS 4 .IP "\(bu" 4 Do you have rt-repeat-tickets scheduled in cron? Is it running? .IP "\(bu" 4 Do you have previous tickets still in an active state? Resolve those tickets or increase the concurrent active tickets value. .IP "\(bu" 4 Is it the right day? Remember to subtract the lead time value to determine the day new tickets should be created. .IP "\(bu" 4 If you set a start date and another criteria like day of the week, the new ticket will be created on the first time that day of the week occurs after the start date you set (if the start date isn't on that day of the week). .RE .RS 4 .RE .SH "METHODS" .IX Header "METHODS" .ie n .SS "Run( RT::Attribute $attr, DateTime $checkday )" .el .SS "Run( RT::Attribute \f(CW$attr\fP, DateTime \f(CW$checkday\fP )" .IX Subsection "Run( RT::Attribute $attr, DateTime $checkday )" Repeat the ticket if \f(CW$checkday\fR meets the repeat settings. It also tries to repeat more to meet config \f(CW\*(C`RepeatTicketCoexistentNumber\*(C'\fR. .PP Return ids of new created tickets. .ie n .SS "Repeat ( RT::Attribute $attr, DateTime $checkday_1, DateTime $checkday_2, ... )" .el .SS "Repeat ( RT::Attribute \f(CW$attr\fP, DateTime \f(CW$checkday_1\fP, DateTime \f(CW$checkday_2\fP, ... )" .IX Subsection "Repeat ( RT::Attribute $attr, DateTime $checkday_1, DateTime $checkday_2, ... )" Repeat the ticket for the check days that meet repeat settings. .PP Return ids of new created tickets. .ie n .SS "MaybeRepeatMore ( RT::Attribute $attr )" .el .SS "MaybeRepeatMore ( RT::Attribute \f(CW$attr\fP )" .IX Subsection "MaybeRepeatMore ( RT::Attribute $attr )" Try to repeat more tickets to meet the coexistent ticket number. .PP Return ids of new created tickets. .ie n .SS "SetRepeatAttribute ( RT::Ticket $ticket, %args )" .el .SS "SetRepeatAttribute ( RT::Ticket \f(CW$ticket\fP, \f(CW%args\fP )" .IX Subsection "SetRepeatAttribute ( RT::Ticket $ticket, %args )" Save \f(CW%args\fR to the ticket's \*(L"RepeatTicketSettings\*(R" attribute. .PP Return ( RT::Attribute, \s-1UPDATE MESSAGE \s0) .SH "AUTHOR" .IX Header "AUTHOR" Best Practical Solutions, \s-1LLC\s0 .SH "BUGS" .IX Header "BUGS" All bugs should be reported via email to .PP .Vb 1 \& L .Ve .PP or via the web at .PP .Vb 1 \& L. .Ve .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" This software is Copyright (c) 2014 by Best Practical Solutions .PP This is free software, licensed under: .PP .Vb 1 \& The GNU General Public License, Version 2, June 1991 .Ve