5.7.173. Bugzilla::Extension::ExternalBugs::WebService

5.7.173.1. NAME

Bugzilla::Extension::ExternalBugs::WebService - The API for creating, changing, and deleting external bug trackers.

5.7.173.2. DESCRIPTION

This part of the Bugzilla API allows you to create, change and delete external bug tracking information for existing bugs in Red Hat Bugzilla. This is a Red Hat specific extension.

5.7.173.3. METHODS

See Bugzilla::WebService for a description of how parameters are passed, and what STABLE, UNSTABLE, and EXPERIMENTAL mean.

5.7.173.4. Functions

All functions require that you are logged in.

5.7.173.5. Webservice Group

All functions belong to the ExternalBugs group, for example: ExternalBugs.add_external_bug

get_ext_data

UNSTABLE

  • Description

Get the current data for an external tracker, inlcuding attempting to sync data.

Note: This method will not send bug mail.

  • Params
  • id
int The id of the external tracker bug.
  • Returns

A hash with the following fields:

id:
int The id of the bug that was updated.
ext_bz_id:
int The id of the external tracker.
ext_bz_bug_id:
int The bug id of the external tracker bug (i.e. the bug number of the external tracker)
ext_status:
string The status of the external bug
ext_priority:
string The priority of the external bug
ext_description:
string The description of the external bug
ext_last_updated:
string The date the External Bug was last synced.
is_private:
bool The link is private.
is_partner:
bool A private link is visible to one or more partner groups.
is_migration_link:
bool This link is where a bug has been migrated to.

add_external_bug

UNSTABLE

  • Description
Add one or more external tracker bugs to one or more existing bugs.
  • Params
  • bug_ids
array - An array of bug ids.
  • external_bugs

array - An array of structs representing the external trackers you wish to add. Each hash has the following keys. either one of ext_bz_bug_id or ext_bz_bug_url must be supplied.

If ext_bz_bug_url is given, no other parameters are required.

If ext_bz_bug_id is given, at least one of ext_type_id, ext_type_description or ext_type_url must also be specified.

  • ext_bz_bug_url
string The full URL to the external bug to be linked to
  • ext_type_id
int The internal id of the external bugzilla type
  • ext_type_description
string The description the external bugzilla type
  • ext_type_url
string The URL value the external bugzilla type
  • ext_bz_bug_id
string The external bug id (i.e. the bug number of the external tracker)
  • ext_status
string The status of the external bug
  • ext_description
string The description of the external bug
  • ext_priority
string The priority of the external bug
  • is_private
bool Force the link to be public or private. Leave unset to allow Bugzilla to automatically set this.
  • is_migration_link
bool This link is where a bug has been migrated to.
  • minor_update
boolean If set to true, this is considered a minor update and no mail is sent to users who do not want minor update emails. If current user is not in the minor_update_group, this parameter is simply ignored.
  • Returns

A hash with a single field, “bugs”. This points to an array of structs with the following fields:

  • id
int The id of the bug that was updated.
  • alias
string The alias of the bug that was updated, if aliases are enabled and this bug has an alias.
  • last_change_time
dateTime The exact time that this update was done at, for this bug. If no update was done (that is, no fields had their values changed and no comment was added) then this will instead be the last time the bug was updated.
  • changes

hash The changes that were actually done on this bug. The keys are the names of the fields that were changed, and the values are a hash with two keys:

  • added (string) The values that were added to this field, possibly a comma-and-space-separated list if multiple values were added.
  • removed (string) The values that were removed from this field, possibly a comma-and-space-separated list if multiple values were

removed.

  • Errors
  • 50 (Parameter required)
You did not specify a required option
  • 1001 (Invalid field)
You specified a field in the external_bugs array that is not valid.
  • 1002 (External Tracker type not specified)
You must specify at least one of ext_type_id, ext_type_description or ext_type_url.
  • 1003 (External Tracker type not found)
The combination of ext_type_* fields did not match any External Trackers. Either the tracker does not exist or you do not have permission to use it.
  • 1004 (External Tracker type not unique)
The combination of ext_type_* fields matched more than one External Tracker.

update_external_bug

UNSTABLE

  • Description

Changes one or more external tracker bugs.

Note: This method will not send bug mail.

  • Params

