1BZ::Client::Product(3)User Contributed Perl DocumentationBZ::Client::Product(3)
2
3
4

NAME

6       BZ::Client::Product - Client side representation of a product in
7       Bugzilla
8

VERSION

10       version 4.4004
11

SYNOPSIS

13       This class provides methods for accessing and managing products in
14       Bugzilla. Instances of this class are returned by
15       BZ::Client::Product::get.
16
17        my $client = BZ::Client->new( url       => $url,
18                                      user      => $user,
19                                      password  => $password );
20
21        my $ids = BZ::Client::Product->get_accessible_products( $client );
22        my $products = BZ::Client::Product->get( $client, \%params );
23

CLASS METHODS

25       This section lists the class methods, which are available in this
26       module.
27
28   create
29        $id = BZ::Client::Product->create( $client, \%params );
30
31       This allows you to create a new Product in Bugzilla.
32
33       History
34
35       Marked as experimental as of Bugzilla 5.0.
36
37       Parameters
38
39       Some params must be set, or an error will be thrown. These params are
40       noted as Required.
41
42       name
43           name (string) The name of this product. Must be globally unique
44           within Bugzilla.
45
46           Required.
47
48       description
49           description (string) A description for this product. Allows some
50           simple HTML.
51
52           Required.
53
54       version
55           version (string) The default version for this product.
56
57           Required.
58
59       has_unconfirmed
60           has_unconfirmed (boolean) Allow the UNCONFIRMED status to be set on
61           bugs in this product. Default: true.
62
63       classification
64           classification (string) The name of the Classification which
65           contains this product.
66
67       default_milestone
68           default_milestone (string) The default milestone for this product.
69           Default '---'.
70
71       is_open
72           is_open (boolean) True if the product is currently allowing bugs to
73           be entered into it. Default: true.
74
75       create_series
76           create_series (boolean) True if you want series for New Charts to
77           be created for this new product. Default: true.
78
79       Returns
80
81       The ID of the newly-filed product.
82
83       Errors
84
85       51 - Classification does not exist
86           You must specify an existing classification name.
87
88       700 - Product blank name
89           You must specify a non-blank name for this product.
90
91       701 - Product name too long
92           The name specified for this product was longer than the maximum
93           allowed length.
94
95       702 - Product name already exists
96           You specified the name of a product that already exists. (Product
97           names must be globally unique in Bugzilla.)
98
99       703 - Product must have description
100           You must specify a description for this product.
101
102       704 - Product must have version
103           You must specify a version for this product.
104
105   update
106        $id = BZ::Client::Product->update( $client, \%params );
107
108       This allows you to update a Group in Bugzilla.
109
110       History
111
112       As of Bugzilla 5.0. this is marked as experimental.
113
114       Added in Bugzilla 4.4.
115
116       Parameters
117
118       Either "ids" or "names" is required to select the bugs you want to
119       update.
120
121       All other values change or set something in the product.
122
123       ids ids (array) Numeric ID's of the products you wish to update.
124
125       names
126           names (array) Text names of the products that you wish to update.
127
128       default_milestone
129           default_milestone (string) When a new bug is filed, what milestone
130           does it get by default if the user does not choose one? Must
131           represent a milestone that is valid for this product.
132
133       description
134           description (string) Update the long description for these products
135           to this value.
136
137       has_unconfirmed
138           has_unconfirmed (boolean) Allow the UNCONFIRMED status to be set on
139           bugs in this products.
140
141       is_open
142           is_open (boolean) True if the product is currently allowing bugs to
143           be entered into it.  Otherwise false.
144
145       Returns
146
147       An array or arrayref of hashes containing the following:
148
149       id  id (int) The ID of the product that was updated.
150
151       changes
152           The changes that were actually done on this product. The keys are
153           the names of the fields that were changed, and the values are a
154           hash with two keys:
155
156           added
157               added (string) The value that this field was changed to.
158
159           removed
160               removed (string) The value that was previously set in this
161               field.
162
163           Note that booleans will be represented with the strings '1' and
164           '0'.
165
166           Here's an example of what a return value might look like:
167
168            [
169                {
170                    id => 123,
171                    changes => {
172                        name => {
173                            removed => 'FooName',
174                            added   => 'BarName'
175                        },
176                        has_unconfirmed => {
177                            removed => '1',
178                            added   => '0',
179                        }
180                    }
181                },
182                \%etc
183            ],
184
185       Errors
186
187       700 - Product blank name
188           You must specify a non-blank name for this product.
189
190       701 - Product name too long
191           The name specified for this product was longer than the maximum
192           allowed length.
193
194       702 - Product name already exists
195           You specified the name of a product that already exists. (Product
196           names must be globally unique in Bugzilla.)
197
198       703 - Product must have description
199           You must specify a description for this product.
200
201       705 - Product must define a default milestone
202           You must define a default milestone.
203
204   get_selectable_products
205        @products = BZ::Client::Product->get_selectable_products( $client );
206        $products = BZ::Client::Product->get_selectable_products( $client );
207
208       Returns a list of the ID's of the products the user can search on.
209
210       History
211
212       Marked as experimental as of Bugzilla 5.0.
213
214       Parameters
215
216       (none)
217
218       Returns
219
220       An array of product ID's
221
222       Errors
223
224       (none)
225
226   get_enterable_products
227        @products = BZ::Client::Product->get_enterable_products( $client );
228        $products = BZ::Client::Product->get_enterable_products( $client );
229
230       Returns a list of the ID's of the products the user can enter bugs
231       against.
232
233       History
234
235       Marked as experimental as of Bugzilla 5.0.
236
237       Parameters
238
239       (none)
240
241       Returns
242
243       An array of product ID's
244
245       Errors
246
247       (none)
248
249   get_accessible_products
250        @products = BZ::Client::Product->get_selectable_products( $client );
251        $products = BZ::Client::Product->get_selectable_products( $client );
252
253       Returns a list of the ID's of the products the user can search or enter
254       bugs against.
255
256       History
257
258       Marked as unstable as of Bugzilla 5.0.
259
260       Parameters
261
262       (none)
263
264       Returns
265
266       An array of product ID's
267
268       Errors
269
270       (none)
271
272   get
273        @products = BZ::Client::Product->get( $client, \%params );
274        $products = BZ::Client::Product->get( $client, \%params );
275
276       Returns a list of BZ::Client::Product instances based on the given
277       parameters.
278
279       Note, that if the user tries to access a product that is not in the
280       list of accessible products for the user, or a product that does not
281       exist, that is silently ignored, and no information about that product
282       is returned.
283
284       Parameters
285
286       In addition to the parameters below, this method also accepts the
287       standard "include_fields" in BZ::Client::Bug and "exclude_fields" in
288       BZ::Client::Bug arguments.
289
290       Note: You must at least specify one of "ids" or "names".
291
292       ids ids (array) An array of product ID's.
293
294       names
295           names (array) An array of product names.
296
297           Added in Bugzilla 4.2.
298
299       type
300           The group of products to return. Valid values are: "accessible"
301           (default), "selectable", and "enterable". "type" can be a single
302           value or an array of values if more than one group is needed with
303           duplicates removed.
304
305       Returns
306
307       An array or arrayref of bug instance objects with the given ID's.
308
309       See "INSTANCE METHODS" for how to use them.
310
311       Errors
312
313       (none)
314
315   get_products
316       Compatibilty with Bugzilla 3.0 API. Exactly equivalent to "get".
317
318   new
319        my $product = BZ::Client::Product->new( id           => $id,
320                                                name         => $name,
321                                                description  => $description );
322
323       Creates a new instance with the given ID, name, and description.
324

