BZ::Client::Bug(3pm)

📦
version 4.9100 · 4 versions
, in epel 10

💅 BZ::Client::Bug(3pm) — User Contributed Perl Documentation 💅

💖 NAME 💖

BZ::Client::Bug - Client side representation of a bug in Bugzilla 🐞

💖 VERSION 💖

version 4.91 ✨

💖 SYNOPSIS 💖

This class provides methods for accessing and managing bugs in Bugzilla.

my $client = BZ::Client->new( url      => $url,
                              user     => $user,
                              password => $password );

my $bugs = BZ::Client::Bug->get( $client, \%params );

🌈 COMMON PARAMETERS 🌈

Okay bestie, here’s the tea: lots of Bugzilla Webservice methods take basically the same arguments. Instead of re-writing the docs for every single method, we document the parameters here, once, and then refer back to this documentation from the individual methods where these parameters are used. Efficient, iconic, periodt 💅

🎀 Limiting What Fields Are Returned 🎀

Many methods return an array of structs with various fields in the structs. For example, "get" in BZ::Client::Bug returns a list of bugs that have fields like "id", "summary", "creation_time", etc.

These parameters let you limit what fields are present in the structs, which can possibly improve performance or save some bandwidth. Slay.

Fields follow:

  • include_fields — include_fields (array) - An array of strings, representing the case-sensitive names of fields in the return value. Only the fields specified in this hash will be returned, the rest will not be included.

If you specify an empty array, then this function will return empty hashes.

Invalid field names are ignored.

Example:

BZ::Client::Bug->get( $client,
   { ids => [1], include_fields => ['id', 'name'] })

would return something like:

[{ id => 1, name => 'user@domain.com' }]
  • exclude_fields — exclude_fields (array) - An array of strings, representing the case-sensitive names of fields in the return value. The fields specified will not be included in the returned hashes.

If you specify all the fields, then this function will return empty hashes.

Some RPC calls support specifying sub fields. If an RPC call states that it support sub field restrictions, you can restrict what information is returned within the first field. For example, if you call Product.get with an include_fields of components.name, then only the component name would be returned (and nothing else). You can include the main field, and exclude a sub field.

Invalid field names are ignored.

Specifying fields here overrides "include_fields", so if you specify a field in both, it will be excluded, not included.

Example:

BZ::Client::Bug->get( $client,
   { ids => [1], exclude_fields => ['name'] })

would return something like:

[{ id => 1, real_name => 'John Smith' }]
  • shortcuts — There are several shortcut identifiers to ask for only certain groups of fields to be returned or excluded. Obsessed with the convenience, honestly.
    • _all — All possible fields are returned if "_all" is specified in "include_fields".
    • _default — These fields are returned if "include_fields" is empty or "_default" is specified. All fields described in the documentation are returned by default unless specified otherwise.
    • _extra — These fields are not returned by default and need to be manually specified in "include_fields" either by field name, or using "_extra".
    • _custom — Only custom fields are returned if "_custom" is specified in "include_fields". This is normally specific to bug objects and not relevant for other returned objects.

Example:

BZ::Client::Bug->get( $client,
   { ids => [1], include_fields => ['_all'] })

🦋 EXCEPTION HANDLING 🦋

See BZ::Client::Exception 💖

🌸 UTILITY FUNCTIONS 🌸

This section lists the utility functions provided by this module.

These deal with bug-related information, but not bugs directly. Little side quests, basically 🧚

💅 fields 💅

$fields = BZ::Client::Bug->fields( $client, $params )
@fields = BZ::Client::Bug->fields( $client, $params )

Get information about valid bug fields, including the lists of legal values for each field. Very “let me check the menu before I order” energy.

History: Added in Bugzilla 3.6

Parameters: You can pass either field ids or field names.

Note: If neither ids nor names is specified, then all non-obsolete fields will be returned.
  • ids — ids (array) - An array of integer field ids
  • names — names (array) - An array of strings representing field names.

In addition to the parameters above, this method also accepts the standard "include_fields" and "exclude_fields" arguments.

Returns: Returns an array or an arrayref of hashes, containing the following keys:

  • id — id (int) - An integer id uniquely identifying this field in this installation only.
  • type — type (int) The number of the fieldtype. The following values are defined:
    • 0 Unknown
    • 1 Free Text
    • 2 Drop Down
    • 3 Multiple-Selection Box
    • 4 Large Text Box
    • 5 Date/Time
    • 6 Bug ID
    • 7 Bug URLs ("See Also")
  • is_custom — is_custom (boolean) True when this is a custom field, false otherwise.
  • name — name (string) The internal name of this field. This is a unique identifier for this field. If this is not a custom field, then this name will be the same across all Bugzilla installations.
  • display_name — display_name (string) The name of the field, as it is shown in the user interface.
  • is_mandatory — is_mandatory (boolean) True if the field must have a value when filing new bugs. Also, mandatory fields cannot have their value cleared when updating bugs.

