4.11. Whining
*************

Whining is a feature in Bugzilla that can regularly annoy users at
specified times.  Using this feature, users can execute saved searches
at specific times (e.g. the 15th of the month at midnight) or at
regular intervals (e.g. every 15 minutes on Sundays).  The results of
the searches are sent to the user, either as a single email or as one
email per bug, along with some descriptive text.

Warning:

  Throughout this section it will be assumed that all users are
  members of the bz_canusewhines group, membership in which is
  required in order to use the Whining system.  You can easily make
  all users members of the bz_canusewhines group by setting the User
  RegExp to ".*" (without the quotes).Also worth noting is the
  bz_canusewhineatothers group.  Members of this group can create
  whines for any user or group in Bugzilla using an extended form of
  the whining interface.  Features only available to members of the
  bz_canusewhineatothers group will be noted in the appropriate
  places.

Note:

  For whining to work, a special Perl script must be executed at
  regular intervals.  More information on this is available in
  Whining.

Note:

  This section does not cover the whineatnews.pl script. See Whining
  at Untriaged Bugs for more information on The Whining Cron.


4.11.1. The Event
=================

The whining system defines an "Event" as one or more queries being
executed at regular intervals, with the results of said queries (if
there are any) being emailed to the user.  Events are created by
clicking on the "Add new event" button.

Once a new event is created, the first thing to set is the "Email
subject line".  The contents of this field will be used in the subject
line of every email generated by this event.  In addition to setting a
subject, space is provided to enter some descriptive text that will be
included at the top of each message (to help you in understanding why
you received the email in the first place).

The next step is to specify when the Event is to be run (the Schedule)
and what searches are to be performed (the Searches).


4.11.2. Whining Schedule
========================

Each whining event is associated with zero or more schedules.  A
schedule is used to specify when the search (specified below) is to be
run.  A new event starts out with no schedules (which means it will
never run, as it is not scheduled to run).  To add a schedule, press
the "Add a new schedule" button.

Each schedule includes an interval, which you use to tell Bugzilla
when the event should be run.  An event can be run on certain days of
the week, certain days of the month, during weekdays (defined as
Monday through Friday), or every day.

Warning:

  Be careful if you set your event to run on the 29th, 30th, or 31st
  of the month, as your event may not run exactly when expected.  If
  you want your event to run on the last day of the month, select
  "Last day of the month" as the interval.

Once you have specified the day(s) on which the event is to be run,
you should now specify the time at which the event is to be run.  You
can have the event run at a certain hour on the specified day(s), or
every hour, half-hour, or quarter-hour on the specified day(s).

If a single schedule does not execute an event as many times as you
would want, you can create another schedule for the same event.  For
example, if you want to run an event on days whose numbers are
divisible by seven, you would need to add four schedules to the event,
setting the schedules to run on the 7th, 14th, 21st, and 28th (one day
per schedule) at whatever time (or times) you choose.

Note:

  If you are a member of the bz_canusewhineatothers group, then you
  will be presented with another option: "Mail to".  Using this you
  can control who will receive the emails generated by this event.
  You can choose to send the emails to a single user (identified by
  email address) or a single group (identified by group name).  To
  send to multiple users or groups, create a new schedule for each
  additional user/group.


4.11.3. Whining Searches
========================

Each whining event is associated with zero or more searches.  A search
is any saved search to be run as part of the specified schedule (see
above).  You start out without any searches associated with the event
(which means that the event will not run, as there will never be any
results to return).  To add a search, press the "Add a search" button.

The first field to examine in your newly added search is the Sort
field. Searches are run, and results included, in the order specified
by the Sort field.  Searches with smaller Sort values will run before
searches with bigger Sort values.

The next field to examine is the Search field.  This is where you
choose the actual search that is to be run.  Instead of defining
search parameters here, you are asked to choose from the list of saved
searches (the same list that appears at the bottom of every Bugzilla
page).  You are only allowed to choose from searches that you have
saved yourself (the default saved search, "My Bugs", is not a valid
choice).  If you do not have any saved searches, you can take this
opportunity to create one (see Bug Lists).

Note:

  When running searches, the whining system acts as if you are the
  user executing the search.  This means that the whining system will
  ignore bugs that match your search but that you cannot access.

Once you have chosen the saved search to be executed, give the search
a descriptive title.  This title will appear in the email, above the
results of the search.  If you choose "One message per bug", the
search title will appear at the top of each email that contains a bug
matching your search.

Finally, decide if the results of the search should be sent in a
single email, or if each bug should appear in its own email.

Warning:

  Think carefully before checking the "One message per bug" box.  If
  you create a search that matches thousands of bugs, you will receive
  thousands of emails!


4.11.4. Saving Your Changes
===========================

Once you have defined at least one schedule and created at least one
search, go ahead and "Update/Commit".  This will save your Event and
make it available for immediate execution.

Note:

  If you ever feel like deleting your event, you may do so using the
  "Remove Event" button in the upper-right corner of each Event.  You
  can also modify an existing event, so long as you "Update/Commit"
  after completing your modifications.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
