1BZ::Client::Bug(3)    User Contributed Perl Documentation   BZ::Client::Bug(3)
2
3
4

NAME

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

VERSION

9       version 4.4002
10

SYNOPSIS

12       This class provides methods for accessing and managing bugs in
13       Bugzilla.
14
15         my $client = BZ::Client->new( url      => $url,
16                                       user     => $user,
17                                       password => $password );
18
19         my $bugs = BZ::Client::Bug->get( $client, \%params );
20

COMMON PARAMETERS

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
27   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
32       These parameters allow you to limit what fields are present in the
33       structs, to possibly improve performance or save some bandwidth.
34
35       Fields follow:
36
37       include_fields
38
39       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
43       If you specify an empty array, then this function will return empty
44       hashes.
45
46       Invalid field names are ignored.
47
48       Example:
49
50        BZ::Client::Bug->get( $client,
51           { ids => [1], include_fields => ['id', 'name'] })
52
53       would return something like:
54
55        [{ id => 1, name => 'user@domain.com' }]
56
57       exclude_fields
58
59       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
63       If you specify all the fields, then this function will return empty
64       hashes.
65
66       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
73       Invalid field names are ignored.
74
75       Specifying fields here overrides "include_fields", so if you specify a
76       field in both, it will be excluded, not included.
77
78       Example:
79
80        BZ::Client::Bug->get( $client,
81           { ids => [1], exclude_fields => ['name'] })
82
83       would return something like:
84
85        [{ id => 1, real_name => 'John Smith' }]
86
87       shortcuts
88
89       There are several shortcut identifiers to ask for only certain groups
90       of fields to be returned or excluded.
91
92       _all
93           All possible fields are returned if "_all" is specified in
94           "include_fields".
95
96       _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
101       _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
106       _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
111       Example:
112
113        BZ::Client::Bug->get( $client,
114           { ids => [1], include_fields => ['_all'] })
115

EXCEPTION HANDLING

117       See BZ::Client::Exception
118

UTILITY FUNCTIONS

120       This section lists the utility functions provided by this module.
121
122       These deal with bug-related information, but not bugs directly.
123
124   fields
125        $fields = BZ::Client::Bug->fields( $client, $params )
126        @fields = BZ::Client::Bug->fields( $client, $params )
127
128       Get information about valid bug fields, including the lists of legal
129       values for each field.
130
131       History
132
133       Added in Bugzilla 3.6
134
135       Parameters
136
137       You can pass either field ids or field names.
138
139       Note: If neither ids nor names is specified, then all non-obsolete
140       fields will be returned.
141
142       ids ids (array) - An array of integer field ids
143
144       names
145           names (array) - An array of strings representing field names.
146
147       In addition to the parameters above, this method also accepts the
148       standard "include_fields" and "exclude_fields" arguments.
149
150       Returns
151
152       Returns an array or an arrayref of hashes, containing the following
153       keys:
154
155       id  id (int) - An integer id uniquely identifying this field in this
156           installation only.
157
158       type
159           type (int) The number of the fieldtype. The following values are
160           defined:
161
162           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
174       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
179       display_name
180           display_name  (string) The name of the field, as it is shown in the
181           user interface.
182
183       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
188           This return value was added in Bugzilla 4.0.
189
190       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
197       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
203       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
208       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
213       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
220           For fields that aren't select-type fields, this will simply be an
221           empty array.
222
223           Each hash has the following keys:
224
225           name
226               name (string) The actual value--this is what you would specify
227               for this field in "create", etc.
228
229           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
233           sortkey
234               DEPRECATED - Use "sort_key" instead.
235
236               Renamed to "sort_key" in Bugzilla 4.2.
237
238           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
243               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
247           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
252               When true, the value is active, otherwise the value is not
253               active.
254
255               Added in Bugzilla 4.4.
256
257           description
258               description (string) The description of the value. This item is
259               only included for the "keywords" field.
260
261           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
266           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
272               Each hash contains the following items:
273
274               name
275                   The name of the new status
276
277               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
282       Errors:
283
284       51 - Invalid Field Name or ID
285           You specified an invalid field name or id.
286
287   legal_values
288        $values = BZ::Client::Bug->legal_values( $client, $field )
289        @values = BZ::Client::Bug->legal_values( $client, $field )
290
291       Tells you what values are allowed for a particular field.
292
293       Note: This is deprecated in Bugzilla, use "fields" instead.
294
295       Parameters
296
297       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
301       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
305       Returns
306
307       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
311       Errors
312
313       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
318       108 - Invalid Field Name
319           You specified a field that doesn't exist or isn't a drop-down
320           field.
321