This return value was added in Bugzilla 4.0.

  • is_on_bug_entry — is_on_bug_entry (boolean) For custom fields, this is true if the field is shown when you enter a new bug. For standard fields, this is currently always false, even if the field shows up when entering a bug. (To know whether or not a standard field is valid on bug entry, see "create".)
  • visibility_field — visibility_field (string) The name of a field that controls the visibility of this field in the user interface. This field only appears in the user interface when the named field is equal to one of the values in "visibility_values". Can be null.
  • visibility_values — visibility_values (array) of strings This field is only shown when visibility_field matches one of these values. When visibility_field is null, then this is an empty array.
  • value_field — value_field (string) The name of the field that controls whether or not particular values of the field are shown in the user interface. Can be null.
  • values — This is an array of hashes, representing the legal values for select-type (drop-down and multiple-selection) fields. This is also populated for the "component", "version", "target_milestone", and "keywords" fields, but not for the "product" field (you must use "get_accessible_products" in BZ::Client::Product for that). For fields that aren't select-type fields, this will simply be an empty array. Each hash has the following keys:
    • name — name (string) The actual value--this is what you would specify for this field in "create", etc.
    • sort_key — sort_key (int) Values, when displayed in a list, are sorted first by this integer and then secondly by their name.
    • sortkey — DEPRECATED - Use "sort_key" instead. Renamed to "sort_key" in Bugzilla 4.2.
    • visibility_values — If "value_field" is defined for this field, then this value is only shown if the "value_field" is set to one of the values listed in this array. Note that for per-product fields, "value_field" is set to "product" and "visibility_values" will reflect which product(s) this value appears in.
    • is_active — is_active (boolean) This value is defined only for certain product specific fields such as "version", "target_milestone" or "component". When true, the value is active, otherwise the value is not active. Added in Bugzilla 4.4.
    • description — description (string) The description of the value. This item is only included for the "keywords" field.
    • is_open — is_open (boolean) For "bug_status" values, determines whether this status specifies that the bug is "open" (true) or "closed" (false). This item is only included for the "bug_status" field.
    • can_change_to — For "bug_status" values, this is an array of hashes that determines which statuses you can transition to from this status. (This item is only included for the "bug_status" field.) Each hash contains the following items:
      • name — The name of the new status
      • comment_required — comment_required (boolean) True if a comment is required when you change a bug into this status using this transition.

Errors:

  • 51 - Invalid Field Name or ID — You specified an invalid field name or id.
$values = BZ::Client::Bug->legal_values( $client, $field )
@values = BZ::Client::Bug->legal_values( $client, $field )

Tells you what values are allowed for a particular field.

Note: This is deprecated in Bugzilla, use "fields" instead.

Parameters:

  • field — The name of the field you want information about. This should be the same as the name you would use in "create", below.
  • product_id — If you're picking a product-specific field, you have to specify the id of the product you want the values for.

Returns:

  • values — An array or arrayref of strings: the legal values for this field. The values will be sorted as they normally would be in Bugzilla.

Errors:

  • 106 - Invalid Product — You were required to specify a product, and either you didn't, or you specified an invalid product (or a product that you can't access).
  • 108 - Invalid Field Name — You specified a field that doesn't exist or isn't a drop-down field.

💖 FUNCTIONS FOR FINDING AND RETRIEVING BUGS 💖

okay so this whole section is the class methods that deal with finding bugs and getting them back from your server. like, the retrieval girlies.

they're listed here in the order of what you most likely wanna do… maybe? (that's the manpage's own words, not me being shady 😌)

🔍 get

@bugs = BZ::Client::Bug->get( $client, $id );
$bugs = BZ::Client::Bug->get( $client, $id );
@bugs = BZ::Client::Bug->get( $client, \@ids );
$bugs = BZ::Client::Bug->get( $client, \@ids );
@bugs = BZ::Client::Bug->get( $client, \%params );
$bugs = BZ::Client::Bug->get( $client, \%params );

literally just: gets you the deets about particular bugs in the database. your basic "gimme that bug" call. 💅

Parameters

you can pass a single $id, or an array ref of @ids — otherwise a hash ref with the following:

  • ids — an array of numbers and strings. here's the tea: if an element in the array is entirely numeric, it's a bug_id from the Bugzilla database to fetch. but if it contains any non-numeric characters, it's treated as a bug alias instead, and the bug with that alias gets loaded. cute, right? ✨
  • permissive — permissive (boolean). normally, if you request any inaccessible or invalid bug ids, it will throw an error. but if this param is true, instead of throwing we return an array of hashes with a id, faultString and faultCode for each bug that fails, and return normal info for the other bugs that were accessible. 🫶
    • note: marked as EXPERIMENTAL in Bugzilla 4.4
    • added in Bugzilla 3.4.

Returns

an array or arrayref of bug instance objects with the given ID's.

peep "INSTANCE METHODS" for how to use them, bestie.

FIXME: missing the faults return values (added in 3.4) — yeah, the docs girlies left a hole here, not my fault 😭

