Master to 4.2.8
[usit-rt.git] / docs / reminders.pod
1 =head1 Reminders
2
3 Reminders can be attached to a ticket to notify you take some action
4 on the ticket. Although there are fields like "Due" on tickets, some
5 tickets have dependencies or sub-tasks that need to be completed before you
6 can do the ticket. For a "Deploy New Certificate" ticket, for example, you may
7 need to remind yourself to order the new cert first.
8
9 Reminders are sort of mini-tickets and in fact they are implemented as
10 tickets themselves.
11
12 Each 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
28 Reminders are attached to tickets, so you create them in the Reminders section of
29 the ticket display. Once you give it an Owner and a Due date, the Reminder will
30 appear on the Owner's "At-a-glance" page by default.
31
32 If you don't see reminders, it may be turned off. Display of reminders can be
33 disabled with the C<$EnableReminders> flag in C<RT_SiteConfig.pm>. By default,
34 reminders are turned on.
35
36 =head1 Email Reminders
37
38 While seeing reminders in the web display is handy, you may also want to send out
39 email based on reminders that are due or are soon to be due. You can use the
40 C<rt-crontool> utility to schedule a job to send these emails for you.
41
42 To 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::Notify \
50                    --action-arg Owner,AlwaysNotifyActor \
51                    --transaction first \
52                    --template 'Reminder'
53
54 If you have modified the status values for reminders such that you have more
55 active 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"
57 reminders, but you could add that to the query as well.
58
59 The 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
61 example, single values can also be passed. The run frequency in your crontab
62 should be consistent with the time period you set to avoid missing reminders.
63
64 The template value refers to a Template in your RT system. You can use the
65 default Reminder template or create your own in Admin > Global > Templates >
66 Create. You can look at the default template for examples of the values
67 you can use to populate the email.