path: root/extensions/RuleEngine/Extension.pm

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

package Bugzilla::Extension::RuleEngine;

use strict;
use warnings;
use 5.10.1;

use base qw(Bugzilla::Extension);

use Date::Parse;
use Date::Format;

use Bugzilla::Bug;
use Bugzilla::Classification;
use Bugzilla::Constants;
use Bugzilla::Error;
use Bugzilla::Field;
use Bugzilla::FlagType;
use Bugzilla::Group;
use Bugzilla::Search;
use Bugzilla::Token;
use Bugzilla::Util;

use Bugzilla::Extension::RuleEngine::Util qw(message_2_array);
use Bugzilla::Extension::RuleEngine::FlagGroup;
use Bugzilla::Extension::RuleEngine::Job qw(_custom_search_match);
use Bugzilla::Extension::RuleEngine::Pages;
use Bugzilla::Extension::RuleEngine::Rule;
use Bugzilla::Extension::RuleEngine::RuleGroup;
use Bugzilla::Extension::RuleEngine::RuleState;

use List::MoreUtils qw(any apply);

our $VERSION = '0.01';

BEGIN {
  *Bugzilla::Product::rule_group         = \&_product_rule_group;
  *Bugzilla::Product::rule_group_obj     = \&_product_rule_group_obj;
  *Bugzilla::Product::set_rule_group     = \&_product_set_rule_group;
  *Bugzilla::_check_rule_group           = \&_check_rule_group;
  *Bugzilla::User::can_admin_any_product = \&_user_can_admin_any_product;
  *Bugzilla::User::can_see_rule          = \&_user_can_see_rule;
}

####################
## INITIALISATION ##
####################

sub db_schema_abstract_schema {
  my ($self, $args) = @_;

  my $schema = $args->{schema};

  # For recording whether the kill switch has been set
  $schema->{rh_rule_state} = {
    FIELDS => [
      id          => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      disabled_by => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}
      },
      when_disabled => {TYPE => 'DATETIME',   NOTNULL => 1},
      reason        => {TYPE => 'MEDIUMTEXT', NOTNULL => 1},
      enabled_by =>
        {TYPE => 'INT3', REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}},
      when_enabled => {TYPE => 'DATETIME'},
      rule_id      => {
        TYPE       => 'INT3',
        DEFAULT    => 'NULL',
        REFERENCES => {TABLE => 'rh_rule', COLUMN => 'id'}
      },
    ],
    INDEXES => [
      rh_rule_stat_when_disabled_idx => ['when_disabled'],
      rh_rule_stat_when_enabled_idx  => ['when_enabled'],
    ],
  };

  # For grouping rules, much like classification does to products
  $schema->{rh_rule_group} = {
    FIELDS => [
      id   => {TYPE => 'SMALLSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      name => {TYPE => 'varchar(64)', NOTNULL => 1},
      description => {TYPE => 'MEDIUMTEXT'},
      isactive    => {TYPE => 'BOOLEAN', NOTNULL => 1, DEFAULT => 'TRUE'},
      user_id     => {
        TYPE       => 'INT3',
        DEFAULT    => 'NULL',
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'},
        DELETE     => 'SET NULL'
      },
    ],
    INDEXES => [rh_rule_group_name_idx => {FIELDS => ['name'], TYPE => 'UNIQUE'},],
  };

  $schema->{rh_rule_group_maintainers} = {
    FIELDS => [
      id            => {TYPE => 'SMALLSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      rule_group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule_group', COLUMN => 'id', DELETE => 'CASCADE'}
      },
      user_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}
      },
    ],
  };

  # Groups that can edit this rule group
  $schema->{rh_rule_group_edit_groups} = {
    FIELDS => [
      id            => {TYPE => 'SMALLSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      rule_group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule_group', COLUMN => 'id', DELETE => 'CASCADE'}
      },
      group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'groups', COLUMN => 'id'}
      },
    ],
  };

  # Groups that can view this rule group
  $schema->{rh_rule_group_view_groups} = {
    FIELDS => [
      id            => {TYPE => 'SMALLSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      rule_group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule_group', COLUMN => 'id', DELETE => 'CASCADE'}
      },
      group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'groups', COLUMN => 'id'}
      },
    ],
  };

  # A single rule
  $schema->{rh_rule} = {
    FIELDS => [
      id   => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      name => {TYPE => 'varchar(64)',  NOTNULL => 1},
      description => {TYPE => 'MEDIUMTEXT'},
      sortkey     => {TYPE => 'INT2', NOTNULL => 1, DEFAULT => '0'},
      creation_ts => {TYPE => 'DATETIME', NOTNULL => 1},
      rule_group_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule_group', COLUMN => 'id'}
      },
      current_detail_id => {
        TYPE => 'INT3',

        # NULLable to prevent dependency issues
        REFERENCES => {TABLE => 'rh_rule_detail', COLUMN => 'id'}
      },
      is_periodic  => {TYPE => 'BOOLEAN', NOTNULL => 1},
      minor_update => {TYPE => 'BOOLEAN', NOTNULL => 1, DEFAULT => 'FALSE'},
    ],
    INDEXES => [
      rh_rule_current_detail_id_idx =>
        {FIELDS => ['current_detail_id'], TYPE => 'UNIQUE'},
    ],
  };

  # The details of a single rule
  $schema->{rh_rule_detail} = {
    FIELDS => [
      id      => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      rule_id => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule', COLUMN => 'id'}
      },
      creation_ts => {TYPE => 'DATETIME', NOTNULL => 1},
      creator_id  => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}
      },
      isactive    => {TYPE => 'BOOLEAN', NOTNULL => 1},
      match_json  => {TYPE => 'TEXT',    NOTNULL => 1},
      action_json => {TYPE => 'TEXT',    NOTNULL => 1},
    ],
    INDEXES => [rh_rule_detail_rule_id_idx => ['rule_id'],],
  };

  $schema->{rh_flag_group} = {
    FIELDS => [
      id   => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      name => {TYPE => 'varchar(64)',  NOTNULL => 1},
      description       => {TYPE => 'MEDIUMTEXT'},
      sortkey           => {TYPE => 'INT2', NOTNULL => 1, DEFAULT => '0'},
      current_detail_id => {
        TYPE => 'INT3',

        # NULLable to prevent dependency issues
        REFERENCES => {TABLE => 'rh_flag_group_detail', COLUMN => 'id'}
      },
    ],
    INDEXES => [
      rh_flag_group_current_detail_id_idx =>
        {FIELDS => ['current_detail_id'], TYPE => 'UNIQUE'},
    ],
  };

  # The details of a single flag group
  $schema->{rh_flag_group_detail} = {
    FIELDS => [
      id            => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      flag_group_id => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_flag_group', COLUMN => 'id'}
      },
      creation_ts => {TYPE => 'DATETIME', NOTNULL => 1},
      creator_id  => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}
      },
      theregexp => {TYPE => 'TEXT', NOTNULL => 1},    # String (a regexp)
    ],
    INDEXES => [rh_flag_group_detail_flag_group_id_idx => ['flag_group_id'],],
  };

  # Maps a rh_flag_group_detail with a flag type (many to many)
  $schema->{rh_flag_group_map} = {
    FIELDS => [
      flag_group_detail_id => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_flag_group_detail', COLUMN => 'id'}
      },
      flag_type_id => {
        TYPE       => 'INT2',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'flagtypes', COLUMN => 'id'}
      },
    ],
    INDEXES => [
      rh_flag_group_map_detail_idx => ['flag_group_detail_id'],
      rh_flag_group_map_type_idx   => ['flag_type_id'],
    ],
  };

  $schema->{rh_rule_owner} = {
    FIELDS => [
      id      => {TYPE => 'MEDIUMSERIAL', NOTNULL => 1, PRIMARYKEY => 1},
      rule_id => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'rh_rule', COLUMN => 'id'}
      },
      profile_id => {
        TYPE       => 'INT3',
        NOTNULL    => 1,
        REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'}
      },
    ],
    INDEXES => [rh_rule_owner_idx => ['rule_id'],],
  };

  return;
}