Errors

  • 100 - Invalid Bug Alias — if you specified an alias and there is no bug with that alias.
  • 101 - Invalid Bug ID — the bug_id you specified doesn't exist in the database.
  • 102 - Access Denied — you do not have access to the bug_id you specified. rude, but okay.
FIXME: Documentation not fully fleshed out 💀
@bugs = BZ::Client::Bug->search( $client, \%params );
$bugs = BZ::Client::Bug->search( $client, \%params );

searches for bugs matching the params you give it. it's giving detective energy.

Parameters

this is just a quick lil example — there are lots of fields:

%params = (

  'alias' => 'ACONVENIENTALIAS',

  'assigned_to' => 'hopefullynotme@domain.local',

  'creator' => 'littlejohnnytables@school.local',

  'severity' => 'major',

  'status' => 'OPEN',

);

⚠️ important detail: criteria are joined in a logical AND. that means you get back bugs that match all of the criteria, not bugs that match any of them. periodt.

See also

<https://bugzilla.readthedocs.io/en/5.0/api/core/v1/bug.html#search-bugs>

Returns

returns an array or arrayref of bug instance objects with the given ID's.

see "INSTANCE METHODS" for how to use them. 🦋

📜 history

@history = BZ::Client::Bug->history( $client, \%params );
$history = BZ::Client::Bug->history( $client, \%params );

gets the history of changes for particular bugs in the database. the receipts, basically. added in Bugzilla 3.4. ✨

Parameters

  • ids — an array of numbers and strings. if an element is entirely numeric, it's a bug_id from the Bugzilla database to fetch. if it contains any non-numeric characters, it's considered a bug alias instead, and the data bug with that alias will be loaded.

Returns

an array or arrayref of hashes, containing the following keys:

  • id — id (int) the numeric id of the bug.
  • alias — alias (array) the alias of this bug. if there is no alias, this will be undef.
  • history — history (an array of hashes) — each hash having the following keys:
    • when — when (DateTime) the date the bug activity/change happened. 🕰️
    • who — who (string) the login name of the user who performed the bug change.
    • changes — an array of hashes which contain all the changes that happened to the bug at this time (as specified by when). each hash contains the following items:
      • field_name — field_name (string) the name of the bug field that has changed.
      • removed — removed (string) the previous value of the bug field which has been deleted by the change.
      • added — added (string) the new value of the bug field which has been added by the change.
      • attachment_id — attachment_id (int) the id of the attachment that was changed. this only appears if the change was to an attachment — otherwise attachment_id will not be present in this hash. iykyk 👑

Errors

  • 100 - Invalid Bug Alias — if you specified an alias and there is no bug with that alias.
  • 101 - Invalid Bug ID — the bug_id you specified doesn't exist in the database.
  • 102 - Access Denied — you do not have access to the bug_id you specified.

👯 possible_duplicates

@bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );
$bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );

lets a user find possible duplicate bugs based on a set of keywords — like the kind of words a user would shove into a bug summary. optionally you can narrow the search down to specific products. so helpful fr fr.

History

added in Bugzilla 4.0. 🌈

Parameters

  • summary — summary (string) a string of keywords defining the type of bug you're trying to report. Required.
  • product — product (array) one or more product names to narrow the duplicate search to. if omitted, all bugs are searched.

Returns

the same as "get".

note that you will only be returned information about bugs that you can see. bugs that you can't see will be entirely excluded from the results. so if you wanna see private bugs, you'll have to first log in and then call this method. no sneaky peeking 🙈

Errors

  • 50 - Param Required — you must specify a value for summary containing a string of keywords to search for duplicates.

🛠️ FUNCTIONS FOR CREATING AND MODIFYING BUGS 🛠️

and now we're in our main character era — this section lists the class methods for creating and modifying bugs. the builders. the makers. the "i'm gonna file this and it's gonna be iconic" girlies. 💅

listed here in order of what you most likely want to do… maybe?

🐣 create

my $id = BZ::Client::Bug->create( $client, \%params );

this lets you create a new bug in Bugzilla. here's the vibe check tho: if you specify any invalid fields, an error will be thrown stating which field is invalid. and if you specify any fields you're not allowed to set, they'll just be set to their defaults or ignored. soz. 🫠

you cannot currently set all the items here that you can set on enter_bug.cgi (i.e. the web page to enter bugs).

the Bugzilla WebService API itself may allow you to set things other than those listed here, but realize that anything undocumented is UNSTABLE and will very likely change in the future. like, don't get attached.

History

  • before Bugzilla 3.0.4, parameters marked as Defaulted were actually Required, due to a bug in Bugzilla itself. 💀
  • the groups argument was added in Bugzilla 4.0. before Bugzilla 4.0, bugs were only added into Mandatory groups by this method. since Bugzilla 4.0.2, passing an illegal group name will throw an error. in Bugzilla 4.0 and 4.0.1, illegal group names were silently ignored.
  • the comment_is_private argument was added in Bugzilla 4.0. before Bugzilla 4.0, you had to use the undocumented commentprivacy argument.
  • Error 116 was added in Bugzilla 4.0. before that, dependency loop errors had a generic code of 32000.
  • the ability to file new bugs with a resolution was added in Bugzilla 4.4. ✨