FUNCTIONS FOR FINDING AND RETRIEVING BUGS

323       This section lists the class methods pertaining to finding and
324       retrieving bugs from your server.
325
326       Listed here in order of what you most likely want to do... maybe?
327
328   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
336       Gets information about particular bugs in the database.
337
338       Parameters
339
340       A single $id or array ref of @ids may be provided, otherwise a hash ref
341       with the following:
342
343       ids An array of numbers and strings.
344
345           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
350       permissive
351           permissive (boolean) Normally, if you request any inaccessible or
352           invalid bug ids, will throw an error.
353
354           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
359           Note: marked as EXPERIMENTAL in Bugzilla 4.4
360
361           Added in Bugzilla 3.4.
362
363       Returns
364
365       An array or arrayref of bug instance objects with the given ID's.
366
367       See "INSTANCE METHODS" for how to use them.
368
369       FIXME missing the faults return values (added in 3.4)
370
371       Errors
372
373       100 - Invalid Bug Alias
374           If you specified an alias and there is no bug with that alias.
375
376       101 - Invalid Bug ID
377           The bug_id you specified doesn't exist in the database.
378
379       102 - Access Denied
380           You do not have access to the bug_id you specified.
381
382   search
383       FIXME Documentation not fully fleshed out
384
385        @bugs = BZ::Client::Bug->search( $client, \%params );
386        $bugs = BZ::Client::Bug->search( $client, \%params );
387
388       Searches for bugs matching the given parameters.
389
390       Parameters
391
392       This is just a quick example, there are lot's of fields
393
394        %params = (
395
396          'alias' => 'ACONVENIENTALIAS',
397
398          'assigned_to' => 'hopefullynotme@domain.local',
399
400          'creator' => 'littlejohnnytables@school.local',
401
402          'severity' => 'major',
403
404          'status' => 'OPEN',
405
406        );
407
408       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
412       See also
413       <https://bugzilla.readthedocs.io/en/5.0/api/core/v1/bug.html#search-bugs>
414
415       Returns
416
417       Returns an array or arrayref of bug instance objects with the given
418       ID's.
419
420       See "INSTANCE METHODS" for how to use them.
421
422   history
423        @history = BZ::Client::Bug->history( $client, \%params );
424        $history = BZ::Client::Bug->history( $client, \%params );
425
426       Gets the history of changes for particular bugs in the database.
427
428       Added in Bugzilla 3.4.
429
430       Parameters
431
432       ids An array of numbers and strings.
433
434           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
439       Returns
440
441       An array or arrayref of hashes, containing the following keys:
442
443       id  id (int) The numeric id of the bug
444
445       alias
446           alias (array) The alias of this bug. If there is no alias, this
447           will be undef.
448
449       history
450           history (An array of hashes) - Each hash having the following keys:
451
452           when
453               when (DateTime) The date the bug activity/change happened.
454
455           who who (string) The login name of the user who performed the bug
456               change.
457
458           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
463               field_name
464                   field_name (string) The name of the bug field that has
465                   changed.
466
467               removed
468                   removed (string) The previous value of the bug field which
469                   has been deleted by the change.
470
471               added
472                   added (string) The new value of the bug field which has
473                   been added by the change.
474
475               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
481       Errors
482
483       100 - Invalid Bug Alias
484           If you specified an alias and there is no bug with that alias.
485
486       101 - Invalid Bug ID
487           The bug_id you specified doesn't exist in the database.
488
489       102 - Access Denied
490           You do not have access to the bug_id you specified.
491
492   possible_duplicates
493        @bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );
494        $bugs = BZ::Client::Bug->possible_duplicates( $client, \%params );
495
496       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
500       History
501
502       Added in Bugzilla 4.0.
503
504       Parameters
505
506       summary
507           summary (string) A string of keywords defining the type of bug you
508           are trying to report. Required.
509
510       product
511           product (array) One or more product names to narrow the duplicate
512           search to. If omitted, all bugs are searched.
513
514       Returns
515
516       The same as "get".
517
518       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
523       Errors
524
525       50 - Param Required
526           You must specify a value for "summary" containing a string of
527           keywords to search for duplicates.
528