sub install_update_db {
  my ($self, $args) = @_;
  my $dbh = Bugzilla->dbh;

  # Create the field if it does not exist
  if (!Bugzilla::Field->new({name => 'rh_rule'})) {
    Bugzilla::Field->create({
      name => 'rh_rule', description => 'Rules Engine Rule', mailhead => 0,
    });
  }

  $dbh->bz_add_column('rh_rule', 'is_periodic',
    {TYPE => 'BOOLEAN', NOTNULL => 1}, 0);

  $dbh->bz_add_column('rh_rule', 'minor_update',
    {TYPE => 'BOOLEAN', NOTNULL => 1, DEFAULT => 'FALSE'}, 0);

  $dbh->bz_add_column(
    'rh_rule_state',
    'rule_id',
    {
      TYPE       => 'INT3',
      DEFAULT    => 'NULL',
      REFERENCES => {TABLE => 'rh_rule', COLUMN => 'id'}
    }
  );

  $dbh->bz_add_column(
    'products',
    'rule_group',
    {
      TYPE       => 'INT3',
      DEFAULT    => 'NULL',
      REFERENCES => {TABLE => 'rh_rule_group', COLUMN => 'id', DELETE => 'SET NULL'}
    }
  );

  $dbh->bz_add_column(
    'rh_rule_group',
    'user_id',
    {
      TYPE       => 'INT3',
      DEFAULT    => 'NULL',
      REFERENCES => {TABLE => 'profiles', COLUMN => 'userid'},
      DELETE     => 'SET NULL'
    }
  );

  $dbh->bz_drop_column('rh_rule_group', 'sortkey');

  return;
}

###########
## PAGES ##
###########

sub template_before_process {
  my ($self, $args) = @_;
  my $file = $args->{'file'};
  my $vars = $args->{vars};

  my $user;

  # For the edit flag type page, we want to show a warning if a rule uses
  # that flag type
  if ($file eq 'admin/flag-type/edit.html.tmpl') {
    $user = Bugzilla->login(LOGIN_OPTIONAL);
    _flag_rule_check($args);
  }
  elsif ($file eq 'admin/products/edit.html.tmpl') {
    $user = Bugzilla->login(LOGIN_OPTIONAL);
    @{$vars->{rule_group_list}}
      = Bugzilla::Extension::RuleEngine::RuleGroup->all_user_can_edit();
  }
  elsif ($file eq 'global/header.html.tmpl') {
    $user = Bugzilla->user;
    if ($user) {
      my @rule_group_list
        = Bugzilla::Extension::RuleEngine::RuleGroup->all_user_can_edit($user);

      if (@rule_group_list) {

        # If the kill switch is on, let's note that
        $vars->{disabled_count}
          = Bugzilla::Extension::RuleEngine::RuleState->disabled_count;

        if ($vars->{disabled_count}) {
          message_2_array($vars);

          # Display message about the kill switch being set
          push(@{$vars->{message}}, ['rules_disabled', {}]);
        }

        foreach my $rule_group (@rule_group_list) {
          if ($rule_group->disabled_count) {
            message_2_array($vars);

            push(
              @{$vars->{message}},
              [
                'group_rules_disabled',
                {rule_group_name => $rule_group->name, ks_count => $rule_group->disabled_count}
              ]
            );
          }
        }
      }
    }
  }

  return;
}

