Upgrade to 4.2.2
[usit-rt.git] / docs / reminders.pod
CommitLineData
af59614d
MKG
1=head1 Reminders
2
3Reminders can be attached to a ticket to notify you take some action
4on the ticket. Although there are fields like "Due" on tickets, some
5tickets have dependencies or sub-tasks that need to be completed before you
6can do the ticket. For a "Deploy New Certificate" ticket, for example, you may
7need to remind yourself to order the new cert first.
8
9Reminders are sort of mini-tickets and in fact they are implemented as
10tickets themselves.
11
12Each Reminder has:
13
14=over
15
16=item * Subject
17
18=item * Owner
19
20=item * Due date
21
22=item * Status (new, open, resolved, ...)
23
24=back
25
26=head1 Creating a Reminder
27
28Reminders are attached to tickets, so you create them in the Reminders section of
29the ticket display. Once you give it an Owner and a Due date, the Reminder will
30appear on the Owner's "At-a-glance" page by default.
31
32If you don't see reminders, it may be turned off. Display of reminders can be
33disabled with the C<$EnableReminders> flag in C<RT_SiteConfig.pm>. By default,
34reminders are turned on.
35
36=head1 Email Reminders
37
38While seeing reminders in the web display is handy, you may also want to send out
39email based on reminders that are due or are soon to be due. You can use the
40C<rt-crontool> utility to schedule a job to send these emails for you.
41
42To schedule the reminders, add a line like the following to your RT crontab:
43
44 0 6 * * * root /opt/rt4/bin/rt-crontool \
45 --search RT::Search::FromSQL \
46 --search-arg 'Type = "reminder" and (Status = "open" or Status = "new")' \
47 --condition RT::Condition::BeforeDue \
48 --condition-arg 2d \
49 --action RT::Action::SendEmail \
50 --action-arg Owner,AlwaysNotifyActor \
51 --transaction first \
52 --template 'Reminder'
53
54If you have modified the status values for reminders such that you have more
55active statuses than "open" and "new" you should add them as part of your
56"FromSQL" query. You typically won't want to send out email on "resolved"
57reminders, but you could add that to the query as well.
58
59The argument to C<RT::Condition::BeforeDue> is an amount of time in the form
60"1d2h3m4s" for 1 day and 2 hours and 3 minutes and 4 seconds. As shown in the
61example, single values can also be passed. The run frequency in your crontab
62should be consistent with the time period you set to avoid missing reminders.
63
64The template value refers to a Template in your RT system. You can use the
65default Reminder template or create your own in Admin > Global > Templates >
66Create. You can look at the default template for examples of the values
67you can use to populate the email.