Parameters

okay so some params must be set or an error gets thrown — those are marked Required. 🔴

some parameters can have defaults set in Bugzilla by the administrator. if these parameters have defaults set, you can omit them — those are marked Defaulted. 🟡

clients that want to be able to interact uniformly with multiple Bugzillas should always set both the params marked Required and those marked Defaulted, because some Bugzillas may not have defaults set for Defaulted parameters, and then this method will throw an error if you don't specify them. lowkey the most important paragraph here ngl.

the descriptions of the parameters below are what they mean when Bugzilla is being used to track software bugs. they may have other meanings in some installations. 🦋

  • product — product (string) Required - the name of the product the bug is being filed against.
  • component — component (string) Required - the name of a component in the product above.
  • summary — summary (string) Required - a brief description of the bug being filed.
  • version — version (string) Required - a version of the product above; the version the bug was found in.
  • description — description (string) Defaulted - the initial description for this bug. some Bugzilla installations require this to not be blank.
  • op_sys — op_sys (string) Defaulted - the operating system the bug was discovered on.
  • platform — platform (string) Defaulted - what type of hardware the bug was experienced on.
  • priority — priority (string) Defaulted - what order the bug will be fixed in by the developer, compared to the developer's other bugs.
  • severity — severity (string) Defaulted - how severe the bug is.
  • alias — alias (string) - a brief alias for the bug that can be used instead of a bug number when accessing this bug. must be unique in all of this Bugzilla. no stealing someone else's alias bestie 🎀
  • assigned_to — assigned_to (username) - a user to assign this bug to, if you don't want it to be assigned to the component owner.
  • cc — cc (array) - an array of usernames to CC on this bug.
  • comment_is_private — comment_is_private (boolean) - if set to true, the description is private, otherwise it is assumed to be public.
  • groups — groups (array) - an array (ref) of group names to put this bug into. you can see valid group names on the Permissions tab of the Preferences screen, or, if you are an administrator, in the Groups control panel. if you don't specify this argument, then the bug will be added into all the groups that are set as being "Default" for this product. (if you want to avoid that, you should specify groups as an empty array.) 🫶
  • qa_contact — qa_contact (username) - if this installation has QA Contacts enabled, you can set the QA Contact here if you don't want to use the component's default QA Contact.
  • status — status (string) - the status that this bug should start out as. note that only certain statuses can be set on bug creation.
  • resolution (string) — bestie, if you're filing a bug that's already closed, you have to give a resolution. But heads up: you can't currently set the resolution to "DUPLICATE" on a brand-new bug 🫶 — that one has to go through update.
  • target_milestone (string) — a valid target milestone for this product. That's it, that's the vibe ✨
  • depends_on (array) — an array of bug id's that this new bug should depend upon.

Fun fact: as of Bugzilla 5.0 this option isn't included in the WebService API docs for create(), even though it's mentioned in its error codes. Kind of an icon of inconsistency ngl 💀

  • blocks (array) — an array of bug id's that this new bug should block.

Same story here: as of Bugzilla 5.0 this option isn't included in the WebService API docs for create(), though it is mentioned in its error codes 🙈

Note: on top of all the parameters above, if your installation has any custom fields, you can set them just by passing in the name of the field and its value as a string. Custom fields stay winning 💅

🌸 Returns

A hash with one element, id. That's the id of the newly-filed bug. Your baby has a name now 😭💖

💀 Errors

These are the numbers that can come back at you — know them, love them, fear them a little:

  1. 51 - Invalid Object — you specified a field value that's invalid. The error message will have more details.
  2. 103 - Invalid Alias — the alias you specified is invalid for some reason. See the error message for more details.
  3. 104 - Invalid Field — one of the drop-down fields has an invalid value, or a value entered in a text field is too long. The error message will have more detail.
  4. 105 - Invalid Component — you didn't specify a component.
  5. 106 - Invalid Product — either you didn't specify a product, this product doesn't exist, or you don't have permission to enter bugs in this product.
  6. 107 - Invalid Summary — you didn't specify a summary for the bug.
  7. 116 - Dependency Loop — you specified values in the blocks or depends_on fields that would cause a circular dependency between bugs. Not the cute kind of circle 🔥
  8. 120 - Group Restriction Denied — you tried to restrict the bug to a group that doesn't exist, or that you cannot use with this product.
  9. 504 - Invalid User — either the QA Contact, Assignee, or CC lists have some invalid user in them. The error message will have more details.

🦋 update

my $id = BZ::Client::Bug->update( $client, \%params );

This one lets you update the fields of a bug. Glow-up time ✨