sub _flag_rule_check {
  my $args = shift;
  my $vars = $args->{vars};
  my $type = $vars->{type};

  # If we are creating a flag type or editing an attachment flag type,
  # then obviously no rules use it
  return if $vars->{action} eq 'insert' || !$type || $type->{target_type} ne 'b';

  # Get all rules
  my $type_name = $type->name;
  my @all_rules = Bugzilla::Extension::RuleEngine::Rule->get_all;
  my @match_rules = ();    # Array of hashes (keys: id, name, use => [])

  # Product and component inclusions and exclusions
  my ($inclusions) = Bugzilla::FlagType::get_clusions($type->id, 'in');

  foreach my $rule (@all_rules) {
    my @use = ();

    # Is the flag type used as part of the match criteria?
    if (my $match = $rule->current->match->{flag_types}) {
      if (any { $_->{name} eq $type_name } @$match) {
        push @use, 'match';
      }
    }

    # Take the list of products that this rule uses.
    # Take the list of products that the flag is applicable to.
    #
    # If any of the lists contain the same elements, then there is
    # a match and we continue checking flags.

    my $rule_products = $rule->current->match->{product}->{values};
    my $flag_products
      = [map { my ($product) = split(/:/, $_); $product } keys %$inclusions];

    my $product_match = 0;

  OUTER: foreach my $rule_product (@$rule_products) {
      foreach my $flag_product (@$flag_products) {
        if ($flag_product eq $rule_product) {
          $product_match = 1;
          last OUTER;
        }
      }
    }

    # If the product does not match, then we can stop processing here.
    next unless $product_match;

    # Is the flag type used as part of a custom search?
    if (my $custom = $rule->current->match->{custom}) {
      my @flags = map { $type_name . $_ } qw(X ? + -);
      foreach my $row (@$custom) {

        # We only check when the field is flagtype and the op is not null/notnull
        next unless $row->{field} eq 'flagtypes.name';
        next if $row->{op} eq 'isnull' || $row->{op} eq 'isnotnull';

        # See if this flag matches. Note: We don't worry about negation
        # because that has special meaning for flags.
        my $op = $row->{op};
        $op = substr($op, 3) if substr($op, 0, 3) eq 'not';

        my $found
          = _custom_search_match({
          op => $op, value => $row->{value}, is_number => 0, values => \@flags,
          });

        if (not defined $found) {

          # Any error occurred
          ThrowUserError('search_field_operator_invalid',
            {field => 'flagtypes.name', operator => $op});
        }
        elsif ($found) {
          push @use, 'custom field';
          last;
        }
      }
    }

    # Is the flag type used as an action?
    if (my $action = $rule->current->action->{flag_types}) {
      if (any { $_ eq $type_name } keys %$action) {
        push @use, 'action';
      }
    }

    if (scalar(@use)) {

      # If it is used as either of the above, then record it.
      push @use, $rule->current->is_active ? 'active' : 'inactive';
      push @match_rules, {id => $rule->id, name => $rule->name, use => \@use};
    }
  }

  if (scalar @match_rules) {

    # The flag type is used by at least one rule, show a warning.
    $vars->{message}       = 'rh_rule_flag_warn';
    $vars->{rh_rule_match} = \@match_rules;
  }

  return;
}


# Throw an error if the user is not in the edit rule group.
sub _require_edit {
  my $user = shift;

  unless ($user->can_admin_any_product()) {
    ThrowUserError("auth_failure",
      {group => 'editcomponents', action => 'edit', object => 'rule_engine'});
  }

  return;
}

sub page_before_template {
  my ($self, $args) = @_;

  my $page = $args->{page_id};

  # If we aren't viewing a BRE page, we don't need to do anything
  return unless substr($page, 0, 10) eq 'ruleengine';

  # Make sure we have permissions to view the pages
  my $user = Bugzilla->login(LOGIN_REQUIRED);

  my $vars = $args->{vars};
  $vars->{doc_section} = 'integrating/api/Bugzilla/Extension/RuleEngine.html';

  if ($page eq 'ruleengine/index.html') {
    _page_index($vars);
  }
  elsif ($page eq 'ruleengine/edit.html') {
    _page_rule_edit($vars);
  }
  elsif ($page eq 'ruleengine/killswitch.html') {
    _page_kill_switch($vars);
  }
  elsif ($page eq 'ruleengine/group/list.html') {
    _page_group_list($vars);
  }
  elsif ($page eq 'ruleengine/group/edit.html') {
    _page_group_edit($vars);
  }
  elsif ($page eq 'ruleengine/group/del.html') {
    _page_group_confirm_delete($vars);
  }
  elsif ($page eq 'ruleengine/flaggroup/list.html') {
    _page_flaggroup_list($vars);
  }
  elsif ($page eq 'ruleengine/flaggroup/edit.html') {
    _page_flaggroup_edit($vars);
  }
  elsif ($page eq 'ruleengine/flaggroup/history.html') {
    _page_flaggroup_history($vars);
  }
  elsif ($page eq 'ruleengine/details/index.html') {
    _page_details($vars);
  }
  elsif ($page eq 'ruleengine/details/change.html') {
    _page_details_change($vars);
  }
  elsif ($page eq 'ruleengine/details/history.html') {
    _page_details_history($vars);
  }

  return;
}

