5.7.210. Bugzilla::Extension::RuleEngine

5.7.210.1. NAME

Bugzilla Rules Engine

5.7.210.2. DESCRIPTION

The Bugzilla Rules Engine is an extension for automating project workflow in Bugzilla. Users can create Rules that represent workflow steps. The Rules Engine ensures that the Rules are properly applied and provides a means of managing and tracking both the changes made to rules and the changes made to bugs by rules.

The Bugzilla Rules Engine provides the following features:

  1. A user-friendly Web GUI for creating and maintaining rules,
  2. A history of changes to each rule,
  3. A “kill-switch” feature to quickly disable the Rules Engine,
  4. Rule cloning,
  5. Access to details on rule activity,

All of these features can be accessed from the Bugzilla Rules Engine page.

The Rules Engine page contains a list of rules in tables organized by Rule Group. The details included in the table are the creation and modification times of the rule, when it was last triggered (hit) and how many bugs it has been actioned against.

By default, the page shows all active rules plus any inactive rules that have been modified within the past seven days. The controls at the top of the page can be used to filter the list by product, change the sort order, or display all rules (including inactive rules that have not been modified within the past seven days).

Each Rule Group has a setting for which Bugzila Groups have edit and view access to Rules in the Rule Group. Users in the Edit Groups for a Rule Group are referred to as Rule Editors.

To clone a Rule from Rule Group A to Rule Group B a user would require view access to Rule Group A and edit access to Rule Group B.

What are Rules

A Bugzilla Rule is the basic building block of workflow in the Rules Engine system. Each Rule defines a set of criteria and a set of actions. If a bug matches the criteria, then the actions are applied to it. It can be thought of in terms of “if a bug looks like this, then make these changes to it”.

Rule criteria include: classification, product, components, status, group, keywords, flags, and custom fields. Actions include setting fields (including custom fields), setting flags, adding comments and sending email notifications.

Each rule specifies a Run After value which defines the order that rules are applied when more than one rule is matched against a bug.

You can control when rules run by seting Rule runs, there are 3 pssible values.

  • On bug change
This rule when only run when a bug is changed.
  • Periodically
This rule will run when triggered by a cron job.
  • On bug change & periodically
This rule will run both when a bug is changed and when a cron job is run.

How does the Rules Engine work?

The Rules Engine works by matching rules against bugs and applying the changes from the rule to the bug. When a bug is updated, it is added to the end of the Rules Engine Job Queue. The Rules Engine takes each bug from the beginning of the queue and checks all the rules against it.

Bugs are added to the queue:

  1. when they are updated or created, or
  2. when they are manually added to the queue by a Rule Editor

Bugs can be manually added to the queue by a rule editor from the Rule Details page.

The Rules Engine continually checks for bugs in the job queue and processes them in turn. When a bug is retrieved from the queue, rules are applied using the following process:

  1. Each rule is checked in order until either a match is found or all the rules have been checked. If no matches are found then the process ends.
  2. The actions of the matched rule are applied to the bug.
  3. The matched rule is removed from the list.
  4. The remaining rules are then checked again starting with the one after the previously matched rule. When the end of the list is reached it continues checking from the beginning of the list until it either finds a new match or has checked every remaining rule in the list.
  5. If a match is found then the process returns to step two. If no matches are found then the process ends

A few things to note about rule processing:

  1. Every time a bug is processed from the job queue, each rule can only be matched to it once.
  2. Every time a rule matches a bug, the bug is updated immediately. Subsequent checks against each rule use the bug’s updated state, not the original.
  3. Rules are limited to the Rule Group selected on the Product admin screen. If a product hasn’t selected a Rule Group then no rules will be able to affect bugs in that product.

Note that it is not possible for more than one rule to have the same Run After value. If you create a rule with the same Run After value as another rule, then the new rule is slotted into the sequence in front of the old one by changing the value of the old rule to point to the new rule.

Using the Rules Engine

The following sections detail how to create and manage rules and use the other features of the Rules Engine.

Creating and Editing Rules

New rules can be created from the Rules Engine page by clicking on the Add new rule link at the bottom of the page and following the prompts. An existing rule can be edited by clicking the edit link for the rule on the Rules Engine page or the Rule Details page. The process for editing is a variation of that for creating a new rule.

Create a new rule

The following procedure shows the steps of creating a new rule.

Creating a rule requires at least one criteria item to be specified. If you do not then you receive an error message after the Actions page, “You may not search, or create saved searches, without any search terms”.

The last step of creating a new rule allows you to go back to any previous step and make changes. It is not recommended to try to use the back button to step back through the process. Wait until you reach the review page for making changes.

  1. Click the Add new rule link on the Rules Engine page. The Add new Bugzilla Rules Engine rule - step 1 page is displayed.
  2. Enter the required details and click Next.

The details that can be specified on this page are:

  1. Rule name
  2. Rule description
  3. Rule Group
  4. Run after
  5. Rule runs
  6. Classification
  7. Product

It is recommended to set Classification and Product to limit the scope of your rule to only those that it applies to. Multiple Classifications and Products can be selected here.

Note that by default Run After is set to Runs first.

  1. Specify the criteria for the rule and click Next.

For each criterion you require, select it from the Criterion menu and click Add. The selected criterion will be added to the list of details above with the appropriate form fields for you to specify details. These elements should be familiar to users of Bugzilla’s Advanced Search.

To remove criteria added by mistake, set the relevant field to either — or an empty value as appropriate.

  1. Specify the Actions for the rule and click Next.

For each action you require, select it from the Action menu and click Add. The selected Action is added to the list of Actions with the appropriate form fields for you to specify details.

