5.7.218. Bugzilla::Extension::RuleEngine::WebService

5.7.218.1. NAME

Bugzilla::Extension::RuleEngine::WebService - The RuleEngine API

5.7.218.2. DESCRIPTION

This API allows you to upload, download, enable and disable rules.

The API does not allow full editing of rules, but rather allows rules to be copied between testing and production servers.

Also possible is fetching usage stats of rules, as well as switching them on and off.

5.7.218.3. METHODS

list

  • Description
Returns basic information about all the rules, and rule groups in the rules engine
  • Params
  • is_active
boolean optional If set then only active groups and rules will be returned.
  • Returns

Returns a list of all rules, and a list of all rule groups in the rules engine.

  • rules

array-of-hashes Returns an array of hashes listing all the rules in the rules engine. The format of the hash is explained below

  • id
int The ID of the rule
  • name
string The name of the rule
  • description
string The description of the rule
  • rule_group_id
int The ID of the rule group that this rule belongs to
  • is_active
boolean True if the rule is enabled. False if the rule is disabled
  • rule_groups

array-of-hashes Returns an array of hashes listing all the rule groups in the rules engine. The format of the hash is explained below.

  • id
int The ID of the rule group
  • name
name The name of the rule group
  • description
string The description of the rule group
  • is_active
boolean True if the rule group is active. False if inactive.

get

  • Description
Fetches detailed information about a list of rules
  • Params
  • ids
array optional An array of rule ids.
  • names
array optional An array of rule names
  • Returns

Returns an array of hashes. Each hash describes a rule. The format of each has is explained below.

  • id
int The ID of the rule
  • name
string The name of the rule
  • description
string The rule description
  • definition
string The rule data itself. Note that this format is not documented and is subject to change. Manual editing of this is discouraged as the format may change without notice. This should be passed to the update or create functions unmodified.
  • is_active
boolean True if the rule is active and running. False if the rule is inactive.
  • rule_group_id
int The rule group that this rule belongs to.
  • owners
array-of-strings An array of email addresses. Each address is a registered bugzilla user that will receive email notifications upon modification of the rule, or if any errors occour.
  • last_modified
string A timestamp of when the current version of the rule was created
  • last_used
string A timestamp of then the rule was last run
  • use_count
int A counter of how many times the rule has run since it was created
  • use_since_change
int A counter of how many times the rule has run since it was last modified.
  • usage_7days
int A counter of how many times the rule has run in the last 7 days.
  • usage_24hrs
int A counter of how many times the rule has run in the last 24 hours.
  • is_periodic
boolean True if the rule runs once per 24 hours. False if it runs on bug change
  • minor_update
boolean True if changes by this rule should be flagged as minor updates.

create

  • Description
Create a new rules engine rule using a rule definition copied from an existing rule
  • Params

The function takes a hash with a singular key, ‘rules’. The value of the rules item is an array of hashes. The format of each hash within this array is described below.

  • name
string mandatory The name of the new rule
  • description
string mandatory The description of the new rule
  • owners

array-of-strings optional An array of email addresses of registered bugzilla users.

These users will receive notifications when the rule is modified, or if there are any run time errors causing the rule to halt.

  • rule_group_id

integer mandatory The ID if the rule group that this rule belongs to.

A list of valid rule group ids can be obtained from the list RPC call.

  • definition

string mandatory The rule definition.

This can be obtained from the get RPC call.

  • is_active
boolean mandatory If true the rule will be created in a running state. If false, the rule will be created and disabled.
  • is_periodic

boolean optional If True the rule will be run once per 24 hours. If False, the rule will run on bug change.

Default: False.

  • minor_update
boolean optional If True then changes made to bugs by this rule will be marked as minor updates.
  • Returns

Returns an array of hashes. Each hash describes the new rule that has been created.

The contents of the hash are identical to the above, with the addition of the ID parameter.

  • id
int The ID of the newly created rule

update

  • Description
Update the definition of an existing rule, Also allow a rule to be enabled or disabled
  • Params

The function takes a hash with a singular key, ‘rules’. The value of the rules item is an array of hashes. The format of each hash within this array is described below.

If you do not wish to update a particular paramter, do not supply a value for it.

  • id
int mandatory The ID of the rule to update.
  • name
string optional The new name of the rule
  • description
string optional The new description of the rule
  • owners

array-of-strings optional An array of email addresses of the new rule owners.

A rule owner must be a registered bugzilla user. Rule owners will receive notifications if there are any errors with their rules.

  • rule_group_id
int optional The new group that this rule should belong to
  • is_periodic
boolean optional True if the rule should run once every 24 hours. False if the rule should run on bug change.
  • minor_update
boolean optional True if changes by this rule should be flagged as minor updates.
  • definition
string optional A new rule definition. Rule definitions can be obtained from the get RPC call.
  • is_active
boolean optional True to enable the rule. False to disable the rule.
  • Returns

Returns an array of hashes. Each hash describes the changes to one rule. Only fields that were changed will be returned.

Each field will be returned as an array. Elemenet 0 will be the old value that was replaced. Element 1 will be the new value for that field.

update_order

  • Description
Update the order of multiple rules.
  • Params

The function takes an array of hashes. Each entry must contain ‘id’ and ‘sortkey’.

  • id
int mandatory The ID of the rule to update.
  • sortkey
int mandatory The order of the rule.
  • Returns
An array of hashes with the changes made.

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