sub _page_index {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);

  # If the kill switch is on, let's note that
  $vars->{disabled_count}
    = Bugzilla::Extension::RuleEngine::RuleState->disabled_count;

  my $rule_group;
  my $prod;
  my %opts = (inactive => 1, isactive => ($input->{inactive} ? 0 : 1),);

  $prod = Bugzilla::Product->check({id => $input->{product}})
    if ($input->{product});

  if ($input->{product}) {
    $prod = Bugzilla::Product->check({id => $input->{product}});

    $rule_group         = $prod->rule_group_obj();
    $opts{product}      = $prod->name;
    $vars->{product_id} = $prod->id;
  }
  elsif ($input->{rule_group_id}) {
    $rule_group
      = Bugzilla::Extension::RuleEngine::RuleGroup->new($input->{rule_group_id});
  }

  if ($rule_group) {
    ThrowUserError('cannot_view_rule_group')
      unless ($rule_group->user_can_view($user));

    $opts{rule_group_id} = $rule_group->id();
    my $rules = Bugzilla::Extension::RuleEngine::Rule->match_rules(\%opts);

    $vars->{rules}         = $rules;
    $vars->{rule_group_id} = $rule_group->id;
    $vars->{rule_group}           = $rule_group;
    $vars->{group_disabled_count} = $rule_group->disabled_count;
  }

  @{$vars->{rule_group_list}}
    = Bugzilla::Extension::RuleEngine::RuleGroup->all_user_can_view($user);

  return;
}

sub _page_kill_switch {
  my ($vars) = @_;
  my $input  = Bugzilla->input_params;
  my $token  = $input->{token};
  my $action = $input->{action} || '';

  my $user = Bugzilla->login(LOGIN_REQUIRED);

  if ($action eq 'remove') {
    check_token_data($token, 'kill_switch');
    my @state_ids
      = apply {s/^remove_(\d+)$/$1/} grep {/^remove_(\d+)$/} keys %$input;
    foreach my $state_id (@state_ids) {
      my $rule_state = Bugzilla::Extension::RuleEngine::RuleState->new($state_id);

      if ($rule_state->rule) {
        ThrowUserError('cannot_edit_rule_group')
          unless ($rule_state->rule->rule_group->user_can_edit($user));
      }
      else {
        _require_edit($user);
      }

      $rule_state->enable();
    }
    $vars->{message} = 'rule_state_removed';
    $vars->{cnt}     = scalar(@state_ids);
    delete_token($token);
  }
  elsif ($action eq 'add') {
    check_token_data($token, 'kill_switch');
    my %args = (disabled_by => Bugzilla->user->id, reason => $input->{reason},);

    if ($input->{rule_id}) {
      $args{rule_id} = $input->{rule_id};
      my $rule
        = Bugzilla::Extension::RuleEngine::Rule->check({id => $input->{rule_id}});
      ThrowUserError('cannot_edit_rule_group')
        unless ($rule->rule_group->user_can_edit($user));
    }
    else {
      _require_edit($user);
    }

    Bugzilla::Extension::RuleEngine::RuleState->create(\%args);

    $vars->{message} = 'rule_state_added';
    delete_token($token);
  }

  # Let's get some lists, after we processed the action
  $vars->{token}       = issue_session_token('kill_switch');
  $vars->{active_list} = Bugzilla::Extension::RuleEngine::RuleState->active_list;
  $vars->{previous_list}
    = Bugzilla::Extension::RuleEngine::RuleState->previous_list;

  my @rule_group_list
    = Bugzilla::Extension::RuleEngine::RuleGroup->all_user_can_edit($user);

  my @rules;
  foreach my $rule_group (@rule_group_list) {

    # Get a list of rules for the current product and active status
    my $rules
      = Bugzilla::Extension::RuleEngine::Rule->match_rules({
      inactive => 1, isactive => 1, rule_group_id => $rule_group->id,
      });

    push(@rules, @$rules);
  }

  $vars->{rule_by_groups}
    = Bugzilla::Extension::RuleEngine::RuleGroup->sort_rules_by_group(\@rules);

  return;
}

sub _page_group_list {
  my ($vars) = @_;
  my $cgi    = Bugzilla->cgi;
  my $input  = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);

  # often used variables
  my $token  = $input->{'token'};
  my $action = $input->{'action'};
  my $id     = $input->{'rule_group_id'};

  if ($action eq 'add') {
    check_token_data($token, 'add_rule_group');

    my $name        = trim($cgi->param('name')        || '');
    my $description = trim($cgi->param('description') || '');

    my $rule_group
      = Bugzilla::Extension::RuleEngine::RuleGroup->create({
      name => $name, description => $description,
      });

    delete_token($token);

    $vars->{message}    = 'rule_group_created';
    $vars->{rule_group} = $rule_group;
  }

  elsif ($action eq 'delete') {
    $id || ThrowCodeError('param_required', {param => 'rule_group_id'});

    my $rule_group = Bugzilla::Extension::RuleEngine::RuleGroup->new($id);
    ThrowUserError('cannot_edit_rule_group')
      unless ($rule_group->user_can_edit($user));

    if ($rule_group->rule_count) {
      ThrowUserError('cannot_delete_rule_group');
    }

    check_token_data($token, 'delete_rule_group');
    $rule_group->remove_from_db();
    delete_token($token);

    $vars->{rule_group} = $rule_group;
    $vars->{message}    = 'rule_group_deleted';
  }

  elsif ($action eq 'update') {
    $id || ThrowCodeError('param_required', {param => 'rule_group_id'});

    my $rule_group = Bugzilla::Extension::RuleEngine::RuleGroup->new($id);

    ThrowUserError('cannot_edit_rule_group')
      unless ($rule_group->user_can_edit($user));

    check_token_data($token, 'edit_rule_group');

    my $name        = trim($cgi->param('name')        || '');
    my $description = trim($cgi->param('description') || '');
    my $isactive    = $cgi->param('isactive');
    my $user_id     = trim($cgi->param('user_id') || 0);
    my @maintainers = $cgi->param('maintainers');

    $rule_group->set_name($name);
    $rule_group->set_description($description);
    $rule_group->set_is_active($isactive);
    $rule_group->set_user_id($user_id);
    $rule_group->set_maintainers(\@maintainers);

    my @view_groups = $cgi->param('view_groups');
    my @edit_groups = $cgi->param('edit_groups');

    my @view_group_obj = map { Bugzilla::Group->check({name => $_}) } @view_groups;
    my @edit_group_obj = map { Bugzilla::Group->check({name => $_}) } @edit_groups;

    if (scalar @view_group_obj) {
      $rule_group->set_view_groups(\@view_group_obj);
    }
    if (scalar @edit_group_obj) {
      $rule_group->set_edit_groups(\@edit_group_obj);
    }

    my $changes = $rule_group->update();

    delete_token($token);

    $vars->{rule_group} = $rule_group;
    $vars->{message}    = 'rule_group_updated';
  }

  # Get a list of all the rule groups the user can edit
  @{$vars->{rule_group_list}}
    = Bugzilla::Extension::RuleEngine::RuleGroup->all_user_can_edit($user);

  return;
}

