1BZ::Client::Bug::CommenUts(e3r)Contributed Perl DocumentBaZt:i:oCnlient::Bug::Comment(3)
2
6 BZ::Client::Bug::Comment - Client side representation of an Comment on
7 a Bug in Bugzilla
8
10 version 4.4004
11
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 my $client = BZ::Client->new( url => $url,
18 user => $user,
19 password => $password );
20 my $comments = BZ::Client::Bug::Comment->get( $client, $ids );
22
24 This section lists the class methods, which are available in this
25 module.
26 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 This allows you to get data about comments, given a list of bugs and/or
32 comment ids.
33 Actual Bugzilla API method is "comments".
35 History
37 Added in Bugzilla 3.4
39 Parameters
41 A single scalar is considered a search for "ids", otherwise a hash
43 reference must be provided.
44 Note: At least one of "ids" or "comment_ids" is required.
46 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 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 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 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 Returns
68 A hash reference containing two items is returned. e.g.
70 {
72 bugs => {
74 123 => \@comments,
75 456 => \@comments,
76 },
77 comments => {
79 789 => $comment,
80 },
81 }
83 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 More details on the above example:
90 bugs
92 This is used for bugs specified in "ids" parameter.
93 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 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 comments
102 Each individual comment requested in "comment_ids" is returned
103 here.
104 This is a hash wherein the keys are the numeric comment ID, and the
106 corresponding value is the comment object.
107 A "comment" as described above is an object instance of this package
109 i.e. BZ::Client::Bug::Comment.
110 Errors
112 100 - Invalid Bug Alias
114 If you specified an alias and there is no bug with that alias.
115 101 - Invalid Bug ID
117 The "bug_id" you specified doesn't exist in the database.
118 102 - Access Denied
120 You do not have access to the "bug_id" you specified.
121 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 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 add
133 This allows you to add a comment to a bug in Bugzilla.
134 Actual Bugzilla API method is "add_comment".
136 History
138 Added in Bugzilla 3.2.
140 Modified to return the new comment's ID in Bugzilla 3.4
142 Modified to throw an error if you try to add a private comment but
144 can't, in Bugzilla 3.4.
145 Parameters
147 An instance of this package or a hash containing:
149 id id (int or string) Required - The ID or alias of the bug to append
151 a comment to.
152 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 is_private
159 is_private (boolean) - If set to true, the comment is private,
160 otherwise it is assumed to be public.
161 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 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 Returns
172 The id of the newly-created comment.
174 Errors
176 54 - Hours Worked Too Large
178 You specified a "work_time" larger than the maximum allowed value
179 of 99999.99.
180 100 - Invalid Bug Alias
182 If you specified an alias and there is no bug with that alias.
183 101 - Invalid Bug ID
185 The ID you specified doesn't exist in the database.
186 109 - Bug Edit Denied
188 You did not have the necessary rights to edit the bug.
189 113 - Can't Make Private Comments
191 You tried to add a private comment, but don't have the necessary
192 rights.
193 114 - Comment Too Long
195 You tried to add a comment longer than the maximum allowed length
196 (65,535 characters).
197 Before Bugzilla 3.6, error 54 and error 114 had a generic error code of
199 32000.
200 render
202 Returns the HTML rendering of the provided comment text.
203 Actual Bugzilla API method is "render_comment".
205 Note: this all takes place on your Bugzilla server.
207 History
209 Added in Bugzilla 5.0.
211 Parameters
213 text
215 text (string) Required - Text comment text to render
216 id id The ID of the bug to render the comment against.
218 Returns
220 The HTML rendering
222 Errors
224 100 - Invalid Bug Alias
226 If you specified an alias and there is no bug with that alias.
227 101 - Invalid Bug ID
229 The "bug_id" you specified doesn't exist in the database.
230 102 - Access Denied
232 You do not have access to the "bug_id" you specified.
233 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 Creates a new instance with the given details. Doesn't actually touch
243 your Bugzilla Server - see "add" for that.
244
246 This section lists the modules instance methods.
247 bug_id
249 bug_id (int) - The ID of the bug that this comment is on when reading
250 bug_id (int or string) - The ID or alias of the bug to append a comment
252 to when writing
253 comment
255 comment (string) The actual text of the comment when reading
256 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 Max length is 65,535 characters.
262 text
264 Synonym for "comment"
265 is_private
267 is_private (boolean) - If set to true, the comment is private,
268 otherwise it is assumed to be public.
269 Read and Write.
271 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 Max value is 99999.99
278 id
280 id (int) The globally unique ID for the comment.
281 Read only.
283 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 Read only.
289 Added to the return value in Bugzilla 3.6
291 count
293 count (int) - The number of the comment local to the bug. The
294 Description is 0, comments start with 1.
295 Read only.
297 Added to the return value in Bugzilla 4.4.
299 creator
301 creator (string) - The login name of the comment's author.
302 Also returned as "author", for backwards-compatibility with older
304 Bugzillas. (However, this backwards-compatibility will go away in
305 Bugzilla 5.0)
306 In bugzilla 4.0, the "author" return value was renamed to "creator".
308 author
310 See creator
311 time
313 time (DateTime) - The time (in Bugzilla's timezone) that the comment
314 was added.
315 Read only.
317 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 Read only.
326 Added in Bugzilla 4.4.
328
330 BZ::Client, BZ::Client::API, Bugzilla API
331 <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Bug.html>
332
334 • Dean Hamstead <dean@bytefoundry.com.au>
335 • Jochen Wiedmann <jochen.wiedmann@gmail.com>
337
339 This software is copyright (c) 2021 by Dean Hamstad.
340 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.
343perl v5.36.0 2023-01-20 BZ::Client::Bug::Comment(3)