At least one of ext_desciption, ext_priority or ext_status must be specified. Additionally, either ids, or one ext_type_* and ext_bz_bug_id must be specified. If the ‘ids’ key is specified, all other values are ignored for determining which external tracker bugs are updated.

  • ids
array An array of integer external tracker bug ids.
  • ext_type_id
int The internal id of the external bugzilla type
  • ext_type_description
string The description the external bugzilla type
  • ext_type_url
string The URL value the external bugzilla type
  • ext_bz_bug_id
sting or array of strings The external bug id (i.e. the bug number of the external tracker)
  • bug_ids
array - An array of bug ids.
  • ext_status
string The new status of the external bug
  • ext_description
string The new description of the external bug
  • ext_priority
string The new priority of the external bug
  • is_private
bool Force the link to be public or private. Leave unset to allow Bugzilla to automatically set this.
  • is_migration_link
bool This link is where a bug has been migrated to.
  • Returns

A hash with a single field, “external_bugs”. This points to an array of structs with the following fields:

  • id
int The id of the external tracker bug that was updated.
  • bug_id
int The Red Hat Bugzilla bug number this external tracker bug is attached to.
  • ext_bz_id
int The id of the external tracker updated. More information is available in the type field.
  • ext_bz_bug_id
int The bug id of the external tracker bug (i.e. the bug number of the external tracker)
  • ext_status
string The status of the external bug
  • ext_description
string The description of the external bug
  • ext_priority
string The priority of the external bug
  • is_migration_link
bool This link is where a bug has been migrated to.
  • type
struct Contains information about the External Tracker type.
  • Errors
  • 50 (Parameter required)
You did not specify a required option
  • 1002 (External Tracker type not specified)
You must specify at least one of ext_type_id, ext_type_description or ext_type_url.
  • 1003 (External Tracker type not found)
The combination of ext_type_* fields did not match any External Trackers. Either the tracker does not exist or you do not have permission to use it.
  • 1004 (External Tracker type not unique)
The combination of ext_type_* fields matched more than one External Tracker.
  • 1006 (No External Tracker bugs found)
No external tracker bugs were found that matched your criteria
  • History
  • Added in Bugzilla 4.2.1-2, as a Red Hat extension.

remove_external_bug

UNSTABLE

  • Description
Removes one or more external tracker bugs.
  • Params

Either ids, or one ext_type_* and ext_bz_bug_id must be specified. If the ‘ids’ key is specified, all other values are ignored.

  • ids
array An array of integer external tracker bug ids.
  • ext_type_id
int The internal id of the external bugzilla type
  • ext_type_description
string The description the external bugzilla type
  • ext_type_url
string The URL value the external bugzilla type
  • ext_bz_bug_id
sting or array of strings The external bug id (i.e. the bug number of the external tracker)
  • bug_ids
array - An array of bug ids.
  • minor_update
boolean If set to true, this is considered a minor update and no mail is sent to users who do not want minor update emails. If current user is not in the minor_update_group, this parameter is simply ignored.
  • Returns

A hash with a single field, “external_bugs”. This points to an array of structs representing the external tracker bugs deleted with the following fields:

  • id
int The id of the external tracker bug that was updated.
  • bug_id
int The Red Hat Bugzilla bug number this external tracker bug is attached to.
  • ext_bz_id
int The id of the external tracker updated. More information is available in the type field.
  • ext_bz_bug_id
int The bug id of the external tracker bug (i.e. the bug number of the external tracker)
  • ext_status
string The status of the external bug
  • ext_description
string The description of the external bug
  • ext_priority
string The priority of the external bug
  • is_migration_link
bool This link is where a bug has been migrated to.
  • type
struct Contains information about the External Tracker type.
  • Errors
  • 50 (Parameter required)
You did not specify a required option
  • 1002 (External Tracker type not specified)
You must specify at least one of ext_type_id, ext_type_description or ext_type_url.
  • 1003 (External Tracker type not found)
The combination of ext_type_* fields did not match any External Trackers. Either the tracker does not exist or you do not have permission to use it.
  • 1004 (External Tracker type not unique)
The combination of ext_type_* fields matched more than one External Tracker.
  • 1006 (No External Tracker bugs found)