sub _page_group_edit {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);

  my $action = $input->{'action'} || '';

  if ($action eq 'new') {
    ThrowUserError('cannot_create_rule_groups')
      unless ($user->can_admin_any_product());

    $vars->{action} = 'add';
    $vars->{token}  = issue_session_token('add_rule_group');
  }
  else {
    my $id = $input->{'rule_group_id'};
    $id || ThrowCodeError('param_required', {param => 'rule_group_id'});

    $vars->{action}     = 'update';
    $vars->{rule_group} = Bugzilla::Extension::RuleEngine::RuleGroup->new($id);
    ThrowUserError('cannot_edit_rule_group')
      unless ($vars->{rule_group}->user_can_edit($user));

    $vars->{token} = issue_session_token('edit_rule_group');
  }

  @{$vars->{groups}} = Bugzilla::Group->get_all();

  return;
}

sub _page_group_confirm_delete {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);

  my $id = $input->{'rule_group_id'};
  $id || ThrowCodeError('param_required', {param => 'rule_group_id'});

  $vars->{rule_group} = Bugzilla::Extension::RuleEngine::RuleGroup->new($id);
  ThrowUserError('cannot_edit_rule_group')
    unless ($vars->{rule_group}->user_can_edit($user));

  $vars->{token} = issue_session_token('delete_rule_group');

  return;
}

sub _page_flaggroup_list {
  my ($vars) = @_;
  my $cgi    = Bugzilla->cgi;
  my $dbh    = Bugzilla->dbh;
  my $input  = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);
  ThrowUserError('cannot_access_flag_groups')
    unless ($user->can_admin_any_product());

  # often used variables
  my $token  = $input->{'token'};
  my $action = $input->{'action'};
  my $id     = $input->{'flag_group_id'};

  if ($action eq 'add') {
    check_token_data($token, 'add_flag_group');

    my $name        = trim($cgi->param('name')        || '');
    my $description = trim($cgi->param('description') || '');
    my $sortkey     = trim($cgi->param('sortkey')     || 0);
    my $regexp      = trim($cgi->param('regexp')      || '');
    my @flag_ids    = $cgi->param('flag_ids');

    detaint_natural($_) for @flag_ids;
    $dbh->bz_start_transaction;
    my $flag_group
      = Bugzilla::Extension::RuleEngine::FlagGroup->create({
      name => $name, description => $description, sortkey => $sortkey,
      });

    # Create the new detail record
    my $flag_group_detail
      = Bugzilla::Extension::RuleEngine::FlagGroupDetail->create({
      flag_group_id => $flag_group->id,
      theregexp     => $regexp,
      flag_ids      => \@flag_ids,
      });

    $flag_group->set_current_detail_id($flag_group_detail->id);
    $flag_group->update();
    $dbh->bz_commit_transaction;

    delete_token($token);

    $vars->{message}    = 'flag_group_created';
    $vars->{flag_group} = $flag_group;
  }
  elsif ($action eq 'update') {
    $id || ThrowCodeError('param_required', {param => 'flag_group_id'});

    my $flag_group = Bugzilla::Extension::RuleEngine::FlagGroup->new($id);

    check_token_data($token, 'edit_flag_group');

    my $name        = trim($cgi->param('name')        || '');
    my $description = trim($cgi->param('description') || '');
    my $sortkey     = trim($cgi->param('sortkey')     || 0);
    my $regexp      = trim($cgi->param('regexp')      || '');
    my @flag_ids    = $cgi->param('flag_ids');
    detaint_natural($_) for @flag_ids;

    # Create the new detail record
    $dbh->bz_start_transaction;
    my $flag_group_detail
      = Bugzilla::Extension::RuleEngine::FlagGroupDetail->create({
      flag_group_id => $flag_group->id,
      theregexp     => $regexp,
      flag_ids      => \@flag_ids,
      });

    # Update everything else
    $flag_group->set_name($name);
    $flag_group->set_description($description);
    $flag_group->set_sortkey($sortkey);
    $flag_group->set_current_detail_id($flag_group_detail->id);
    my $changes = $flag_group->update();
    $dbh->bz_commit_transaction;

    delete_token($token);

    $vars->{flag_group} = $flag_group;
    $vars->{message}    = 'flag_group_updated';
  }

  # Get a list of all the flag groups
  @{$vars->{flag_group_list}}
    = Bugzilla::Extension::RuleEngine::FlagGroup->get_all;

  return;
}

