1BZ::Client::Bug(3pm) User Contributed Perl Documentation BZ::Client::Bug(3pm)
2
6 BZ::Client::Bug - Client side representation of a bug in Bugzilla
7
9 version 4.4004
10
12 This class provides methods for accessing and managing bugs in
13 Bugzilla.
14 my $client = BZ::Client->new( url => $url,
16 user => $user,
17 password => $password );
18 my $bugs = BZ::Client::Bug->get( $client, \%params );
20
22 Many Bugzilla Webservice methods take similar arguments. Instead of re-
23 writing the documentation for each method, we document the parameters
24 here, once, and then refer back to this documentation from the
25 individual methods where these parameters are used.
26 Limiting What Fields Are Returned
28 Many methods return an array of structs with various fields in the
29 structs. (For example, "get" in BZ::Client::Bug returns a list of bugs
30 that have fields like "id", "summary", "creation_time", etc.)
31 These parameters allow you to limit what fields are present in the
33 structs, to possibly improve performance or save some bandwidth.
34 Fields follow:
36 include_fields
38 include_fields (array) - An array of strings, representing the (case-
40 sensitive) names of fields in the return value. Only the fields
41 specified in this hash will be returned, the rest will not be included.
42 If you specify an empty array, then this function will return empty
44 hashes.
45 Invalid field names are ignored.
47 Example:
49 BZ::Client::Bug->get( $client,
51 { ids => [1], include_fields => ['id', 'name'] })
52 would return something like:
54 [{ id => 1, name => 'user@domain.com' }]
56 exclude_fields
58 exclude_fields (array) - An array of strings, representing the (case-
60 sensitive) names of fields in the return value. The fields specified
61 will not be included in the returned hashes.
62 If you specify all the fields, then this function will return empty
64 hashes.
65 Some RPC calls support specifying sub fields. If an RPC call states
67 that it support sub field restrictions, you can restrict what
68 information is returned within the first field. For example, if you
69 call Product.get with an include_fields of components.name, then only
70 the component name would be returned (and nothing else). You can
71 include the main field, and exclude a sub field.
72 Invalid field names are ignored.
74 Specifying fields here overrides "include_fields", so if you specify a
76 field in both, it will be excluded, not included.
77 Example:
79 BZ::Client::Bug->get( $client,
81 { ids => [1], exclude_fields => ['name'] })
82 would return something like:
84 [{ id => 1, real_name => 'John Smith' }]
86 shortcuts
88 There are several shortcut identifiers to ask for only certain groups
90 of fields to be returned or excluded.
91 _all
93 All possible fields are returned if "_all" is specified in
94 "include_fields".
95 _default
97 These fields are returned if "include_fields" is empty or
98 "_default" is specified. All fields described in the documentation
99 are returned by default unless specified otherwise.
100 _extra
102 These fields are not returned by default and need to be manually
103 specified in "include_fields" either by field name, or using
104 "_extra".
105 _custom
107 Only custom fields are returned if "_custom" is specified in
108 "include_fields". This is normally specific to bug objects and not
109 relevant for other returned objects.
110 Example:
112 BZ::Client::Bug->get( $client,
114 { ids => [1], include_fields => ['_all'] })
115
117 See BZ::Client::Exception
118
120 This section lists the utility functions provided by this module.
121 These deal with bug-related information, but not bugs directly.
123 fields
125 $fields = BZ::Client::Bug->fields( $client, $params )
126 @fields = BZ::Client::Bug->fields( $client, $params )
127 Get information about valid bug fields, including the lists of legal
129 values for each field.
130 History
132 Added in Bugzilla 3.6
134 Parameters
136 You can pass either field ids or field names.
138 Note: If neither ids nor names is specified, then all non-obsolete
140 fields will be returned.
141 ids ids (array) - An array of integer field ids
143 names
145 names (array) - An array of strings representing field names.
146 In addition to the parameters above, this method also accepts the
148 standard "include_fields" and "exclude_fields" arguments.
149 Returns
151 Returns an array or an arrayref of hashes, containing the following
153 keys:
154 id id (int) - An integer id uniquely identifying this field in this
156 installation only.
157 type
159 type (int) The number of the fieldtype. The following values are
160 defined:
161 0 Unknown
163 1 Free Text
164 2 Drop Down
165 3 Multiple-Selection Box
166 4 Large Text Box
167 5 Date/Time
168 6 Bug ID
169 7 Bug URLs ("See Also")
170 is_custom
171 is_custom (boolean) True when this is a custom field, false
172 otherwise.
173 name
175 name (string) The internal name of this field. This is a unique
176 identifier for this field. If this is not a custom field, then this
177 name will be the same across all Bugzilla installations.
178 display_name
180 display_name (string) The name of the field, as it is shown in the
181 user interface.
182 is_mandatory
184 is_mandatory (boolean) True if the field must have a value when
185 filing new bugs. Also, mandatory fields cannot have their value
186 cleared when updating bugs.
187 This return value was added in Bugzilla 4.0.
189 is_on_bug_entry
191 is_on_bug_entry (boolean) For custom fields, this is true if the
192 field is shown when you enter a new bug. For standard fields, this
193 is currently always false, even if the field shows up when entering
194 a bug. (To know whether or not a standard field is valid on bug
195 entry, see "create".)
196 visibility_field
198 visibility_field (string) The name of a field that controls the
199 visibility of this field in the user interface. This field only
200 appears in the user interface when the named field is equal to one
201 of the values in "visibility_values". Can be null.
202 visibility_values
204 visibility_values (array) of strings This field is only shown when
205 visibility_field matches one of these values. When visibility_field
206 is null, then this is an empty array.
207 value_field
209 value_field (string) The name of the field that controls whether or
210 not particular values of the field are shown in the user interface.
211 Can be null.
212 values
214 This is an array of hashes, representing the legal values for
215 select-type (drop-down and multiple-selection) fields. This is also
216 populated for the "component", "version", "target_milestone", and
217 "keywords" fields, but not for the "product" field (you must use
218 "get_accessible_products" in BZ::Client::Product for that).
219 For fields that aren't select-type fields, this will simply be an
221 empty array.
222 Each hash has the following keys:
224 name
226 name (string) The actual value--this is what you would specify
227 for this field in "create", etc.
228 sort_key
230 sort_key (int) Values, when displayed in a list, are sorted
231 first by this integer and then secondly by their name.
232 sortkey
234 DEPRECATED - Use "sort_key" instead.
235 Renamed to "sort_key" in Bugzilla 4.2.
237 visibility_values
239 If "value_field" is defined for this field, then this value is
240 only shown if the "value_field" is set to one of the values
241 listed in this array.
242 Note that for per-product fields, "value_field" is set to
244 "product" and "visibility_values" will reflect which product(s)
245 this value appears in.
246 is_active
248 is_active (boolean) This value is defined only for certain
249 product specific fields such as "version", "target_milestone"
250 or "component".
251 When true, the value is active, otherwise the value is not
253 active.
254 Added in Bugzilla 4.4.
256 description
258 description (string) The description of the value. This item is
259 only included for the "keywords" field.
260 is_open
262 is_open (boolean) For "bug_status" values, determines whether
263 this status specifies that the bug is "open" (true) or "closed"
264 (false). This item is only included for the "bug_status" field.
265 can_change_to
267 For "bug_status" values, this is an array of hashes that
268 determines which statuses you can transition to from this
269 status. (This item is only included for the "bug_status"
270 field.)
271 Each hash contains the following items:
273 name
275 The name of the new status
276 comment_required
278 comment_required (boolean) True if a comment is required
279 when you change a bug into this status using this
280 transition.
281 Errors:
283 51 - Invalid Field Name or ID
285 You specified an invalid field name or id.
286 legal_values
288 $values = BZ::Client::Bug->legal_values( $client, $field )
289 @values = BZ::Client::Bug->legal_values( $client, $field )
290 Tells you what values are allowed for a particular field.
292 Note: This is deprecated in Bugzilla, use "fields" instead.
294 Parameters
296 field
298 The name of the field you want information about. This should be
299 the same as the name you would use in "create", below.
300 product_id
302 If you're picking a product-specific field, you have to specify the
303 id of the product you want the values for.
304 Returns
306 values
308 An array or arrayref of strings: the legal values for this field.
309 The values will be sorted as they normally would be in Bugzilla.
310 Errors
312 106 - Invalid Product
314 You were required to specify a product, and either you didn't, or
315 you specified an invalid product (or a product that you can't
316 access).
317 108 - Invalid Field Name
319 You specified a field that doesn't exist or isn't a drop-down
320 field.
321
323 This section lists the class methods pertaining to finding and
324 retrieving bugs from your server.
325 Listed here in order of what you most likely want to do... maybe?
327 get
329 @bugs = BZ::Client::Bug->get( $client, $id );
330 $bugs = BZ::Client::Bug->get( $client, $id );
331 @bugs = BZ::Client::Bug->get( $client, \@ids );
332 $bugs = BZ::Client::Bug->get( $client, \@ids );
333 @bugs = BZ::Client::Bug->get( $client, \%params );
334 $bugs = BZ::Client::Bug->get( $client, \%params );
335 Gets information about particular bugs in the database.
337 Parameters
339 A single $id or array ref of @ids may be provided, otherwise a hash ref
341 with the following:
342 ids An array of numbers and strings.
344 If an element in the array is entirely numeric, it represents a
346 "bug_id" from the Bugzilla database to fetch. If it contains any
347 non-numeric characters, it is considered to be a bug alias instead,
348 and the bug with that alias will be loaded.
349 permissive
351 permissive (boolean) Normally, if you request any inaccessible or
352 invalid bug ids, will throw an error.
353 If this parameter is True, instead of throwing an error we return
355 an array of hashes with a "id", "faultString" and "faultCode" for
356 each bug that fails, and return normal information for the other
357 bugs that were accessible.
358 Note: marked as EXPERIMENTAL in Bugzilla 4.4
360 Added in Bugzilla 3.4.
362 Returns
364 An array or arrayref of bug instance objects with the given ID's.
366 See "INSTANCE METHODS" for how to use them.
368 FIXME missing the faults return values (added in 3.4)
370 Errors
372 100 - Invalid Bug Alias
374 If you specified an alias and there is no bug with that alias.
375 101 - Invalid Bug ID
377 The bug_id you specified doesn't exist in the database.
378 102 - Access Denied
380 You do not have access to the bug_id you specified.
381 search
383 FIXME Documentation not fully fleshed out
384 @bugs = BZ::Client::Bug->search( $client, \%params );
386 $bugs = BZ::Client::Bug->search( $client, \%params );
387 Searches for bugs matching the given parameters.
389 Parameters
391 This is just a quick example, there are lot's of fields
393 %params = (
395 'alias' => 'ACONVENIENTALIAS',
397 'assigned_to' => 'hopefullynotme@domain.local',
399 'creator' => 'littlejohnnytables@school.local',
401 'severity' => 'major',
403 'status' => 'OPEN',
405 );
407 Criteria are joined in a logical AND. That is, you will be returned
409 bugs that match all of the criteria, not bugs that match any of the
410 criteria.
411 See also
413 <https://bugzilla.readthedocs.io/en/5.0/api/core/v1/bug.html#search-bugs>
414 Returns
416 Returns an array or arrayref of bug instance objects with the given
418 ID's.
419 See "INSTANCE METHODS" for how to use them.
421 history
423 @history = BZ::Client::Bug->history( $client, \%params );
424 $history = BZ::Client::Bug->history( $client, \%params );
425 Gets the history of changes for particular bugs in the database.
427 Added in Bugzilla 3.4.
429 Parameters
431 ids An array of numbers and strings.
433 If an element in the array is entirely numeric, it represents a
435 "bug_id" from the Bugzilla database to fetch. If it contains any
436 non-numeric characters, it is considered to be a bug alias instead,
437 and the data bug with that alias will be loaded.
438 Returns
440 An array or arrayref of hashes, containing the following keys:
442 id id (int) The numeric id of the bug
444 alias
446 alias (array) The alias of this bug. If there is no alias, this
447 will be undef.
448 history
450 history (An array of hashes) - Each hash having the following keys:
451 when
453 when (DateTime) The date the bug activity/change happened.
454 who who (string) The login name of the user who performed the bug
456 change.
457 changes
459 An array of hashes which contain all the changes that happened
460 to the bug at this time (as specified by when). Each hash
461 contains the following items:
462 field_name
464 field_name (string) The name of the bug field that has
465 changed.
466 removed
468 removed (string) The previous value of the bug field which
469 has been deleted by the change.
470 added
472 added (string) The new value of the bug field which has
473 been added by the change.
474 attachment_id
476 attachment_id (int) The id of the attachment that was
477 changed. This only appears if the change was to an
478 attachment, otherwise "attachment_id" will not be present
479 in this hash.
480 Errors
482 100 - Invalid Bug Alias
484 If you specified an alias and there is no bug with that alias.
485 101 - Invalid Bug ID
487 The bug_id you specified doesn't exist in the database.
488 102 - Access Denied
490 You do not have access to the bug_id you specified.
491 possible_duplicates
493 @bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );
494 $bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );
495 Allows a user to find possible duplicate bugs based on a set of
497 keywords such as a user may use as a bug summary. Optionally the search
498 can be narrowed down to specific products.
499 History
501 Added in Bugzilla 4.0.
503 Parameters
505 summary
507 summary (string) A string of keywords defining the type of bug you
508 are trying to report. Required.
509 product
511 product (array) One or more product names to narrow the duplicate
512 search to. If omitted, all bugs are searched.
513 Returns
515 The same as "get".
517 Note that you will only be returned information about bugs that you can
519 see. Bugs that you can't see will be entirely excluded from the
520 results. So, if you want to see private bugs, you will have to first
521 log in and then call this method.
522 Errors
524 50 - Param Required
526 You must specify a value for "summary" containing a string of
527 keywords to search for duplicates.
528
530 This section lists the class methods pertaining to the creation and
531 modification of bugs.
532 Listed here in order of what you most likely want to do... maybe?
534 create
536 my $id = BZ::Client::Bug->create( $client, \%params );
537 This allows you to create a new bug in Bugzilla. If you specify any
539 invalid fields, an error will be thrown stating which field is invalid.
540 If you specify any fields you are not allowed to set, they will just be
541 set to their defaults or ignored.
542 You cannot currently set all the items here that you can set on
544 enter_bug.cgi (i.e. the web page to enter bugs).
545 The Bugzilla WebService API itself may allow you to set things other
547 than those listed here, but realize that anything undocumented is
548 UNSTABLE and will very likely change in the future.
549 History
551 Before Bugzilla 3.0.4, parameters marked as Defaulted were actually
553 Required, due to a bug in Bugzilla itself.
554 The groups argument was added in Bugzilla 4.0. Before Bugzilla 4.0,
556 bugs were only added into Mandatory groups by this method. Since
557 Bugzilla 4.0.2, passing an illegal group name will throw an error. In
558 Bugzilla 4.0 and 4.0.1, illegal group names were silently ignored.
559 The "comment_is_private" argument was added in Bugzilla 4.0. Before
561 Bugzilla 4.0, you had to use the undocumented "commentprivacy"
562 argument.
563 Error 116 was added in Bugzilla 4.0. Before that, dependency loop
565 errors had a generic code of 32000.
566 The ability to file new bugs with a "resolution" was added in Bugzilla
568 4.4.
569 Parameters
571 Some params must be set, or an error will be thrown. These params are
573 marked Required.
574 Some parameters can have defaults set in Bugzilla, by the
576 administrator. If these parameters have defaults set, you can omit
577 them. These parameters are marked Defaulted.
578 Clients that want to be able to interact uniformly with multiple
580 Bugzillas should always set both the params marked Required and those
581 marked Defaulted, because some Bugzillas may not have defaults set for
582 Defaulted parameters, and then this method will throw an error if you
583 don't specify them.
584 The descriptions of the parameters below are what they mean when
586 Bugzilla is being used to track software bugs. They may have other
587 meanings in some installations.
588 product (string) Required - The name of the product the bug is being
590 filed against.
591 product (string) Required - The name of the product the bug is
592 being filed against.
593 component
595 component (string) Required - The name of a component in the
596 product above.
597 summary
599 summary (string) Required - A brief description of the bug being
600 filed.
601 version
603 version (string) Required - A version of the product above; the
604 version the bug was found in.
605 description
607 description (string) Defaulted - The initial description for this
608 bug. Some Bugzilla installations require this to not be blank.
609 op_sys
611 op_sys (string) Defaulted - The operating system the bug was
612 discovered on.
613 platform
615 platform (string) Defaulted - What type of hardware the bug was
616 experienced on.
617 priority
619 priority (string) Defaulted - What order the bug will be fixed in
620 by the developer, compared to the developer's other bugs.
621 severity
623 severity (string) Defaulted - How severe the bug is.
624 alias
626 alias (string) - A brief alias for the bug that can be used instead
627 of a bug number when accessing this bug. Must be unique in all of
628 this Bugzilla.
629 assigned_to
631 assigned_to (username) - A user to assign this bug to, if you don't
632 want it to be assigned to the component owner.
633 cc cc (array) - An array of usernames to CC on this bug.
635 comment_is_private
637 comment_is_private (boolean) - If set to true, the description is
638 private, otherwise it is assumed to be public.
639 groups
641 groups (array) - An array (ref) of group names to put this bug
642 into. You can see valid group names on the Permissions tab of the
643 Preferences screen, or, if you are an administrator, in the Groups
644 control panel. If you don't specify this argument, then the bug
645 will be added into all the groups that are set as being "Default"
646 for this product. (If you want to avoid that, you should specify
647 "groups" as an empty array.)
648 qa_contact
650 qa_contact (username) - If this installation has QA Contacts
651 enabled, you can set the QA Contact here if you don't want to use
652 the component's default QA Contact.
653 status
655 status (string) - The status that this bug should start out as.
656 Note that only certain statuses can be set on bug creation.
657 resolution
659 resolution (string) - If you are filing a closed bug, then you will
660 have to specify a resolution. You cannot currently specify a
661 resolution of "DUPLICATE" for new bugs, though. That must be done
662 with "update".
663 target_milestone
665 target_milestone (string) - A valid target milestone for this
666 product.
667 depends_on
669 depends_on (array) - An array of bug id's that this new bug should
670 depend upon.
671 As of Bugzilla 5.0 this option isn't included in the WebService API
673 docks for =create()=, although it is mentioned in it's error codes.
674 blocks
676 blocks (array) - An array of bug id's that this new bug should
677 block.
678 As of Bugzilla 5.0 this option isn't included in the WebService API
680 docks for =create()=, although it is mentioned in it's error codes.
681 Note: In addition to the above parameters, if your installation has any
683 custom fields, you can set them just by passing in the name of the
684 field and its value as a string.
685 Returns
687 A hash with one element, "id". This is the id of the newly-filed bug.
689 Errors
691 51 - Invalid Object
693 You specified a field value that is invalid. The error message will
694 have more details.
695 103 - Invalid Alias
697 The alias you specified is invalid for some reason. See the error
698 message for more details.
699 104 - Invalid Field
701 One of the drop-down fields has an invalid value, or a value
702 entered in a text field is too long. The error message will have
703 more detail.
704 105 - Invalid Component
706 You didn't specify a component.
707 106 - Invalid Product
709 Either you didn't specify a product, this product doesn't exist, or
710 you don't have permission to enter bugs in this product.
711 107 - Invalid Summary
713 You didn't specify a summary for the bug.
714 116 - Dependency Loop
716 You specified values in the blocks or depends_on fields that would
717 cause a circular dependency between bugs.
718 120 - Group Restriction Denied
720 You tried to restrict the bug to a group which does not exist, or
721 which you cannot use with this product.
722 504 - Invalid User
724 Either the QA Contact, Assignee, or CC lists have some invalid user
725 in them. The error message will have more details.
726 update
728 my $id = BZ::Client::Bug->update( $client, \%params );
729 Allows you to update the fields of a bug.
731 (Your Bugzilla server may automatically sends emails out about the
733 changes)
734 History
736 Added in Bugzilla 4.0.
738 Parameters
740 ids ids (Array of "int"s or "string"s) - The ids or aliases of the
742 bugs that you want to modify.
743 Note: All following fields specify the values you want to set on
745 the bugs you are updating.
746 alias
748 alias (string) - The alias of the bug. You can only set this if you
749 are modifying a single bug. If there is more than one bug specified
750 in "ids", passing in a value for "alias" will cause an error to be
751 thrown.
752 assigned_to
754 assigned_to (string) - The full login name of the user this bug is
755 assigned to.
756 blocks
758 blocks (hash) - These specify the bugs that this bug blocks. To
759 set these, you should pass a hash as the value. The hash may
760 contain the following fields:
761 add add (Array of "int"s) - Bug ids to add to this field.
763 remove
765 remove (Array of "int"s) - Bug ids to remove from this field.
766 If the bug ids are not already in the field, they will be
767 ignored.
768 set set (Array of "int"s) - An exact set of bug ids to set this
770 field to, overriding the current value. If you specify "set",
771 then "add" and "remove" will be ignored.
772 depends_on
774 depends_on (hash) - These specify the bugs that this depends on.
775 To set these, you should pass a hash as the value. The hash may
776 contain the following fields:
777 add add (Array of "int"s) - Bug ids to add to this field.
779 remove
781 remove (Array of "int"s) - Bug ids to remove from this field.
782 If the bug ids are not already in the field, they will be
783 ignored.
784 set set (Array of "int"s) - An exact set of bug ids to set this
786 field to, overriding the current value. If you specify "set",
787 then "add" and "remove" will be ignored.
788 cc cc (hash) - The users on the cc list. To modify this field, pass a
790 hash, which may have the following fields:
791 add add (Array of "string"s) - User names to add to the CC list.
793 They must be full user names, and an error will be thrown if
794 you pass in an invalid user name.
795 remove
797 remove (Array of "string"s) - User names to remove from the CC
798 list. They must be full user names, and an error will be thrown
799 if you pass in an invalid user name.
800 is_cc_accessible
802 is_cc_accessible (boolean) - Whether or not users in the CC list
803 are allowed to access the bug, even if they aren't in a group that
804 can normally access the bug.
805 comment
807 comment (hash) - A comment on the change. The hash may contain the
808 following fields:
809 body
811 body (string) - The actual text of the comment. Note: For
812 compatibility with the parameters to "add_comment", you can
813 also call this field "comment", if you wish.
814 is_private
816 is_private (boolean) - Whether the comment is private or not.
817 If you try to make a comment private and you don't have the
818 permission to, an error will be thrown.
819 comment_is_private
821 comment_is_private (hash) - This is how you update the privacy of
822 comments that are already on a bug. This is a hash, where the keys
823 are the "int" id of comments (not their count on a bug, like #1,
824 #2, #3, but their globally-unique id, as returned by "comments")
825 and the value is a "boolean" which specifies whether that comment
826 should become private ("true") or public ("false").
827 The comment ids must be valid for the bug being updated. Thus, it
829 is not practical to use this while updating multiple bugs at once,
830 as a single comment id will never be valid on multiple bugs.
831 component component (string) - The Component the bug is in.
833 deadline
834 deadline (string) - The Deadline field--a date specifying when the
835 bug must be completed by, in the format "YYYY-MM-DD".
836 dupe_of
838 dupe_of (int) - The bug that this bug is a duplicate of. If you
839 want to mark a bug as a duplicate, the safest thing to do is to set
840 this value and not set the "status" or "resolution" fields. They
841 will automatically be set by Bugzilla to the appropriate values for
842 duplicate bugs.
843 estimated_time
845 estimated_time (double) - The total estimate of time required to
846 fix the bug, in hours. This is the total estimate, not the amount
847 of time remaining to fix it.
848 groups
850 groups (hash) - The groups a bug is in. To modify this field, pass
851 a hash, which may have the following fields:
852 add add (Array of "string"s) - The names of groups to add. Passing
854 in an invalid group name or a group that you cannot add to this
855 bug will cause an error to be thrown.
856 remove
858 remove (Array of "string"s) - The names of groups to remove.
859 Passing in an invalid group name or a group that you cannot
860 remove from this bug will cause an error to be thrown.
861 keywords
863 keywords (hash) - Keywords on the bug. To modify this field, pass
864 a hash, which may have the following fields:
865 add add (An array of "string"s) - The names of keywords to add to
867 the field on the bug. Passing something that isn't a valid
868 keyword name will cause an error to be thrown.
869 remove
871 remove (An array of "string"s) - The names of keywords to
872 remove from the field on the bug. Passing something that isn't
873 a valid keyword name will cause an error to be thrown.
874 set set (An array of "string"s) - An exact set of keywords to set
876 the field to, on the bug. Passing something that isn't a valid
877 keyword name will cause an error to be thrown. Specifying "set"
878 overrides "add" and "remove".
879 op_sys
881 op_sys (string) - The Operating System ("OS") field on the bug.
882 platform
884 platform (string) - The Platform or "Hardware" field on the bug.
885 priority
887 priority (string) - The Priority field on the bug.
888 product
890 product (string) - The name of the product that the bug is in. If
891 you change this, you will probably also want to change
892 "target_milestone", "version", and "component", since those have
893 different legal values in every product.
894 If you cannot change the "target_milestone" field, it will be reset
896 to the default for the product, when you move a bug to a new
897 product.
898 You may also wish to add or remove groups, as which groups are
900 valid on a bug depends on the product. Groups that are not valid in
901 the new product will be automatically removed, and groups which are
902 mandatory in the new product will be automaticaly added, but no
903 other automatic group changes will be done.
904 Note: that users can only move a bug into a product if they would
906 normally have permission to file new bugs in that product.
907 qa_contact
909 qa_contact (string) - The full login name of the bug's QA Contact.
910 is_creator_accessible
912 is_creator_accessible (boolean) - Whether or not the bug's reporter
913 is allowed to access the bug, even if he or she isn't in a group
914 that can normally access the bug.
915 remaining_time
917 remaining_time (double) - How much work time is remaining to fix
918 the bug, in hours. If you set "work_time" but don't explicitly set
919 "remaining_time", then the "work_time" will be deducted from the
920 bug's "remaining_time".
921 reset_assigned_to
923 reset_assigned_to (boolean) - If true, the "assigned_to" field will
924 be reset to the default for the component that the bug is in. (If
925 you have set the component at the same time as using this, then the
926 component used will be the new component, not the old one.)
927 reset_qa_contact
929 reset_qa_contact (boolean) - If true, the "qa_contact" field will
930 be reset to the default for the component that the bug is in. (If
931 you have set the component at the same time as using this, then the
932 component used will be the new component, not the old one.)
933 resolution
935 resolution (string) The current resolution. May only be set if you
936 are closing a bug or if you are modifying an already-closed bug.
937 Attempting to set the resolution to any value (even an empty or
938 null string) on an open bug will cause an error to be thrown.
939 If you change the "status" field to an open status, the resolution
941 field will automatically be cleared, so you don't have to clear it
942 manually.
943 see_also
945 see_also (hash) - The See Also field on a bug, specifying URLs to
946 bugs in other bug trackers. To modify this field, pass a hash,
947 which may have the following fields:
948 add add (An array of "string"s) - URLs to add to the field. Each
950 URL must be a valid URL to a bug-tracker, or an error will be
951 thrown.
952 remove
954 remove (An array of "string"s) - URLs to remove from the field.
955 Invalid URLs will be ignored.
956 severity
958 severity (string) - The Severity field of a bug.
959 status
961 status (string) - The status you want to change the bug to. Note
962 that if a bug is changing from open to closed, you should also
963 specify a resolution.
964 summary
966 summary (string) - The Summary field of the bug.
967 target_milestone
969 target_milestone (string) - The bug's Target Milestone.
970 url url (string) - The "URL" field of a bug.
972 version
974 version (string) - The bug's Version field.
975 whiteboard
977 whiteboard (string) - The Status Whiteboard field of a bug.
978 work_time
980 work_time (double) - The number of hours worked on this bug as part
981 of this change. If you set "work_time" but don't explicitly set
982 "remaining_time", then the "work_time" will be deducted from the
983 bug's remaining_time.
984 Note: You can also set the value of any custom field by passing its
986 name as a parameter, and the value to set the field to. For multiple-
987 selection fields, the value should be an array of strings.
988 Returns
990 A "hash" with a single field, "bugs". This points to an array of hashes
992 with the following fields:
993 id id (int) - The id of the bug that was updated.
995 alias
997 alias (string) - The alias of the bug that was updated, if this bug
998 has an alias.
999 last_change_time
1001 last_change_time (DateTime) - The exact time that this update was
1002 done at, for this bug. If no update was done (that is, no fields
1003 had their values changed and no comment was added) then this will
1004 instead be the last time the bug was updated.
1005 changes
1007 changes (hash) - The changes that were actually done on this bug.
1008 The keys are the names of the fields that were changed, and the
1009 values are a hash with two keys:
1010 added
1012 added (string) - The values that were added to this field,
1013 possibly a comma-and-space-separated list if multiple values
1014 were added.
1015 removed
1017 removed (string) - The values that were removed from this
1018 field, possibly a comma-and-space-separated list if multiple
1019 values were removed.
1020 Here's an example of what a return value might look like:
1022 {
1024 bugs => [
1025 {
1026 id => 123,
1027 alias => 'foo',
1028 last_change_time => '2010-01-01T12:34:56',
1029 changes => {
1030 status => {
1031 removed => 'NEW',
1032 added => 'ASSIGNED'
1033 },
1034 keywords => {
1035 removed => 'bar',
1036 added => 'qux, quo, qui',
1037 },
1038 },
1039 },
1040 ],
1041 }
1042 Note: Currently, some fields are not tracked in changes: "comment",
1044 "comment_is_private", and "work_time". This means that they will not
1045 show up in the return value even if they were successfully updated.
1046 This may change in a future version of Bugzilla.
1047 Errors
1049 This function can throw all of the errors that "get", "create", and
1051 "add_comment" can throw, plus:
1052 50 - Empty Field
1054 You tried to set some field to be empty, but that field cannot be
1055 empty. The error message will have more details.
1056 52 - Input Not A Number
1058 You tried to set a numeric field to a value that wasn't numeric.
1059 54 - Number Too Large
1061 You tried to set a numeric field to a value larger than that field
1062 can accept.
1063 55 - Number Too Small
1065 You tried to set a negative value in a numeric field that does not
1066 accept negative values.
1067 56 - Bad Date/Time
1069 You specified an invalid date or time in a date/time field (such as
1070 the deadline field or a custom date/time field).
1071 112 - See Also Invalid
1073 You attempted to add an invalid value to the see_also field.
1074 115 - Permission Denied
1076 You don't have permission to change a particular field to a
1077 particular value. The error message will have more detail.
1078 116 - Dependency Loop
1080 You specified a value in the blocks or depends_on fields that
1081 causes a dependency loop.
1082 117 - Invalid Comment ID
1084 You specified a comment id in comment_is_private that isn't on this
1085 bug.
1086 118 - Duplicate Loop
1088 You specified a value for dupe_of that causes an infinite loop of
1089 duplicates.
1090 119 - dupe_of Required
1092 You changed the resolution to DUPLICATE but did not specify a value
1093 for the dupe_of field.
1094 120 - Group Add/Remove Denied
1096 You tried to add or remove a group that you don't have permission
1097 to modify for this bug, or you tried to add a group that isn't
1098 valid in this product.
1099 121 - Resolution Required
1101 You tried to set the status field to a closed status, but you
1102 didn't specify a resolution.
1103 122 - Resolution On Open Status
1105 This bug has an open status, but you specified a value for the
1106 resolution field.
1107 123 - Invalid Status Transition
1109 You tried to change from one status to another, but the status
1110 workflow rules don't allow that change.
1111 update_see_also
1113 @changes = BZ::Client::Bug->update_see_also( $client, \%params );
1114 $changes = BZ::Client::Bug->update_see_also( $client, \%params );
1115 Adds or removes URLs for the See Also field on bugs. These URLs must
1117 point to some valid bug in some Bugzilla installation or in Launchpad.
1118 History
1120 This is marked as EXPERIMENTAL in Bugzilla 4.4
1122 Added in Bugzilla 3.4.
1124 Parameters
1126 ids An array of integers or strings. The IDs or aliases of bugs that
1128 you want to modify.
1129 add Array of strings. URLs to Bugzilla bugs. These URLs will be added
1131 to the See Also field.
1132 If the URLs don't start with "http://" or "https://", it will be
1134 assumed that "http://" should be added to the beginning of the
1135 string.
1136 It is safe to specify URLs that are already in the See Also field
1138 on a bug as they will just be silently ignored.
1139 remove
1141 An array of strings. These URLs will be removed from the See Also
1142 field. You must specify the full URL that you want removed.
1143 However, matching is done case-insensitively, so you don't have to
1144 specify the URL in exact case, if you don't want to.
1145 If you specify a URL that is not in the See Also field of a
1147 particular bug, it will just be silently ignored. Invaild URLs are
1148 currently silently ignored, though this may change in some future
1149 version of Bugzilla.
1150 Note: If you specify the same URL in both "add" and "remove", it will
1152 be added. (That is, "add" overrides "remove".)
1153 Returns
1155 A hash or hashref where the keys are numeric bug ids and the contents
1157 are a hash with one key, "see_also".
1158 "see_also" points to a hash, which contains two keys, "added" and
1160 "removed".
1161 These are arrays of strings, representing the actual changes that were
1163 made to the bug.
1164 Here's a diagram of what the return value looks like for updating bug
1166 ids 1 and 2:
1167 {
1169 1 => {
1170 see_also => {
1171 added => [(an array of bug URLs)],
1172 removed => [(an array of bug URLs)],
1173 }
1174 },
1175 2 => {
1176 see_also => {
1177 added => [(an array of bug URLs)],
1178 removed => [(an array of bug URLs)],
1179 }
1180 }
1181 }
1182 This return value allows you to tell what this method actually did.
1184 It is in this format to be compatible with the return value of a future
1186 "update" method.
1187 Errors
1189 100 - Invalid Bug Alias
1191 If you specified an alias and there is no bug with that alias.
1192 101 - Invalid Bug ID
1194 The bug_id you specified doesn't exist in the database.
1195 102 - Access Denied
1197 You do not have access to the bug_id you specified.
1198 109 - Bug Edit Denied
1200 You did not have the necessary rights to edit the bug.
1201 112 - Invalid Bug URL
1203 One of the URLs you provided did not look like a valid bug URL.
1204 115 - See Also Edit Denied
1206 You did not have the necessary rights to edit the See Also field
1207 for this bug.
1208 Before Bugzilla 3.6, error 115 had a generic error code of 32000.
1210 update_tags
1212 @changes = BZ::Client::Bug->update_tags( $client, \%params );
1213 $changes = BZ::Client::Bug->update_tags( $client, \%params );
1214 Adds or removes tags on bugs.
1216 Unlike Keywords which are global and visible by all users, Tags are
1218 personal and can only be viewed and edited by their author. Editing
1219 them won't send any notification to other users. Use them to tag and
1220 keep track of bugs.
1221 Bugzilla will lower case the text of the tags. This doesn't seem to be
1223 documented.
1224 Reminder: to retrieve these tags, specify "_extra" or the field name
1226 "tags" in "include_fields" when searching etc.
1227 History
1229 This is marked as UNSTABLE in Bugzilla 4.4
1231 Added in Bugzilla 4.4.
1233 Parameters
1235 ids An array of ints and/or strings--the ids or aliases of bugs that
1237 you want to add or remove tags to. All the tags will be added or
1238 removed to all these bugs.
1239 tags
1241 A hash representing tags to be added and/or removed. The hash has
1242 the following fields:
1243 add An array of strings representing tag names to be added to the
1245 bugs.
1246 It is safe to specify tags that are already associated with the
1248 bugs as they will just be silently ignored.
1249 remove
1251 An array of strings representing tag names to be removed from
1252 the bugs.
1253 It is safe to specify tags that are not associated with any
1255 bugs as they will just be silently ignored.
1256 Returns
1258 A hash or hashref where the keys are numeric bug ids and the contents
1260 are a hash with one key, "tags".
1261 "tags" points to a hash, which contains two keys, "added" and
1263 "removed".
1264 These are arrays of strings, representing the actual changes that were
1266 made to the bug.
1267 Here's a diagram of what the return value looks like for updating bug
1269 ids 1 and 2:
1270 {
1272 1 => {
1273 tags => {
1274 added => [(an array of tags)],
1275 removed => [(an array of tags)],
1276 }
1277 },
1278 2 => {
1279 tags => {
1280 added => [(an array of tags)],
1281 removed => [(an array of tags)],
1282 }
1283 }
1284 }
1285 This return value allows you to tell what this method actually did.
1287 Errors
1289 100 - Invalid Bug Alias
1291 If you specified an alias and there is no bug with that alias.
1292 101 - Invalid Bug ID
1294 The bug_id you specified doesn't exist in the database.
1295 102 - Access Denied
1297 You do not have access to the bug_id you specified.
1298 new
1300 my $bug = BZ::Client::Bug->new( id => $id );
1301 Creates a new bug object instance with the given ID.
1303 Note: Doesn't actually touch your bugzilla server.
1305 See "INSTANCE METHODS" for how to use it.
1307
1309 This section lists the modules instance methods.
1310 Once you have a bug object, you can use these methods to inspect and
1312 manipulate the bug.
1313 id
1315 $id = $bug->id();
1316 $bug->id( $id );
1317 Gets or sets the bugs ID.
1319 alias
1321 $alias = $bug->alias();
1322 $bug->alias( $alias );
1323 Gets or sets the bugs alias. If there is no alias or aliases are
1325 disabled in Bugzilla, this will be an empty string.
1326 assigned_to
1328 $assigned_to = $bug->assigned_to();
1329 $bug->assigned_to( $assigned_to );
1330 Gets or sets the login name of the user to whom the bug is assigned.
1332 component
1334 $component = $bug->component();
1335 $bug->component( $component );
1336 Gets or sets the name of the current component of this bug.
1338 creation_time
1340 $dateTime = $bug->creation_time();
1341 $bug->creation_time( $dateTime );
1342 Gets or sets the date and time, when the bug was created.
1344 dupe_of
1346 $dupeOf = $bug->dupe_of();
1347 $bug->dupe_of( $dupeOf );
1348 Gets or sets the bug ID of the bug that this bug is a duplicate of. If
1350 this bug isn't a duplicate of any bug, this will be an empty int.
1351 is_open
1353 $isOpen = $bug->is_open();
1354 $bug->is_open( $isOpen );
1355 Gets or sets, whether this bug is closed. The return value, or
1357 parameter value is true (1) if this bug is open, false (0) if it is
1358 closed.
1359 last_change_time
1361 $lastChangeTime = $bug->last_change_time();
1362 $bug->last_change_time( $lastChangeTime );
1363 Gets or sets the date and time, when the bug was last changed.
1365 priority
1367 $priority = $bug->priority();
1368 $bug->priority( $priority );
1369 Gets or sets the priority of the bug.
1371 product
1373 $product = $bug->product();
1374 $bug->product( $product );
1375 Gets or sets the name of the product this bug is in.
1377 resolution
1379 $resolution = $bug->resolution();
1380 $bug->resolution( $resolution );
1381 Gets or sets the current resolution of the bug, or an empty string if
1383 the bug is open.
1384 severity
1386 $severity = $bug->severity();
1387 $bug->severity( $severity );
1388 Gets or sets the current severity of the bug.
1390 status
1392 $status = $bug->status();
1393 $bug->status( $status );
1394 Gets or sets the current status of the bug.
1396 summary
1398 $summary = $bug->summary();
1399 $bug->summary( $summary );
1400 Gets or sets the summary of this bug.
1402
1404 These are implemented by other modules.
1405 See BZ::Client::Bug::Attachment and BZ::Client::Bug::Comment
1407
1409 Bugzilla 5.0. introduced the "search_comment_tags" and
1410 "update_comment_tags" methods, these are yet to be specifically
1411 implemented.
1412
1414 BZ::Client, BZ::Client::Bug::Attachment, BZ::Client::Bug::Comment
1415 BZ::Client::API, Bugzilla WebService 4.4 API
1417 <https://www.bugzilla.org/docs/4.4/en/html/api/Bugzilla/WebService/Bug.html>,
1418 Bugzilla WebService 5.0 API
1419 <https://www.bugzilla.org/docs/5.0/en/html/integrating/api/Bugzilla/WebService/Bug.html>
1420
1422 • Dean Hamstead <dean@bytefoundry.com.au>
1423 • Jochen Wiedmann <jochen.wiedmann@gmail.com>
1425
1427 This software is copyright (c) 2021 by Dean Hamstad.
1428 This is free software; you can redistribute it and/or modify it under
1430 the same terms as the Perl 5 programming language system itself.
1431perl v5.38.0 2023-07-20 BZ::Client::Bug(3pm)