5.14. 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 (i.e. the 15th of the month at midnight) or at regular intervals (i.e. 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.
 | 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 a extended form of the whining interface. Features only available to members of the bz_canusewhineatothers group will be noted in the appropriate places. |
 | For whining to work, a special Perl script must be executed at regular intervals. More information on this is available in Section 2.3.4. |
| This section does not cover the whineatnews.pl script. See Section 2.3.3 for more information on The Whining Cron. |
5.14.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 Queries).
5.14.2. Whining Schedule
Each whining event is associated with zero or more schedules. A schedule is used to specify when the query (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.
| 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.
| 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. |
5.14.3. Whining Queries
Each whining event is associated with zero or more queries. A query is a saved search that is executed on the schedule specified (see above). You start out with zero queries attached to the event (which means that the event will not run, as there will never be any results to return). To add a query, press the "Add a new query" button.
The first field to examine in your new query is the Sort field. Queries are executed, and results returned, in the order specified by the Sort field. Queries with lower Sort values will run before queries with higher 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 Section 5.6).
| When running queries, the whining system acts as if you are the user executing the query. This means that the whining system will ignore bugs that match your query, but that you can not access. |
Once you have chosen the saved search to be executed, give the query a descriptive title. This title will appear in the email, above the results of the query. If you choose "One message per bug", the query title will appear at the top of each email that contains a bug matching your query.
Finally, decide if the results of the query should be sent in a single email, or if each bug should appear in its own email.
| Think carefully before checking the "One message per bug" box. If you create a query that matches thousands of bugs, you will receive thousands of emails! |
5.14.4. Saving Your Changes
Once you have defined at least one schedule, and created at least one query, go ahead and "Update/Commit". This will save your Event and make it available for immediate execution.
| 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. |