sub _page_flaggroup_edit {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $action = $input->{'action'} || '';

  my $user = Bugzilla->login(LOGIN_REQUIRED);
  ThrowUserError('cannot_access_flag_groups')
    unless ($user->can_admin_any_product());

  if ($action eq 'new') {
    $vars->{action} = 'add';
    $vars->{token}  = issue_session_token('add_flag_group');
  }
  else {
    my $id = $input->{'flag_group_id'};
    $id || ThrowCodeError('param_required', {param => 'flag_group_id'});

    $vars->{action}     = 'update';
    $vars->{flag_group} = Bugzilla::Extension::RuleEngine::FlagGroup->new($id);
    $vars->{token}      = issue_session_token('edit_flag_group');
  }

  $vars->{flag_type_list} = [Bugzilla::FlagType->get_all];

  return;
}

sub _page_flaggroup_history {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $user = Bugzilla->login(LOGIN_REQUIRED);
  ThrowUserError('cannot_access_flag_groups')
    unless ($user->can_admin_any_product());

  my $id = $input->{'flag_group_id'};
  $id || ThrowCodeError('param_required', {param => 'flag_group_id'});

  $vars->{flag_group} = Bugzilla::Extension::RuleEngine::FlagGroup->new($id);

  return;
}

sub _page_details {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  # Unlike every other page, this takes rule_name and not rule_id. This
  # makes it possible to provide linkification in the history page
  my $name = $input->{'rule_name'};
  $name || ThrowCodeError('param_required', {param => 'rule_name'});

  my $rule = $vars->{rule}
    = Bugzilla::Extension::RuleEngine::Rule->new({name => $name});

  ThrowUserError('rule_does_not_exist', {rule_name => $name}) unless ($rule);

  my $user = Bugzilla->login(LOGIN_REQUIRED);
  ThrowUserError('cannot_view_rule_group')
    unless ($rule->rule_group->user_can_view($user));

  # Count bugs
  $vars->{json}      = $rule->current;
  $vars->{bug_ids}   = _get_matching_bugs_for_rule($rule->current->match, $rule);
  $vars->{bug_count} = scalar(@{$vars->{bug_ids}});
  $vars->{token}     = issue_session_token('rule_details');

  $vars->{flag_group_map} = {};
  foreach my $flag_group (Bugzilla::Extension::RuleEngine::FlagGroup->get_all) {
    $vars->{flag_group_map}{$flag_group->id} = $flag_group->name;
  }

  return;
}

sub _page_details_history {
  my ($vars) = @_;
  my $input = Bugzilla->input_params;

  my $id = $input->{'rule_id'};
  $id || ThrowCodeError('param_required', {param => 'rule_id'});

  $vars->{rule} = Bugzilla::Extension::RuleEngine::Rule->new($id);

  my $user = Bugzilla->login(LOGIN_REQUIRED);
  ThrowUserError('cannot_view_rule_group')
    unless ($vars->{rule}->rule_group->user_can_view($user));

  $vars->{flag_group_map} = {};
  foreach my $flag_group (Bugzilla::Extension::RuleEngine::FlagGroup->get_all) {
    $vars->{flag_group_map}{$flag_group->id} = $flag_group->name;
  }

  return;
}

sub _page_details_change {
  my ($vars)  = @_;
  my $input   = Bugzilla->input_params;
  my @changes = ();

  my $id = $input->{'rule_id'};
  $id || ThrowCodeError('param_required', {param => 'rule_id'});

  my $token = $input->{'token'};
  check_token_data($token, 'rule_details');
  my $rule = $vars->{rule} = Bugzilla::Extension::RuleEngine::Rule->new($id);

  # It would be crazy to add bugs while a rule is inactive
  if ($input->{add_bugs} && !$input->{is_active}) {
    ThrowUserError('bre_cannot_add_bugs_while_inactive');
  }

  if ($rule->current->is_active xor $input->{is_active}) {

    # The user wants to the change the active state of the rule
    $rule->set_active($input->{is_active});

    # Reload the rule (since ->current is no longer correct)
    $rule = $vars->{rule} = Bugzilla::Extension::RuleEngine::Rule->new($id);
    $vars->{active_change} = 1;
  }

  if ($input->{add_bugs}) {

    # The user wants to add bugs that match this rule to the job queue
    # Let's start by counting the bugs
    my $bug_ids = _get_matching_bugs_for_rule($rule->current->match, $rule);

    # Add the bug to the queue. Although we could add a single job with all
    # the bugs, this wouldn't be ideal when the Rules Engine kills itself.
    foreach my $bug_id (@$bug_ids) {
      Bugzilla->job_queue->insert(
        'rule_engine',
        {
          action      => 'update',
          delta_ts    => 1,           # Always going to be true
          do_periodic => 1,
          bug_ids     => [$bug_id],
          run_after   => time + 5,
        }
      );
    }

    $vars->{bug_count} = scalar(@$bug_ids);
  }
  delete_token($token);

  return;
}

###############
## BUG HOOKS ##
###############

sub bug_create_after_mail {
  my ($self, $args) = @_;

  my $bug = $args->{'bug'};

  # Add the bug to the queue, if product is using BRE
  if ($bug->product_obj->rule_group) {
    Bugzilla->job_queue->insert(
      'rule_engine',
      {
        action    => 'create',
        delta_ts  => $bug->creation_ts,
        bug_ids   => [$bug->id],
        run_after => time + 5,
      }
    );
  }

  return;
}