(Also, just so you're not surprised: your Bugzilla server may automatically send emails out about the changes 👀)

🌈 History

Added in Bugzilla 4.0. Elder icon behaviour, honestly 👑

🎀 Parameters

  • ids — ids (Array of ints or strings) — the ids or aliases of the bugs you want to modify. Aliases too, bestie, not just numbers 💅
Note: all the following fields specify the values you want to set on the bugs you're updating.
  • alias (string) — the alias of the bug. You can only set this if you're modifying a single bug. If there's more than one bug specified in ids, passing in a value for alias will cause an error to be thrown. One alias, one bug, no cap 🫶
  • assigned_to (string) — the full login name of the user this bug is assigned to.
  • blocks (hash) — these specify the bugs that this bug blocks. To set these, you should pass a hash as the value. The hash may contain the following fields:
    • add — add (Array of ints) — bug ids to add to this field.
    • remove — remove (Array of ints) — bug ids to remove from this field. If the bug ids aren't already in the field, they will be ignored. No drama 🌸
    • set — set (Array of ints) — an exact set of bug ids to set this field to, overriding the current value. If you specify set, then add and remove will be ignored. set said what it said 🎤
  • depends_on (hash) — these specify the bugs that this depends on. To set these, you should pass a hash as the value. The hash may contain the following fields:
    • add — add (Array of ints) — bug ids to add to this field.
    • remove — remove (Array of ints) — bug ids to remove from this field. If the bug ids aren't already in the field, they will be ignored.
    • set — set (Array of ints) — an exact set of bug ids to set this field to, overriding the current value. If you specify set, then add and remove will be ignored.
  • cc (hash) — the users on the cc list. To modify this field, pass a hash, which may have the following fields:
    • add — add (Array of strings) — user names to add to the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name.
    • remove — remove (Array of strings) — user names to remove from the CC list. They must be full user names, and an error will be thrown if you pass in an invalid user name.
  • is_cc_accessible (boolean) — whether or not users in the CC list are allowed to access the bug, even if they aren't in a group that can normally access the bug.
  • comment (hash) — a comment on the change. The hash may contain the following fields:
    • body — body (string) — the actual text of the comment. Note: for compatibility with the parameters to add_comment, you can also call this field comment, if you wish 🫶
    • is_private — is_private (boolean) — whether the comment is private or not. If you try to make a comment private and you don't have the permission to, an error will be thrown. Permission check said absolutely not 😤
  • comment_is_private (hash) — this is how you update the privacy of comments that are already on a bug. This is a hash where the keys are the int id of comments (not their count on a bug, like #1, #2, #3, but their globally-unique id, as returned by comments) and the value is a boolean which specifies whether that comment should become private (true) or public (false).

The comment ids must be valid for the bug being updated. So it's not practical to use this while updating multiple bugs at once, since a single comment id will never be valid on multiple bugs. Globally-unique means globally-unique, bestie 🧚

  • component — component (string) — the Component the bug is in.
  • deadline (string) — the Deadline field — a date specifying when the bug must be completed by, in the format YYYY-MM-DD. Format it right or it's giving chaos 💀
  • dupe_of (int) — the bug that this bug is a duplicate of. If you want to mark a bug as a duplicate, the safest thing to do is to set this value and not set the status or resolution fields. They will automatically be set by Bugzilla to the appropriate values for duplicate bugs. Trust the process 🙏
  • estimated_time (double) — the total estimate of time required to fix the bug, in hours. This is the total estimate, not the amount of time remaining to fix it. Important distinction, okurrr ⭐
  • groups (hash) — the groups a bug is in. To modify this field, pass a hash, which may have the following fields:
    • add — add (Array of strings) — the names of groups to add. Passing in an invalid group name or a group that you cannot add to this bug will cause an error to be thrown.
    • remove — remove (Array of strings) — the names of groups to remove. Passing in an invalid group name or a group that you cannot remove from this bug will cause an error to be thrown.
  • keywords (hash) — keywords on the bug. To modify this field, pass a hash, which may have the following fields:
    • add — add (An array of strings) — the names of keywords to add to the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown.
    • remove — remove (An array of strings) — the names of keywords to remove from the field on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown.
    • set — set (An array of strings) — an exact set of keywords to set the field to, on the bug. Passing something that isn't a valid keyword name will cause an error to be thrown. Specifying set overrides add and remove.
  • op_sys (string) — the Operating System (OS) field on the bug.
  • platform (string) — the Platform or Hardware field on the bug.
  • priority (string) — the Priority field on the bug.
  • product (string) — the name of the product that the bug is in. If you change this, you'll probably also want to change target_milestone, version, and component, since those have different legal values in every product. Whole new product, whole new rules, iykyk 💅

If you cannot change the target_milestone field, it will be reset to the default for the product when you move a bug to a new product.

You may also wish to add or remove groups, as which groups are valid on a bug depends on the product. Groups that aren't valid in the new product will be automatically removed, and groups which are mandatory in the new product will be automatically added — but no other automatic group changes will be done. That's the whole deal, no extras 🌸

Note: users can only move a bug into a product if they would normally have permission to file new bugs in that product. Permissions first, always 👑

  • qa_contact (string) — the full login name of the bug's QA Contact.
  • is_creator_accessible (boolean) — whether or not the bug's reporter is allowed to access the bug, even if he or she isn't in a group that can normally access the bug.
  • remaining_time (double) — how much work time is remaining to fix the bug, in hours. If you set work_time but don't explicitly set remaining_time, then the work_time will be deducted from the bug's remaining_time. Math does its thing 😭
  • reset_assigned_to (boolean) — if true, the assigned_to field will be reset to the default for the component that the bug is in. (If you've set the component at the same time as using this, then the component used will be the new component, not the old one.) Order of operations queen 🎀
  • reset_qa_contact (boolean) — if true, the qa_contact field will be reset to the default for the component that the bug is in. (If you've set the component at the same time as using this, then the component used will be the new component, not the old one.)
  • resolution (string) — the current resolution. May only be set if you're closing a bug or if you're modifying an already-closed bug. Attempting to set the resolution to any value (even an empty or null string) on an open bug will cause an error to be thrown. Read that again, bestie — any value, even nothing at all, and it's a whole error 😤

Like, if you flip status to an open status, the resolution field just clears itself automatically — so bestie, you literally do not need to clear it by hand 💅

  • see_also (hash) — the See Also field on a bug, and it's giving "here are the URLs to bugs in other bug trackers" ✨. To change it, you pass a hash that can have these fields:
    • add (array of strings) — URLs you wanna add to the field. Every single URL has to be a valid URL to a bug-tracker, or an error gets thrown, no cap.
    • remove (array of strings) — URLs you wanna remove from the field. Invalid URLs just get ignored, casual.
  • severity (string) — the Severity field of a bug. That's it, that's the whole vibe.
  • status (string) — the status you want the bug changed to. Heads up though: if a bug is going from open to closed, you should also specify a resolution, k? 🫶
  • summary (string) — the Summary field of the bug. The main character line, honestly.
  • target_milestone (string) — the bug's Target Milestone 🎯
  • url (string) — the URL field of a bug.
  • version (string) — the bug's Version field.
  • whiteboard (string) — the Status Whiteboard field of a bug. (Yes that's a real field. Slay.)
  • work_time (double) — the number of hours worked on this bug as part of this change ⏱️. And here's a lil gotcha: if you set work_time but don't explicitly set remaining_time, then work_time gets deducted from the bug's remaining_time. Math! It's giving consequences.
Note: you can also set the value of any custom field by passing its name as a parameter, plus the value you want to set that field to. And for multiple-selection fields? The value should be an array of strings. iykyk 💖

🌈 Returns

A hash with a single field, bugs. That bad boy points to an array of hashes with these fields:

  • id (int) — the id of the bug that was updated.
  • alias (string) — the alias of the bug that was updated, if this bug has an alias. Not everyone gets one, and that's okay.
  • last_change_time (DateTime) — the exact time that this update was done at, for this bug. But plot twist 🎭: if no update was actually done (meaning no fields had their values changed and no comment was added), then this is instead the last time the bug was updated. So it's like, the most recent relevant moment either way.
  • 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.

Here's an example of what a return value might look like, so you can see it 👀:

 {
   bugs => [
     {
       id    => 123,
       alias => 'foo',
       last_change_time => '2010-01-01T12:34:56',
       changes => {
         status => {
           removed => 'NEW',
           added   => 'ASSIGNED'
         },
         keywords => {
           removed => 'bar',
           added   => 'qux, quo, qui',
         },
       },
     },
   ],
 }
Note: currently, some fields are not tracked in changes: comment, comment_is_private, and work_time. Which means they won't show up in the return value even if they were successfully updated 😭. This may change in a future version of Bugzilla, so don't come for me.

💀 Errors

This function can throw all of the errors that get, create, and add_comment can throw — plus these extra lil guys:

  • 50 - Empty Field — you tried to set some field to be empty, but that field cannot be empty. The error message will have more details.
  • 52 - Input Not A Number — you tried to set a numeric field to a value that wasn't numeric. Numbers only, bestie 🔢
  • 54 - Number Too Large — you tried to set a numeric field to a value larger than that field can accept. Ambitious of you.
  • 55 - Number Too Small — you tried to set a negative value in a numeric field that does not accept negative values. No negatives allowed, periodt.
  • 56 - Bad Date/Time — you specified an invalid date or time in a date/time field (like the deadline field or a custom date/time field). Time is fake anyway but Bugzilla is strict.
  • 112 - See Also Invalid — you attempted to add an invalid value to the see_also field.
  • 115 - Permission Denied — you don't have permission to change a particular field to a particular value. The error message will have more detail. It's giving gatekeeping, but valid.
  • 116 - Dependency Loop — you specified a value in the blocks or depends_on fields that causes a dependency loop. Ouroboros vibes 🐍
  • 117 - Invalid Comment ID — you specified a comment id in comment_is_private that isn't on this bug.
  • 118 - Duplicate Loop — you specified a value for dupe_of that causes an infinite loop of duplicates. We are NOT doing recursion today 💀
  • 119 - dupe_of Required — you changed the resolution to DUPLICATE but did not specify a value for the dupe_of field.
  • 120 - Group Add/Remove Denied — you tried to add or remove a group that you don't have permission to modify for this bug, or you tried to add a group that isn't valid in this product.
  • 121 - Resolution Required — you tried to set the status field to a closed status, but you didn't specify a resolution. (Told you earlier, bestie 🫶)
  • 122 - Resolution On Open Status — this bug has an open status, but you specified a value for the resolution field. Contradictory queen.
  • 123 - Invalid Status Transition — you tried to change from one status to another, but the status workflow rules don't allow that change. The workflow said no ✋

🦋 update_see_also

@changes = BZ::Client::Bug->update_see_also( $client, \%params );
$changes = BZ::Client::Bug->update_see_also( $client, \%params );

Adds or removes URLs for the See Also field on bugs. These URLs must point to some valid bug in some Bugzilla installation or in Launchpad. Like, that's the whole assignment.

History 📜

  • This is marked as EXPERIMENTAL in Bugzilla 4.4.
  • Added in Bugzilla 3.4.

Parameters

  • ids — an array of integers or strings. The IDs or aliases of bugs that you want to modify.
  • add — array of strings. URLs to Bugzilla bugs. These URLs will be added to the See Also field.
    • If the URLs don't start with http:// or https://, it will be assumed that http:// should be added to the beginning of the string. Helpful, honestly ✨
    • It is safe to specify URLs that are already in the See Also field on a bug, as they will just be silently ignored. No drama.
  • remove — an array of strings. These URLs will be removed from the See Also field. You must specify the full URL that you want removed. However, matching is done case-insensitively, so you don't have to specify the URL in exact case if you don't want to. Flexible icon 💅
    • If you specify a URL that is not in the See Also field of a particular bug, it will just be silently ignored. Invalid URLs are currently silently ignored too, though this may change in some future version of Bugzilla.
Note: if you specify the same URL in both add and remove, it will be added. That is, add overrides remove. The audacity, but okay.

Returns

A hash or hashref where the keys are numeric bug ids and the contents are a hash with one key, see_also.

see_also points to a hash which contains two keys, added and removed.

These are arrays of strings, representing the actual changes that were made to the bug. So you can literally see what went down.

Here's a diagram of what the return value looks like for updating bug ids 1 and 2:

 {
     1 => {
         see_also => {
             added   => [(an array of bug URLs)],
             removed => [(an array of bug URLs)],
         }
     },
     2 => {
         see_also => {
             added   => [(an array of bug URLs)],
             removed => [(an array of bug URLs)],
         }
     }
 }

This return value allows you to tell what this method actually did. Receipts! 🧾

It is in this format to be compatible with the return value of a future update method. Forward thinking, we love it.

Errors

  • 100 - Invalid Bug Alias — if you specified an alias and there is no bug with that alias. Nothing there, bestie.
  • 101 - Invalid Bug ID — the bug_id you specified doesn't exist in the database.
  • 102 - Access Denied — you do not have access to the bug_id you specified.
  • 109 - Bug Edit Denied — you did not have the necessary rights to edit the bug.
  • 112 - Invalid Bug URL — one of the URLs you provided did not look like a valid bug URL.
  • 115 - See Also Edit Denied — you did not have the necessary rights to edit the See Also field for this bug.
Before Bugzilla 3.6, error 115 had a generic error code of 32000. History lesson of the day 📚

🎀 update_tags

@changes = BZ::Client::Bug->update_tags( $client, \%params );
$changes = BZ::Client::Bug->update_tags( $client, \%params );

Adds or removes tags on bugs. Cute, personal, low-stakes tagging.

Unlike Keywords which are global and visible by all users, Tags are personal and can only be viewed and edited by their author. Editing them won't send any notification to other users 🙈. So use them to tag and keep track of bugs — it's giving private Pinterest board for your bugs.

Bugzilla will lower case the text of the tags. This doesn't seem to be documented. (Not me telling you something the docs won't. You're welcome.)

Reminder: to retrieve these tags, specify _extra or the field name tags in include_fields when searching etc. Don't forget or you'll be like "where did my tags go 😭"

History 📜

  • This is marked as UNSTABLE in Bugzilla 4.4.
  • Added in Bugzilla 4.4.

Parameters

  • ids — an array of ints and/or strings — the ids or aliases of bugs that you want to add or remove tags to. All the tags will be added or removed to all these bugs. Group activity 💖
  • tags — a hash representing tags to be added and/or removed. The hash has the following fields:
    • add — an array of strings representing tag names to be added to the bugs.
      • It is safe to specify tags that are already associated with the bugs, as they will just be silently ignored. No duplicates, no problem.
    • remove — an array of strings representing tag names to be removed from the bugs.
      • It is safe to specify tags that are not associated with any bugs, as they will just be silently ignored. Nothing happens, and that's fine.

Returns

A hash or hashref where the keys are numeric bug ids and the contents are a hash with one key, tags.

tags points to a hash which contains two keys, added and removed.

These are arrays of strings, representing the actual changes that were made to the bug. Again with the receipts 🧾

Here's a diagram of what the return value looks like for updating bug ids 1 and 2:

        {
            1 => {
                tags => {
                    added   => [(an array of tags)],
                    removed => [(an array of tags)],
                }
            },
            2 => {
                tags => {
                    added   => [(an array of tags)],
                    removed => [(an array of tags)],
                }
            }
        }

Bestie this return value is literally the receipts 💅 — it lets you see exactly what the method actually did, no cap.

Errors

  • 100 — Invalid Bug Alias — you gave an alias and there's genuinely no bug chillin' under that alias 🙈
  • 101 — Invalid Bug ID — the bug_id you handed over does not exist in the database, it's giving ghost town 👻
  • 102 — Access Denied — you don't have access to that bug_id you specified, sorry babe 🚫

✨ new ✨

my $bug = BZ::Client::Bug->new( id => $id );

Creates a shiny new bug object instance with the given ID 🎀

Heads up bestie: this does not actually touch your bugzilla server. It's all vibes and no network calls, fr fr. Purely a local lil object.

See "INSTANCE METHODS" for how to use it 👑

💖 INSTANCE METHODS 💖

Okay so this section lists the module's instance methods. Once you've got a bug object in your hands, you can use these to poke at it and mess with it — inspect and manipulate, the whole moment 🌸

🦋 id 🦋

$id = $bug->id();
$bug->id( $id );

Gets or sets the bug's ID, iconic little identifier that it is ⭐

🦋 alias 🦋

$alias = $bug->alias();
$bug->alias( $alias );

Gets or sets the bug's alias. If there's no alias, or aliases are straight up disabled in Bugzilla, you get an empty string back — so don't be surprised by the silence 💀

🦋 assigned_to 🦋

$assigned_to = $bug->assigned_to();
$bug->assigned_to( $assigned_to );

Gets or sets the login name of the user the bug is assigned to — aka who's holding the bag on this one 🫶

🦋 component 🦋

$component = $bug->component();
$bug->component( $component );

Gets or sets the name of this bug's current component 🧩

🦋 creation_time 🦋

$dateTime = $bug->creation_time();
$bug->creation_time( $dateTime );

Gets or sets the date and time when the bug was created — its birthday, basically 🎂

🦋 dupe_of 🦋

$dupeOf = $bug->dupe_of();
$bug->dupe_of( $dupeOf );

Gets or sets the bug ID of the bug this one is a duplicate of. If this bug isn't a dupe of anything, you get an empty int — no dupe, no drama ✨

🦋 is_open 🦋

$isOpen = $bug->is_open();
$bug->is_open( $isOpen );

Gets or sets whether this bug is closed. Return value (or the parameter you pass) is true (1) if the bug is open, false (0) if it's closed. Simple as 🔥

🦋 last_change_time 🦋

$lastChangeTime = $bug->last_change_time();
$bug->last_change_time( $lastChangeTime );

Gets or sets the date and time when the bug was last changed — the last time it had main character energy 🌟

🦋 priority 🦋

$priority = $bug->priority();
$bug->priority( $priority );

Gets or sets the priority of the bug — how urgently it needs attention, bestie ⏰

🦋 product 🦋

$product = $bug->product();
$bug->product( $product );

Gets or sets the name of the product this bug lives in 🏠

🦋 resolution 🦋

$resolution = $bug->resolution();
$bug->resolution( $resolution );

Gets or sets the current resolution of the bug — or an empty string if the bug is still open, because nothing's been resolved yet 💅

🦋 severity 🦋

$severity = $bug->severity();
$bug->severity( $severity );

Gets or sets the current severity of the bug — how bad it truly is 😭

🦋 status 🦋

$status = $bug->status();
$bug->status( $status );

Gets or sets the current status of the bug 📌

🦋 summary 🦋

$summary = $bug->summary();
$bug->summary( $summary );

Gets or sets the summary of this bug — the tl;dr, the one-liner, the vibe in a sentence 🎀

🌈 ATTACHMENTS & COMMENTS 🌈

Plot twist: these are implemented by other modules, not this one. It's giving delegation, and honestly? Respect 🫶

See BZ::Client::Bug::Attachment and BZ::Client::Bug::Comment 💜

⭐ TODO ⭐

Bugzilla 5.0. introduced the search_comment_tags and update_comment_tags methods, and those are yet to be specifically implemented. Not me leaving them on read 🙈 — they're coming, just not yet, iykyk.

🦋 SEE ALSO 🦋

👑 AUTHORS 👑

  • Dean Hamstead <dean@bytefoundry.com.au>
  • Jochen Wiedmann <jochen.wiedmann@gmail.com>

This software is copyright (c) 2026 by Dean Hamstad. (Yes, spelled exactly like that on the page — copying it verbatim, bestie 💅)

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay, open source 🫶

And that's the whole page, babes ✨ This lil number comes to you courtesy of perl v5.40.2, dated 2026-07-16, and it's the BZ::Client::Bug(3pm) manpage — go forth and file bugs like the icon you are 💖🦋💅

📦 where this page comes from