BZ::Client::Bug::Comment(3pm)

1BZ::Client::Bug::CommenUts(e3rpmC)ontributed Perl DocumeBnZt:a:tCiloinent::Bug::Comment(3pm)
2
3
4

NAME

6       BZ::Client::Bug::Comment - Client side representation of an Comment on
7       a Bug in Bugzilla
8

VERSION

10       version 4.4004
11

SYNOPSIS

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

CLASS METHODS

24       This section lists the class methods, which are available in this
25       module.
26
27   get
28         my $comments = BZ::Client::Bug::Comment->get( $client, 1234 );
29         my $comments = BZ::Client::Bug::Comment->get( $client, { ids => \@list, commend_ids => \@list } );
30
31       This allows you to get data about comments, given a list of bugs and/or
32       comment ids.
33
34       Actual Bugzilla API method is "comments".
35
36       History
37
38       Added in Bugzilla 3.4
39
40       Parameters
41
42       A single scalar is considered a search for "ids", otherwise a hash
43       reference must be provided.
44
45       Note: At least one of "ids" or "comment_ids" is required.
46
47       In addition to the parameters below, this method also accepts the
48       standard "include_fields" in BZ::Client::Bug and "exclude_fields" in
49       BZ::Client::Bug arguments.
50
51       ids ids (array) - An array that can contain both bug ID's and bug
52           aliases. All of the comments (that are visible to you) will be
53           returned for the specified bugs.
54
55       comment_ids
56           comment_ids (array) - An array of integer comment ID's. These
57           comments will be returned individually, separate from any other
58           comments in their respective bugs.
59
60       new_since
61           new_since (DateTime) - If specified, the method will only return
62           comments newer than this time. This only affects comments returned
63           from the "ids" argument. You will always be returned all comments
64           you request in the comment_ids argument, even if they are older
65           than this date.
66
67       Returns
68
69       A hash reference containing two items is returned. e.g.
70
71        {
72
73            bugs => {
74                123 => \@comments,
75                456 => \@comments,
76            },
77
78            comments => {
79                789 => $comment,
80            },
81
82        }
83
84       The Bugzilla WebService documentation doesnt state what order the
85       comments will be in, however they seem to be returned [ oldest, newest
86       ]. If this order is important to you, then you should sort them just to
87       be sure.
88
89       More details on the above example:
90
91       bugs
92           This is used for bugs specified in "ids" parameter.
93
94           This is a hash, wherein the keys are the numeric IDs of the bugs,
95           and the corresponding value is an array ref of comment objects.
96
97           Note that any individual bug will only be returned once, so if you
98           specify an ID multiple times in ID's, it will still only be
99           returned once.
100
101       comments
102           Each individual comment requested in "comment_ids" is returned
103           here.
104
105           This is a hash wherein the keys are the numeric comment ID, and the
106           corresponding value is the comment object.
107
108       A "comment" as described above is an object instance of this package
109       i.e. BZ::Client::Bug::Comment.
110
111       Errors
112
113       100 - Invalid Bug Alias
114           If you specified an alias and there is no bug with that alias.
115
116       101 - Invalid Bug ID
117           The "bug_id" you specified doesn't exist in the database.
118
119       102 - Access Denied
120           You do not have access to the "bug_id" you specified.
121
122       110 - Comment Is Private
123           You specified the ID of a private comment in the comment_ids
124           argument, and you are not in the "insider group" that can see
125           private comments.
126
127       111 - Invalid Comment ID
128           You specified an ID in the "comment_ids" argument that is
129           invalid--either you specified something that wasn't a number, or
130           there is no comment with that ID.
131
132   add
133       This allows you to add a comment to a bug in Bugzilla.
134
135       Actual Bugzilla API method is "add_comment".
136
137       History
138
139       Added in Bugzilla 3.2.
140
141       Modified to return the new comment's ID in Bugzilla 3.4
142
143       Modified to throw an error if you try to add a private comment but
144       can't, in Bugzilla 3.4.
145
146       Parameters
147
148       An instance of this package or a hash containing:
149
150       id  id (int or string) Required - The ID or alias of the bug to append
151           a comment to.
152
153       comment
154           comment (string) Required - The comment to append to the bug. If
155           this is empty or all whitespace, an error will be thrown saying
156           that you did not set the comment parameter.
157
158       is_private
159           is_private (boolean) - If set to true, the comment is private,
160           otherwise it is assumed to be public.
161
162           Before Bugzilla 3.6, the "is_private argument" was called
163           "private", and you can still call it "private" for backwards-
164           compatibility purposes if you wish.
165
166       work_time
167           work_time (double) - Adds this many hours to the "Hours Worked" on
168           the bug. If you are not in the time tracking group, this value will
169           be ignored.
170
171       Returns
172
173       The id of the newly-created comment.
174
175       Errors
176
177       54 - Hours Worked Too Large
178           You specified a "work_time" larger than the maximum allowed value
179           of 99999.99.
180
181       100 - Invalid Bug Alias
182           If you specified an alias and there is no bug with that alias.
183
184       101 - Invalid Bug ID
185           The ID you specified doesn't exist in the database.
186
187       109 - Bug Edit Denied
188           You did not have the necessary rights to edit the bug.
189
190       113 - Can't Make Private Comments
191           You tried to add a private comment, but don't have the necessary
192           rights.
193
194       114 - Comment Too Long
195           You tried to add a comment longer than the maximum allowed length
196           (65,535 characters).
197
198       Before Bugzilla 3.6, error 54 and error 114 had a generic error code of
199       32000.
200
201   render
202       Returns the HTML rendering of the provided comment text.
203
204       Actual Bugzilla API method is "render_comment".
205
206       Note: this all takes place on your Bugzilla server.
207
208       History
209
210       Added in Bugzilla 5.0.
211
212       Parameters
213
214       text
215           text (string) Required - Text comment text to render
216
217       id  id The ID of the bug to render the comment against.
218
219       Returns
220
221       The HTML rendering
222
223       Errors
224
225       100 - Invalid Bug Alias
226           If you specified an alias and there is no bug with that alias.
227
228       101 - Invalid Bug ID
229           The "bug_id" you specified doesn't exist in the database.
230
231       102 - Access Denied
232           You do not have access to the "bug_id" you specified.
233
234   new
235         my $comment = BZ::Client::Bug::Comment->new(
236                                                 id         => $bug_id,
237                                                 comment    => $comment,
238                                                 is_private => 1 || 0,
239                                                 work_time  => 3.5
240                                               );
241
242       Creates a new instance with the given details. Doesn't actually touch
243       your Bugzilla Server - see "add" for that.
244