INSTANCE METHODS

326       This section lists the modules instance methods.
327
328   id
329        $id = $product->id();
330
331       Gets the products ID.
332
333       Read only.
334
335   name
336        $name = $product->name();
337        $product->name( $name );
338
339       Gets or sets the products name.
340
341   description
342        $description = $product->description();
343        $product->description( $description );
344
345       Gets or sets the products description.
346
347   version
348        $version = $product->version();
349        $product->version( $version );
350
351       Gets or sets the products version.
352
353       (Set only works for new products, not updates)
354
355   has_unconfirmed
356        $bool = $product->has_unconfirmed();
357        $product->has_unconfirmed( $bool );
358
359       Gets or sets the products has_unconfirmed setting.
360
361       Added in Bugzilla 4.2 as a replacement for "internals".
362
363   classification
364        $classification = $product->classification();
365        $product->classification( $classification );
366
367       Gets or sets the products classification.
368
369       Added in Bugzilla 4.2 as a replacement for "internals".
370
371   default_milestone
372        $milestone = $product->default_milestone();
373        $product->default_milestone( $milestone );
374
375       Gets or sets the products default milestone.
376
377       Added in Bugzilla 4.2 as a replacement for "internals".
378
379   is_open
380        $bool = $product->is_open();
381        $product->is_open( $bool );
382
383       Gets or sets the products is_open setting.
384
385   create_series
386        $series = $product->create_series();
387        $product->create_series( $series );
388
389       Gets or sets the products is_open setting.
390
391   components
392        @components = $product->components();
393        $components = $product->components();
394
395       An array of hashes, where each hash describes a component, and has the
396       following items:
397
398       id  id (int) An integer ID uniquely identifying the component in this
399           installation only.
400
401       name
402           name (string) The name of the component. This is a unique
403           identifier for this component.
404
405       description
406           description (string) A description of the component, which may
407           contain HTML.
408
409       default_assigned_to
410           default_assigned_to (string) The login name of the user to whom new
411           bugs will be assigned by default.
412
413       default_qa_contact
414           default_qa_contact (string) The login name of the user who will be
415           set as the QA Contact for new bugs by default. Empty string if the
416           QA contact is not defined.
417
418       sort_key
419           sort_key (int) Components, when displayed in a list, are sorted
420           first by this integer and then secondly by their name.
421
422       is_active
423           is_active (boolean) A boolean indicating if the component is
424           active. Inactive components are not enabled for new bugs.
425
426       flag_types
427           Added in Bugzilla 4.4.
428
429           A hash containing the two items bug and attachment that each
430           contains an array of hashes, where each hash describes a flagtype,
431           and has the following items:
432
433           id  id (int) Returns the ID of the flagtype.
434
435           name
436               name (string) Returns the name of the flagtype.
437
438           description
439               description (string) Returns the description of the flagtype.
440
441           cc_list
442               cc_list (string) Returns the concatenated CC list for the
443               flagtype, as a single string.
444
445           sort_key
446               sort_key (int) Returns the sortkey of the flagtype.
447
448           is_active
449               is_active (boolean) Returns whether the flagtype is active or
450               disabled. Flags being in a disabled flagtype are not deleted.
451               It only prevents you from adding new flags to it.
452
453           is_requestable
454               is_requestable (boolean) Returns whether you can request for
455               the given flagtype (i.e.  whether the '?' flag is available or
456               not).
457
458           is_requesteeble
459               is_requesteeble (boolean) Returns whether you can ask someone
460               specifically or not.
461
462           is_multiplicable
463               is_multiplicable (boolean) Returns whether you can have more
464               than one flag for the given flagtype in a given bug/attachment.
465
466           grant_group
467               grant_group (int) the group ID that is allowed to grant/deny
468               flags of this type. If the item is not included all users are
469               allowed to grant/deny this flagtype.
470
471           request_group
472               request_group (int) the group ID that is allowed to request the
473               flag if the flag is of the type requestable. If the item is not
474               included all users are allowed request this flagtype.
475
476       Added in Bugzilla 4.2 as a replacement for "internals".
477
478   versions
479        $versions = $product->versions();
480
481       Added in Bugzilla 4.2 as a replacement for "internals".
482
483       Returns an array of hashes, where each hash describes a version, and
484       has the following items: "name", "sort_key" and "is_active".
485
486   milestones
487        $milestones = $product->milestones();
488
489       Returns an array of hashes, where each hash describes a milestones, and
490       has the following items: "name", "sort_key" and "is_active".
491
492       Added in Bugzilla 4.2 as a replacement for "internals".
493
494   internals
495       Returned by "get" until version 4.2, at which point it was dropped.
496       Remains for compatibility. Please move away from using it asap.
497

EXCEPTION HANDLING

499       See BZ::Client::Exception
500

SEE ALSO

502       BZ::Client, BZ::Client::API, Bugzilla API
503       <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Product.html>
504

AUTHORS

506       •   Dean Hamstead <dean@bytefoundry.com.au>
507
508       •   Jochen Wiedmann <jochen.wiedmann@gmail.com>
509
511       This software is copyright (c) 2021 by Dean Hamstad.
512
513       This is free software; you can redistribute it and/or modify it under
514       the same terms as the Perl 5 programming language system itself.
515
516
517
518perl v5.36.0                      2023-01-20            BZ::Client::Product(3)
Impressum