FUNCTIONS FOR CREATING AND MODIFYING BUGS

530       This section lists the class methods pertaining to the creation and
531       modification of bugs.
532
533       Listed here in order of what you most likely want to do... maybe?
534
535   create
536         my $id = BZ::Client::Bug->create( $client, \%params );
537
538       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
543       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
546       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
550       History
551
552       Before Bugzilla 3.0.4, parameters marked as Defaulted were actually
553       Required, due to a bug in Bugzilla itself.
554
555       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
560       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
564       Error 116 was added in Bugzilla 4.0. Before that, dependency loop
565       errors had a generic code of 32000.
566
567       The ability to file new bugs with a "resolution" was added in Bugzilla
568       4.4.
569
570       Parameters
571
572       Some params must be set, or an error will be thrown. These params are
573       marked Required.
574
575       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
579       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
585       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
589       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
594       component
595           component (string) Required - The name of a component in the
596           product above.
597
598       summary
599           summary (string) Required - A brief description of the bug being
600           filed.
601
602       version
603           version (string) Required - A version of the product above; the
604           version the bug was found in.
605
606       description
607           description (string) Defaulted - The initial description for this
608           bug. Some Bugzilla installations require this to not be blank.
609
610       op_sys
611           op_sys (string) Defaulted - The operating system the bug was
612           discovered on.
613
614       platform
615           platform (string) Defaulted - What type of hardware the bug was
616           experienced on.
617
618       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
622       severity
623           severity (string) Defaulted - How severe the bug is.
624
625       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
630       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
634       cc  cc (array) - An array of usernames to CC on this bug.
635
636       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
640       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
649       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
654       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
658       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
664       target_milestone
665           target_milestone (string) - A valid target milestone for this
666           product.
667
668       depends_on
669           depends_on (array) - An array of bug id's that this new bug should
670           depend upon.
671
672           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
675       blocks
676           blocks (array) - An array of bug id's that this new bug should
677           block.
678
679           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
682       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
686       Returns
687
688       A hash with one element, "id". This is the id of the newly-filed bug.
689
690       Errors
691
692       51 - Invalid Object
693           You specified a field value that is invalid. The error message will
694           have more details.
695
696       103 - Invalid Alias
697           The alias you specified is invalid for some reason. See the error
698           message for more details.
699
700       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
705       105 - Invalid Component
706           You didn't specify a component.
707
708       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
712       107 - Invalid Summary
713           You didn't specify a summary for the bug.
714
715       116 - Dependency Loop
716           You specified values in the blocks or depends_on fields that would
717           cause a circular dependency between bugs.
718
719       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
723       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
727   update
728         my $id = BZ::Client::Bug->update( $client, \%params );
729
730       Allows you to update the fields of a bug.
731
732       (Your Bugzilla server may automatically sends emails out about the
733       changes)
734
735       History
736
737       Added in Bugzilla 4.0.
738
739       Parameters
740
741       ids ids (Array of "int"s or "string"s) -  The ids or aliases of the
742           bugs that you want to modify.
743
744           Note: All following fields specify the values you want to set on
745           the bugs you are updating.
746
747       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
753       assigned_to
754           assigned_to (string) -  The full login name of the user this bug is
755           assigned to.
756
757       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
762           add add (Array of "int"s) - Bug ids to add to this field.
763
764           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
769           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
773       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
778           add add (Array of "int"s) - Bug ids to add to this field.
779
780           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
785           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
789       cc  cc (hash) -  The users on the cc list. To modify this field, pass a
790           hash, which may have the following fields:
791
792           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
796           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
801       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
806       comment
807           comment (hash) -  A comment on the change. The hash may contain the
808           following fields:
809
810           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
815           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
820       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
828           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
832       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
837       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
844       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
849       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
853           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
857           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
862       keywords
863           keywords (hash) -  Keywords on the bug. To modify this field, pass
864           a hash, which may have the following fields:
865
866           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
870           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
875           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
880       op_sys
881           op_sys (string) -  The Operating System ("OS") field on the bug.
882
883       platform
884           platform (string) - The Platform or "Hardware" field on the bug.
885
886       priority
887           priority (string) -  The Priority field on the bug.
888
889       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
895           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
899           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
905           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
908       qa_contact
909           qa_contact (string) - The full login name of the bug's QA Contact.
910
911       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
916       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
922       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
928       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
934       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
940           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
944       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
949           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
953           remove
954               remove (An array of "string"s) - URLs to remove from the field.
955               Invalid URLs will be ignored.
956
957       severity
958           severity (string) - The Severity field of a bug.
959
960       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
965       summary
966           summary (string) - The Summary field of the bug.
967
968       target_milestone
969           target_milestone (string) -  The bug's Target Milestone.
970
971       url url (string) - The "URL" field of a bug.
972
973       version
974           version (string) -  The bug's Version field.
975
976       whiteboard
977           whiteboard (string) - The Status Whiteboard field of a bug.
978
979       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
985       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
989       Returns
990
991       A "hash" with a single field, "bugs". This points to an array of hashes
992       with the following fields:
993
994       id  id (int) - The id of the bug that was updated.
995
996       alias
997           alias (string) - The alias of the bug that was updated, if this bug
998           has an alias.
999
1000       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
1006       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
1011           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
1016           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
1021       Here's an example of what a return value might look like:
1022
1023        {
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
1043       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
1048       Errors
1049
1050       This function can throw all of the errors that "get", "create", and
1051       "add_comment" can throw, plus:
1052
1053       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
1057       52 - Input Not A Number
1058           You tried to set a numeric field to a value that wasn't numeric.
1059
1060       54 - Number Too Large
1061           You tried to set a numeric field to a value larger than that field
1062           can accept.
1063
1064       55 - Number Too Small
1065           You tried to set a negative value in a numeric field that does not
1066           accept negative values.
1067
1068       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
1072       112 - See Also Invalid
1073           You attempted to add an invalid value to the see_also field.
1074
1075       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
1079       116 - Dependency Loop
1080           You specified a value in the blocks or depends_on fields that
1081           causes a dependency loop.
1082
1083       117 - Invalid Comment ID
1084           You specified a comment id in comment_is_private that isn't on this
1085           bug.
1086
1087       118 - Duplicate Loop
1088           You specified a value for dupe_of that causes an infinite loop of
1089           duplicates.
1090
1091       119 - dupe_of Required
1092           You changed the resolution to DUPLICATE but did not specify a value
1093           for the dupe_of field.
1094
1095       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
1100       121 - Resolution Required
1101           You tried to set the status field to a closed status, but you
1102           didn't specify a resolution.
1103
1104       122 - Resolution On Open Status
1105           This bug has an open status, but you specified a value for the
1106           resolution field.
1107
1108       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
1112   update_see_also
1113        @changes = BZ::Client::Bug->update_see_also( $client, \%params );
1114        $changes = BZ::Client::Bug->update_see_also( $client, \%params );
1115
1116       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
1119       History
1120
1121       This is marked as EXPERIMENTAL in Bugzilla 4.4
1122
1123       Added in Bugzilla 3.4.
1124
1125       Parameters
1126
1127       ids An array of integers or strings. The IDs or aliases of bugs that
1128           you want to modify.
1129
1130       add Array of strings. URLs to Bugzilla bugs. These URLs will be added
1131           to the See Also field.
1132
1133           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
1137           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
1140       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
1146           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
1151       Note: If you specify the same URL in both "add" and "remove", it will
1152       be added. (That is, "add" overrides "remove".)
1153
1154       Returns
1155
1156       A hash or hashref where the keys are numeric bug ids and the contents
1157       are a hash with one key, "see_also".
1158
1159       "see_also" points to a hash, which contains two keys, "added" and
1160       "removed".
1161
1162       These are arrays of strings, representing the actual changes that were
1163       made to the bug.
1164
1165       Here's a diagram of what the return value looks like for updating bug
1166       ids 1 and 2:
1167
1168        {
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
1183       This return value allows you to tell what this method actually did.
1184
1185       It is in this format to be compatible with the return value of a future
1186       "update" method.
1187
1188       Errors
1189
1190       100 - Invalid Bug Alias
1191           If you specified an alias and there is no bug with that alias.
1192
1193       101 - Invalid Bug ID
1194           The bug_id you specified doesn't exist in the database.
1195
1196       102 - Access Denied
1197           You do not have access to the bug_id you specified.
1198
1199       109 - Bug Edit Denied
1200           You did not have the necessary rights to edit the bug.
1201
1202       112 - Invalid Bug URL
1203           One of the URLs you provided did not look like a valid bug URL.
1204
1205       115 - See Also Edit Denied
1206           You did not have the necessary rights to edit the See Also field
1207           for this bug.
1208
1209           Before Bugzilla 3.6, error 115 had a generic error code of 32000.
1210
1211   update_tags
1212        @changes = BZ::Client::Bug->update_tags( $client, \%params );
1213        $changes = BZ::Client::Bug->update_tags( $client, \%params );
1214
1215       Adds or removes tags on bugs.
1216
1217       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
1222       Bugzilla will lower case the text of the tags. This doesn't seem to be
1223       documented.
1224
1225       Reminder: to retrieve these tags, specify "_extra" or the field name
1226       "tags" in "include_fields" when searching etc.
1227
1228       History
1229
1230       This is marked as UNSTABLE in Bugzilla 4.4
1231
1232       Added in Bugzilla 4.4.
1233
1234       Parameters
1235
1236       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
1240       tags
1241           A hash representing tags to be added and/or removed. The hash has
1242           the following fields:
1243
1244           add An array of strings representing tag names to be added to the
1245               bugs.
1246
1247               It is safe to specify tags that are already associated with the
1248               bugs as they will just be silently ignored.
1249
1250           remove
1251               An array of strings representing tag names to be removed from
1252               the bugs.
1253
1254               It is safe to specify tags that are not associated with any
1255               bugs as they will just be silently ignored.
1256
1257       Returns
1258
1259       A hash or hashref where the keys are numeric bug ids and the contents
1260       are a hash with one key, "tags".
1261
1262       "tags" points to a hash, which contains two keys, "added" and
1263       "removed".
1264
1265       These are arrays of strings, representing the actual changes that were
1266       made to the bug.
1267
1268       Here's a diagram of what the return value looks like for updating bug
1269       ids 1 and 2:
1270
1271        {
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
1286       This return value allows you to tell what this method actually did.
1287
1288       Errors
1289
1290       100 - Invalid Bug Alias
1291           If you specified an alias and there is no bug with that alias.
1292
1293       101 - Invalid Bug ID
1294           The bug_id you specified doesn't exist in the database.
1295
1296       102 - Access Denied
1297           You do not have access to the bug_id you specified.
1298
1299   new
1300        my $bug = BZ::Client::Bug->new( id => $id );
1301
1302       Creates a new bug object instance with the given ID.
1303
1304       Note: Doesn't actually touch your bugzilla server.
1305
1306       See "INSTANCE METHODS" for how to use it.
1307

INSTANCE METHODS

1309       This section lists the modules instance methods.
1310
1311       Once you have a bug object, you can use these methods to inspect and
1312       manipulate the bug.
1313
1314   id
1315        $id = $bug->id();
1316        $bug->id( $id );
1317
1318       Gets or sets the bugs ID.
1319
1320   alias
1321        $alias = $bug->alias();
1322        $bug->alias( $alias );
1323
1324       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
1327   assigned_to
1328        $assigned_to = $bug->assigned_to();
1329        $bug->assigned_to( $assigned_to );
1330
1331       Gets or sets the login name of the user to whom the bug is assigned.
1332
1333   component
1334        $component = $bug->component();
1335        $bug->component( $component );
1336
1337       Gets or sets the name of the current component of this bug.
1338
1339   creation_time
1340        $dateTime = $bug->creation_time();
1341        $bug->creation_time( $dateTime );
1342
1343       Gets or sets the date and time, when the bug was created.
1344
1345   dupe_of
1346        $dupeOf = $bug->dupe_of();
1347        $bug->dupe_of( $dupeOf );
1348
1349       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
1352   is_open
1353        $isOpen = $bug->is_open();
1354        $bug->is_open( $isOpen );
1355
1356       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
1360   last_change_time
1361        $lastChangeTime = $bug->last_change_time();
1362        $bug->last_change_time( $lastChangeTime );
1363
1364       Gets or sets the date and time, when the bug was last changed.
1365
1366   priority
1367        $priority = $bug->priority();
1368        $bug->priority( $priority );
1369
1370       Gets or sets the priority of the bug.
1371
1372   product
1373        $product = $bug->product();
1374        $bug->product( $product );
1375
1376       Gets or sets the name of the product this bug is in.
1377
1378   resolution
1379        $resolution = $bug->resolution();
1380        $bug->resolution( $resolution );
1381
1382       Gets or sets the current resolution of the bug, or an empty string if
1383       the bug is open.
1384
1385   severity
1386        $severity = $bug->severity();
1387        $bug->severity( $severity );
1388
1389       Gets or sets the current severity of the bug.
1390
1391   status
1392        $status = $bug->status();
1393        $bug->status( $status );
1394
1395       Gets or sets the current status of the bug.
1396
1397   summary
1398        $summary = $bug->summary();
1399        $bug->summary( $summary );
1400
1401       Gets or sets the summary of this bug.
1402

ATTACHMENTS & COMMENTS

1404       These are implemented by other modules.
1405
1406       See BZ::Client::Bug::Attachment and BZ::Client::Bug::Comment
1407

TODO

1409       Bugzilla 5.0. introduced the "search_comment_tags" and
1410       "update_comment_tags" methods, these are yet to be specifically
1411       implemented.
1412

SEE ALSO

1414       BZ::Client, BZ::Client::Bug::Attachment, BZ::Client::Bug::Comment
1415
1416       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

AUTHORS

1422       ·   Dean Hamstead <dean@bytefoundry.com.au>
1423
1424       ·   Jochen Wiedmann <jochen.wiedmann@gmail.com>
1425
1427       This software is copyright (c) 2017 by Dean Hamstad.
1428
1429       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.
1431
1432
1433
1434perl v5.30.1                      2020-01-29                BZ::Client::Bug(3)
Impressum