sub bug_end_of_update {
  my ($self, $args) = @_;

  my $bug = $args->{bug};

  if (defined($bug->{_rh_rule})) {
    $self->bug_end_of_process($args);
  }

  return;
}

sub bug_end_of_process {
  my ($self, $args) = @_;
  my $dbh  = Bugzilla->dbh;
  my $user = Bugzilla->user;

  my ($bug, $old_bug, $timestamp, $changes)
    = @$args{qw(bug old_bug timestamp changes)};

  if (my $rule = delete $bug->{_rh_rule}) {

    # Log the change, if a change was made
    if (scalar(keys %$changes) || $bug->{added_comments}) {
      LogActivityEntry($bug->id, 'rh_rule', '', $rule->id, $user->id, $timestamp);

      # Add it to the current changes
      $changes->{rh_rule} = ['', $rule->id];
    }
  }
  else {
    # Add the bug to the queue. If no change is being made, we set delta_ts
    # to the current value of the bug. If not, we set it to the new delta
    # This is because the job queue can be added to the database before
    # the bug is committed, especially if updating multiple bugs at the
    # same time.
    my $delta
      = (  scalar(keys %$changes)
        || $self->{added_comments}
        || $self->{comment_isprivate}) ? $timestamp : $bug->delta_ts;
    if ($bug->product_obj->rule_group) {
      Bugzilla->job_queue->insert(
        'rule_engine',
        {
          action    => 'update',
          delta_ts  => $delta,
          bug_ids   => [$bug->id],
          run_after => time + 5,
        }
      );
    }
  }

  return;
}

################################
## JOB QUEUE AND SEARCH HOOKS ##
################################

sub job_map {
  my ($self, $args) = @_;

  my $job_map = $args->{job_map};

  # This adds the named class (an instance of TheSchwartz::Worker) as a
  # handler for when a job is added with the name "rule_engine".
  $job_map->{'rule_engine'} = 'Bugzilla::Extension::RuleEngine::Job';

  return;
}

sub search_operator_field_override {
  my ($self, $args) = @_;

  my $operators = $args->{'operators'};

  $operators->{rh_rule} = {
    _non_changed => \&Bugzilla::Search::_invalid_combination,
    changedfrom  => \&_rh_rule_changedfrom_changedto,
    changedto    => \&_rh_rule_changedfrom_changedto,
  };

  return;
}

# Bug 1257780 - Map rule name to rule id.
#
# This is a bit gnarly. In bug 1201616 the rules engine went from
# storing the name as a string in the history, to storing the name
# as the rule id.
#
# This breaks searching for rules by the rule name.
#
# To fix this, what we need to do is to join the bugs_activity table
# to the rh_rule table on bugs_activity.(removed|added) = rh_rule.id
#
# This was done by taking Bugzilla::Search::_changedfrom_changedto
# and beating on it until the joins were perfomed to make this happen
sub _rh_rule_changedfrom_changedto {
  my ($invocant, $args) = @_;

  my ($chart_id, $joins, $field, $operator, $quoted)
    = @$args{qw(chart_id joins field operator quoted)};

  my $column = ($operator =~ /from/) ? 'removed' : 'added';
  $column .= '::INTEGER' if Bugzilla->is_pg;

  ## REDHAT EXTENSION 964029: Since we hide fields, throw user error
  my $field_object = $invocant->_chart_fields->{$field}
    || ThrowUserError("invalid_field_name", {field => $field});
  my $field_id   = $field_object->id;
  my $act_table  = "act_${field_id}_$chart_id";
  my $rule_table = "rh_rule_${field_id}_${chart_id}";

  my $join = {
    table   => 'bugs_activity',
    as      => $act_table,
    extra   => ["$act_table.fieldid = $field_id"],
    then_to => {
      table      => 'rh_rule',
      as         => $rule_table,
      from       => $column,
      bugs_table => $act_table,
      to         => 'id'
    },
  };

  $args->{term}
    = "$act_table.bug_when IS NOT NULL AND $rule_table.name = $quoted";
  $invocant->_changed_security_check($args, $join);
  push(@$joins, $join);

  return;
}

sub jobqueue_before_run {
  my ($self, $args) = @_;

# If there's active kill switches, stop TheSchwartz from selecting rule engine jobs.
  if (scalar(@{Bugzilla::Extension::RuleEngine::RuleState->active_list})) {
    $args->{job_queue}->set_strict_remove_ability(1);
    $args->{job_queue}
      ->temporarily_remove_ability($args->{job_queue}->job_map->{rule_engine});
  }

  return;
}

sub webservice {
  my ($self, $args) = @_;

  my $dispatch = $args->{dispatch};

  $dispatch->{'RuleEngine'} = 'Bugzilla::Extension::RuleEngine::WebService';
  $dispatch->{'RuleGroup'}
    = 'Bugzilla::Extension::RuleEngine::WebService::RuleGroup';

  return;
}

# Bug 1333985
# This is pretty nasty, but I can't think of a better way to do it.
#
# The rule engine field used to track what the rule engine has done
# to a bug.
#
# To allow rule name changes, we use the ID, meaning we have to on
# the fly remap the ID to a name.
#
# This will modify the argument hash passed to the email template,
# and rewrite the ID to a name.
sub email_before_template {
  my ($self, $args) = @_;

  my $vars = $args->{vars};

  if (any { $_ eq 'rh_rule' } @{$vars->{changedfields}}) {
    foreach my $diff (@{$vars->{diffs}}) {
      if ($diff->{field_name} eq 'rh_rule') {
        my $rule_id = int $diff->{new};
        last unless $rule_id;

        my $name = Bugzilla->process_cache->{_rh_rule_id_to_name}->{$rule_id};
        if (defined($name)) {
          $diff->{new} = $name;
        }
        else {
          my $rule = Bugzilla::Extension::RuleEngine::Rule->new($rule_id);
          $diff->{new} = $rule->name;

          Bugzilla->process_cache->{_rh_rule_id_to_name}->{$rule_id} = $rule->name;
        }

        return;
      }
    }
  }

  return;
}