To remove a actions added by mistake, set the relevant field to either Do not change, —, or an empty value as appropriate.

A rule with no actions will still trigger and an entry is made against the bug but with no changes.

  1. The last page displays a summary of the rule that you have specified thus far for you to review. It also provides a count of the bugs that would be affected by this rule and a button to view that list of bugs in a new window.

If you need to make changes you can return to any of the previous three steps using the buttons provided.

Once you are satisfied with the rule, check the I am happy with the above changes checkbox, optionally check the Play it safe checkbox, and click Submit changes.

At this point the rule is finalized and the Rule Created page is displayed. If you checked the Play it safe checkbox, the rule is disabled and the result of a test run is emailed to you. If you are satisfied with the result of the test run you can enable the rule. If not, you can edit the rule.

Editing a rule

Editing a rule is very similar to creating one. Click the edit link on the corresponding table row on the Rules Engine page or the edit link on the details page for the rule.

The procedure for editing the rule is the same as creating a new one with the following differences:

  1. Each page of the process is already populated with the existing data.
  2. There is no “Play it safe” option.

Managing Rule Groups

Rule Groups are a way to isolate teams and prducts from each other. Each group has a name, a description, view and edit groups, and a user to run the rules as.

Rule Groups are isolated from each other, allowing different teams to run isolated from each other. Only products that have selected to use a Rule Group can be affected by rules in a Group.

To manage Rule Groups, click on the Modify Rule Groups link on the Rules Engine page.

Add a Rule Group
  1. From the Rule Group page, click Add a new Rule Group.
  2. Specify the Rule Group name, description, edit group, etc.
  3. Click Save Changes.
Edit a Rule Group
  1. From the Rule Group page, click on the name of the rule you want to edit.
  2. Edit the fields as required.
  3. Click Save Changes.
Delete a Rule Group

There are two ways you can delete a Rule Group, but they can only be deleted if they contain no rules. In both cases you will be prompted to confirm that you want to delete the Rule Group before it is deleted.

  1. From the Rule Group page, click the Delete link for the corresponding Rule Group table row, or
  2. From the Edit Rule Group page, click the Delete link.

Viewing Rule Details

The Rule Details page displays information about the specified rule as well as providing quick access to several tasks. This page can be reached by clicking the Details link for the corresponding rule on the Rules Engine page.

In addition to the details of the rule (criteria and actions) the following information is displayed here:

  1. Number of Rule changes and a link to history page
  2. Creation date and time
  3. Last modification date and time
  4. Last hit
  5. Total runs
  6. Runs in the last 7 days
  7. Runs in the last 24 hours

From here you can perform the following actions:

  1. Edit the rule
  2. Clone the rule
  3. View the history page
  4. View the bugs actioned by this rule in the last 7 days or 24 hours
  5. View the bugs that are currently matched by this rule, and queue them in the Rules Engine
  6. Disable or enable the rule

Adding Bugs to the Rule Job Queue

Rules are normally processed when a bug is updated but there are some situations where you want rules applied to a set of bugs on demand. The Rules Engine allows bugs that match a specific rule to be added to the Job Queue.

The details screen shows the number of bugs which are currently matched by this rule. You can add these bugs to the Job Queue by clicking the Queue Bugs button.

The following points need to be understood before using this feature:

  1. The Rule Details page displays the number of bugs that currently match the rule, however the list of bugs is recalculated when you click the button. This means that the actual number of bugs might be different.
  2. The bugs that are added to the job queue are processed the same as any other bug in the queue. This means that all rules are checked against them.
  3. The bugs are queued immediately, but the time taken to process all of them will depend on the number of bugs, the number of bugs already in the queue and the number of rules that match them.

Review Rule History

You can view a complete history of changes made to each rule. You can see the definition of each rule for every change made, the person who made the change, and when each change was made.

Using the Kill Switch

The Kill Switch provides an emergency ability for any Rule Editor user to disable the execution of Rules. When the Kill Switch is active no rules are executed, and a notice is displayed at the top of the Rules Administration page. The Rules Engine can enable the Kill Switch itself if an irrecoverable error occurs while processing a rule against a bug. An example of this is a rule that tried to set a flag on a bug when the flag had been made inactive.

There can be multiple Kill Switch entries. While there is at least one Kill Switch entry, the Kill Switch is enabled. Any rule editor can disable the Kill Switch by removing Kill Switch entries. When all the entries have been removed the Rules Engine is enabled again. It is recommended that you do not remove other people’s Kill Switch entries unless you have confirmation to do so.

The Kill Switch page can be reached by clicking the Kill Switch link on the Rules Engine page.

The Kill Switch status is displayed at the top of this page.

To enable the Kill Switch, supply your reason in the box and click Add Kill Switch.

To disable the Kill Switch, check the checkbox of the reason you want to remove and click Disable Kill Switch. If there are no remaining reasons, then the Kill Switch is disabled.

The history of changes to the Kill Switch are displayed at the bottom of the page in Previous Changes.

Cloning Rules

You can clone a rule from the Rule Details screen. Rule cloning provides an easy way to create a new rule which is almost identical to another. This is especially useful if you have rules with many complex criteria or actions.

Cloning a rule is like creating a new rule, except the fields are already populated with the information from the original rule.

Cloning a Rule
  1. Go to the details page for the rule, and click Clone.
  2. Follow the same process as creating a new rule, updating the details as needed.

The name of the new rule is Clone of NAME OF ORIGINAL RULE. It is recommended that you change the name of your newly cloned rule to something appropriate.

See Create a new rule for details.

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