INSTANCE METHODS

246       This section lists the modules instance methods.
247
248   bug_id
249       bug_id (int) - The ID of the bug that this comment is on when reading
250
251       bug_id (int or string) - The ID or alias of the bug to append a comment
252       to when writing
253
254   comment
255       comment (string) The actual text of the comment when reading
256
257       When writing, the comment to append to the bug. If this is empty or all
258       whitespace, an error will be thrown saying that you did not set the
259       "comment" parameter.
260
261       Max length is 65,535 characters.
262
263   text
264       Synonym for "comment"
265
266   is_private
267       is_private (boolean) - If set to true, the comment is private,
268       otherwise it is assumed to be public.
269
270       Read and Write.
271
272   work_time
273       work_time (double) - Adds this many hours to the "Hours Worked" on the
274       bug. If you are not in the time tracking group, this value will be
275       ignored.
276
277       Max value is 99999.99
278
279   id
280       id (int) The globally unique ID for the comment.
281
282       Read only.
283
284   attachment_id
285       attachment_id (int) If the comment was made on an attachment, this will
286       be the ID of that attachment. Otherwise it will be null.
287
288       Read only.
289
290       Added to the return value in Bugzilla 3.6
291
292   count
293       count (int) - The number of the comment local to the bug. The
294       Description is 0, comments start with 1.
295
296       Read only.
297
298       Added to the return value in Bugzilla 4.4.
299
300   creator
301       creator (string) -  The login name of the comment's author.
302
303       Also returned as "author", for backwards-compatibility with older
304       Bugzillas. (However, this backwards-compatibility will go away in
305       Bugzilla 5.0)
306
307       In bugzilla 4.0, the "author" return value was renamed to "creator".
308
309   author
310       See creator
311
312   time
313       time (DateTime) - The time (in Bugzilla's timezone) that the comment
314       was added.
315
316       Read only.
317
318   creation_time
319       creation_time (DateTime) - This is exactly same as the "time" key. Use
320       this field instead of "time" for consistency with other methods
321       including "get" and "attachments". For compatibility, /time is still
322       usable. However, please note that /time may be deprecated and removed
323       in a future release of Bugzilla.
324
325       Read only.
326
327       Added in Bugzilla 4.4.
328

AUTHORS

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

COPYRIGHT AND LICENSE

339       This software is copyright (c) 2021 by Dean Hamstad.
340
341       This is free software; you can redistribute it and/or modify it under
342       the same terms as the Perl 5 programming language system itself.
343
344
345
346perl v5.38.0                      2023-07-20     BZ::Client::Bug::Comment(3pm)