sub _product_rule_group     { return $_[0]->{'rule_group'}; }
sub _product_set_rule_group { $_[0]->set('rule_group', $_[1]); return; }

sub _product_rule_group_obj {
  my $self = shift;
  my $rule_group;

  if ($self->rule_group) {
    $rule_group
      = Bugzilla::Extension::RuleEngine::RuleGroup->new($self->{'rule_group'});
  }

  return $rule_group;
}

sub update_product_add_vars {
  my ($self, $args) = @_;

  my $product = $args->{product};
  my $changes = $args->{changes};
  my $vars    = $args->{vars};
  my $dbh     = Bugzilla->dbh;

  my $curr_rule_group = $product->rule_group();
  my $rule_group;
  $rule_group = Bugzilla::Extension::RuleEngine::RuleGroup->new($curr_rule_group)
    if ($curr_rule_group);

  if (($vars->{rule_group} ? $vars->{rule_group} : '') ne
    ($rule_group ? $rule_group->name : ''))
  {
    my $new_group = Bugzilla::Extension::RuleEngine::RuleGroup->new(
      {name => $vars->{rule_group}});
    $changes->{rule_group} = [($rule_group ? $rule_group->name : ''),
      ($new_group ? $new_group->name : '')];
    $product->set_rule_group($new_group->id);
    $product->update();
  }

  return;
}

sub _check_rule_group {
  my ($invocant, $id) = @_;

  return unless ($id);

  my $rule_group;

  if ($id =~ m/^\d+$/) {
    $rule_group = Bugzilla::Extension::RuleEngine::RuleGroup->new($id);
  }
  else {
    $rule_group = Bugzilla::Extension::RuleEngine::RuleGroup->new({name => $id});
  }

  return ($rule_group->id);
}

sub _user_can_admin_any_product {
  my ($user) = @_;

  return ($user->in_group('editcomponents')
      || scalar @{$user->get_products_by_permission('editcomponents')});
}

sub _user_can_see_rule {
  my ($user, $rule) = @_;

  if (!ref $rule) {
    return if ($rule eq '');

    if ($rule =~ /^\d+$/) {
      $rule = Bugzilla::Extension::RuleEngine::Rule->check({id => $rule});
    }
    else {
      $rule = Bugzilla::Extension::RuleEngine::Rule->check({name => $rule});
    }
  }

  return ($rule->rule_group->user_can_view($user));
}

sub bug_filter_change {
  my ($self, $args) = @_;

  my $user      = $args->{user};
  my $field     = $args->{field};
  my $added     = $args->{added};
  my $removed   = $args->{removed};
  my $visible   = $args->{visible};
  my $object_id = $args->{object_id};

  if ($field eq 'rh_rule') {
    if (!defined($added)) {
      $$visible = 0;
    }
    else {
      my $rule = Bugzilla::Extension::RuleEngine::Rule->new($added);
      if ($rule) {
        $$visible = $user->can_see_rule($rule);
      }
      else {
        $$visible = $user->in_group('admin');
      }
    }

  }

  return;
}
__PACKAGE__->NAME;

__END__

=encoding UTF-8

=head1 NAME

Bugzilla Rules Engine

=head1 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 I<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.

=head2 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 I<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 I<Rule runs>, there are 3 pssible values.

=over

=item On bug change

This rule when only run when a bug is changed.

=item Periodically

This rule will run when triggered by a cron job.

=item On bug change & periodically

This rule will run both when a bug is changed and when a cron job is run.

=back

=head2 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 I<Run After> value. If you create a rule with the same I<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.

=head2 Using the Rules Engine

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

=head3 Creating and Editing Rules

New rules can be created from the Rules Engine page by clicking on the I<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.

=head4 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, I<"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 I<Add new rule> link on the Rules Engine page. The I<Add new Bugzilla Rules Engine rule - step 1> page is displayed.
2. Enter the required details and click I<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 I<Runs first>.

3. Specify the criteria for the rule and click I<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.

4. Specify the Actions for the rule and click I<Next>.

For each action you require, select it from the I<Action> menu and click I<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 I<Do not change>, I<--->, 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.

5. 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<I am happy with the above changes> checkbox, optionally check the I<Play it safe> checkbox, and click I<Submit changes>.

At this point the rule is finalized and the I<Rule Created> page is displayed. If you checked the I<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.

=head4 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.

=head3 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 I<Modify Rule Groups> link on the Rules Engine page.

=head4 Add a Rule Group

1. From the Rule Group page, click I<Add a new Rule Group>.
2. Specify the Rule Group name, description, edit group, etc.
3. Click I<Save Changes>.

=head4 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 I<Save Changes>.

=head4 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 I<Rule Group> page, click the I<Delete> link for the corresponding Rule Group table row, or
2. From the I<Edit Rule Group> page, click the I<Delete> link.

=head3 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 I<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

=head3 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 I<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.

=head3 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.

=head3 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 I<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 I<Add Kill Switch>.

To disable the Kill Switch, check the checkbox of the reason you want to remove and click I<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 I<Previous Changes>.

=head3 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.

=head4 Cloning a Rule

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

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

See L</"Create a new rule"> for details.

=cut