No external tracker bugs were found that matched your criteria
  • History
  • Added in Bugzilla 4.2.1-2, as a Red Hat extension.

get_tracker

UNSTABLE

  • Description
Get one or more external trackers.
  • Params

Either trackers, or all must be specified.

If a tracker is protected by group membership then it will not be visible if you are not a member of any of the groups.

  • trackers
array An array of tracker ids or descriptions.
  • all
boolean Get all trackers.

create_tracker

UNSTABLE

  • Description

Create an external tracker.

You must be in the editcomments group to use this method.

  • Params
  • description|tracker
string The description to use for the tracker.
  • can_get Optional
boolean Should Bugzilla try and sync data from this tracker?
  • regex Optional

string The type of data this field contains.

If this is not set then IDs are not validated.

Number          | ^[1-9]\d*$                 | a number
Mantis Numbers  | ^\d+$                      | a number with possible leading zeros
JIRA Issue      | ^[A-Z\d]+\-\d+$            | upper case letters or digits, a dash, and numbers
Number or Alias | ^(:?[1-9]\d*|[0-9A-Za-z])$ | a number or alias
SFDC Case       | ^\d{8}$                    | eight digits with possible leading zeros
  • format Optional

string A printf style sting for formatting an ID in the UI.

See matchrx below.

e.g. Github: ‘%s %s %s %s’

  • full_url

string The full URL to a tracker.

e.g. https://bugzilla.mozilla.org/show_bug.cgi?id=%id%

  • matchrx Optional

string A regex used to split up the ID for use in formatting.

See format above.

e.g. Github: (.*)/(.*)/(issues|pull)/(.*)

  • type Optional

integer The type of tracker that it is. Used for syncing data.

Supported types:

None
Bugzilla
Gerrit
GitHub
JIRA
KBase
Redmine
SFDC
SFDC_DEV
SFDC_QA
SFDC_Sandbox
SFDC_Stage

Type ‘None’ does not support syncing.

  • url

string The root URL for the site.

e.g. https://bugzilla.mozilla.org

  • groups Optional
array of group names to limit access to.
  • always_private Optional
bool Force all links on this tracker to be treated as private. This will hide the tracker in the UI and API from users not in the specified groups.
  • must_get Optional
bool Force all links created on this tracker to be synced from the source. Failure to sync will block creation of links.

edit_tracker

UNSTABLE

  • Description

Edit an external tracker.

You must be in the editcomments group to use this method.

  • Params
  • tracker
integer|string The ID or description of the tracker.
  • can_get Optional
boolean Should Bugzilla try and sync data from this tracker?
  • regex Optional

string The type of data this field contains.

If this is not set then IDs are not validated.

Number          | ^[1-9]\d*$                 | a number
Mantis Numbers  | ^\d+$                      | a number with possible leading zeros
JIRA Issue      | ^[A-Z\d]+\-\d+$            | upper case letters or digits, a dash, and numbers
Number or Alias | ^(:?[1-9]\d*|[0-9A-Za-z])$ | a number or alias
SFDC Case       | ^\d{8}$                    | eight digits with possible leading zeros
  • format Optional

string A printf style sting for formatting an ID in the UI.

See matchrx below.

e.g. Github: ‘%s %s %s %s’

  • full_url

string The full URL to a tracker.

e.g. https://bugzilla.mozilla.org/show_bug.cgi?id=%id%

  • matchrx Optional

string A regex used to split up the ID for use in formatting.

See format above.

e.g. Github: (.*)/(.*)/(issues|pull)/(.*)

  • type

integer The type of tracker that it is. Used for syncing data.

Supported types:

None
Bugzilla
Gerrit
GitHub
GitLab
JIRA
KBase
Redmine
SFDC
SFDC_DEV
SFDC_QA
SFDC_Sandbox
SFDC_Stage

Type ‘None’ does not support syncing.

  • url

string The root URL for the site.

e.g. https://bugzilla.mozilla.org

  • groups
array of group names to limit access to.
  • always_private Optional
bool Force all links on this tracker to be treated as private. This will hide the tracker in the UI and API from users not in the specified groups.
  • must_get Optional
bool Force all links created on this tracker to be synced from the source. Failure to sync will block creation of links.

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