1BZ::Client::User(3) User Contributed Perl Documentation BZ::Client::User(3)
2
3
4
6 BZ::Client::User - Creates and edits user accounts in Bugzilla
7
9 version 4.4004
10
12 This class provides methods for accessing information about the
13 Bugzilla servers installation.
14
15 my $client = BZ::Client->new( url => $url,
16 user => $user,
17 password => $password );
18
19 my $ok = BZ::Client::User->offer_account_by_email( $client, 'email@address' );
20 my $users = BZ::Client::User->get( $client, \%params );
21 my $id = BZ::Client::User->create( $client, \%params );
22 my $users = BZ::Client::User->update( $client, \%params );
23
25 This section lists the class methods, which are available in this
26 module.
27
28 offer_account_by_email
29 my $ok = BZ::Client::User->offer_account_by_email( $client, 'email@address' );
30 my $ok = BZ::Client::User->offer_account_by_email( $client, \%params );
31
32 Sends an email to the user, offering to create an account. The user
33 will have to click on a URL in the email, and choose their password and
34 real name.
35
36 This is the recommended way to create a Bugzilla account.
37
38 Parameters
39
40 email
41 email (string) The email address to send the offer to.
42
43 Note: email can be provided as the single option as a scalar as
44 shown above.
45
46 Returns
47
48 nothing if successful
49
50 Errors
51
52 50 - Email parameter missing
53 The email parameter was not provided.
54
55 500 - Account Already Exists
56 An account with that email address already exists in Bugzilla.
57
58 501 - Illegal Email Address
59 This Bugzilla does not allow you to create accounts with the format
60 of email address you specified. Account creation may be entirely
61 disabled.
62
63 get
64 my $users = BZ::Client::User->get( $client, \%params );
65
66 Gets information about user accounts in Bugzilla.
67
68 History
69
70 Added in Bugzilla 3.4
71
72 Parameters
73
74 Note: At least one of "ids", "names", or "match" must be specified.
75
76 Note: Users will only appear once in the returned list, even if that
77 user is matched by more than one search argument.
78
79 In addition to the parameters below, this method also accepts the
80 standard "include_fields" in BZ::Client::Bug and "exclude_fields" in
81 BZ::Client::Bug arguments.
82
83 ids (array)
84 An array of integers, representing user ID's.
85
86 Logged-out users cannot pass this parameter to this function. If
87 they try, they will get an error. Logged-in users will get an error
88 if they specify the ID of a user they cannot see.
89
90 names (array)
91 An array of login names (strings).
92
93 match (array)
94 An array of strings. This works just like "user matching" in
95 Bugzilla itself. Users will be returned whose real name or login
96 name contains any one of the specified strings. Users that you
97 cannot see will not be included in the returned list.
98
99 Most installations have a limit on how many matches are returned
100 for each string, which defaults to 1000 but can be changed by the
101 Bugzilla administrator.
102
103 Logged-out users cannot use this argument, and an error will be
104 thrown if they try. (This is to make it harder for spammers to
105 harvest email addresses from Bugzilla, and also to enforce the user
106 visibility restrictions that are implemented on some Bugzillas.)
107
108 limit (int)
109 Limit the number of users matched by the "match" parameter. If
110 value is greater than the system limit, the system limit will be
111 used. This parameter is only used when user matching using the
112 "match" parameter is being performed.
113
114 group_ids (array)
115 group_ids is an array of numeric ids for groups that a user can be
116 in. If this is specified, it limits the return value to users who
117 are in any of the groups specified.
118
119 Added in Bugzilla 4.0
120
121 groups (array)
122 groups is an array of names of groups that a user can be in. If
123 this is specified, it limits the return value to users who are in
124 any of the groups specified.
125
126 Added in Bugzilla 4.0
127
128 include_disabled (boolean)
129 By default, when using the "match" parameter, disabled users are
130 excluded from the returned results unless their full username is
131 identical to the match string. Setting "include_disabled" to "true"
132 will include disabled users in the returned results even if their
133 username doesn't fully match the input string.
134
135 Added in Bugzilla 4.0, default behaviour for "match" was then
136 changed to exclude disabled users.
137
138 Returns
139
140 A hash containing one item, "users", that is an array of hashes. Each
141 hash describes a user, and has the following items:
142
143 id id (int) The unique integer ID that Bugzilla uses to represent this
144 user. Even if the user's login name changes, this will not change.
145
146 real_name
147 real_name (string) The actual name of the user. May be blank.
148
149 email
150 email (string) The email address of the user.
151
152 name
153 name (string) The login name of the user. Note that in some
154 situations this is different than their email.
155
156 can_login
157 can_login (boolean) A boolean value to indicate if the user can
158 login into bugzilla.
159
160 email_enabled
161 email_enabled (boolean) A boolean value to indicate if bug-related
162 mail will be sent to the user or not.
163
164 login_denied_text
165 login_denied_text (string) A text field that holds the reason for
166 disabling a user from logging into bugzilla, if empty then the user
167 account is enabled. Otherwise it is disabled/closed.
168
169 groups
170 groups (array) An array of group hashes the user is a member of. If
171 the currently logged in user is querying his own account or is a
172 member of the "editusers" group, the array will contain all the
173 groups that the user is a member of. Otherwise, the array will only
174 contain groups that the logged in user can bless. Each hash
175 describes the group and contains the following items:
176
177 Added in Bugzilla 4.4
178
179 id id (int) The group ID
180
181 name
182 name (string) The name of the group
183
184 description
185 description (string) The description for the group
186
187 saved_searches
188 saved_searches (array) An array of hashes, each of which represents
189 a user's saved search and has the following keys:
190
191 Added in Bugzilla 4.4
192
193 id id (int) An integer ID uniquely identifying the saved search.
194
195 name
196 name (string) The name of the saved search.
197
198 query
199 query (string) The CGI parameters for the saved search.
200
201 saved_reports
202 saved_reports (array) An array of hashes, each of which represents
203 a user's saved report and has the following keys:
204
205 Added in Bugzilla 4.4
206
207 id id (int) An integer ID uniquely identifying the saved report.
208
209 name
210 name (string) The name of the saved report.
211
212 query
213 query (string) The CGI parameters for the saved report.
214
215 Note: If you are not logged in to Bugzilla when you call this
216 function, you will only be returned the "id", "name", and
217 "real_name" items. If you are logged in and not in "editusers"
218 group, you will only be returned the "id", "name", "real_name",
219 "email", "can_login", and "groups" items. The "groups" returned
220 are filtered based on your permission to bless each group. The
221 "saved_searches" and "saved_reports" items are only returned if you
222 are querying your own account, even if you are in the "editusers"
223 group.
224
225 Errors
226
227 51 - Bad Login Name or Group ID
228 You passed an invalid login name in the "names" array or a bad
229 group ID in the "group_ids" argument.
230
231 52 - Invalid Parameter
232 The value used must be an integer greater then zero.
233
234 304 - Authorization Required
235 You are logged in, but you are not authorized to see one of the
236 users you wanted to get information about by user ID.
237
238 505 - User Access By Id or User-Matching Denied
239 Logged-out users cannot use the "ids" or "match" arguments to this
240 function.
241
242 804 - Invalid Group Name
243 You passed a group name in the "groups" argument which either does
244 not exist or you do not belong to it.
245
246 Added in Bugzilla 4.0.9 and 4.2.4, when it also became illegal to
247 pass a group name you don't belong to.
248
249 new
250 my $user = BZ::Client::User->new( id => $id );
251
252 Creates a new instance with the given ID.
253
254 create
255 my $id = BZ::Client::User->create( $client, \%params );
256
257 Creates a user account directly in Bugzilla, password and all. Instead
258 of this, you should use "offer_account_by_email" when possible, because
259 that makes sure that the email address specified can actually receive
260 an email. This function does not check that.
261
262 You must be logged in and have the "editusers" privilege in order to
263 call this function.
264
265 Params:
266
267 email
268 email (string) - The email address for the new user.
269
270 Required.
271
272 full_name
273 full_name (string) The user's full name. Will be set to empty if
274 not specified.
275
276 password
277 password (string) The password for the new user account, in plain
278 text. It will be stripped of leading and trailing whitespace. If
279 blank or not specified, the newly created account will exist in
280 Bugzilla, but will not be allowed to log in using DB authentication
281 until a password is set either by the user (through resetting their
282 password) or by the administrator.
283
284 Returns
285
286 The numeric ID of the user that was created.
287
288 Errors
289
290 The same as "offer_account_by_email". If a password is specified, the
291 function may also throw:
292
293 502 - Password Too Short
294 The password specified is too short. (Usually, this means the
295 password is under three characters.)
296
297 503 - Password Too Long
298 Removed in Bugzilla 3.6
299
300 update
301 my $users = BZ::Client::User->update( $client, \%params );
302
303 Updates user accounts in Bugzilla.
304
305 Parameters
306
307 ids array Contains ID's of user to update.
308
309 names
310 array Contains email/login of user to update.
311
312 full_name
313 full_name (string) The new name of the user.
314
315 email
316 email (string) The email of the user. Note that email used to login
317 to bugzilla. Also note that you can only update one user at a time
318 when changing the login name / email. (An error will be thrown if
319 you try to update this field for multiple users at once.)
320
321 password
322 password (string) The password of the user.
323
324 email_enabled
325 email_enabled (boolean) A boolean value to enable/disable sending
326 bug-related mail to the user.
327
328 login_denied_text
329 login_denied_text (string) A text field that holds the reason for
330 disabling a user from logging into Bugzilla, if empty then the user
331 account is enabled otherwise it is disabled/closed.
332
333 Returns
334
335 An array of hashes with the following fields:
336
337 id id (int) The ID of the user that was updated.
338
339 changes
340 changes (hash) The changes that were actually done on this user.
341 The keys are the names of the fields that were changed, and the
342 values are a hash with two keys:
343
344 added
345 added (string) The values that were added to this field, possibly a
346 comma-and-space-separated list if multiple values were added.
347
348 removed
349 removed (string) The values that were removed from this field,
350 possibly a comma-and-space-separated list if multiple values were
351 removed.
352
353 Errors
354
355 51 - Bad Login Name
356 You passed an invalid login name in the "names" array.
357
358 304 - Authorization Required
359 Logged-in users are not authorized to edit other users.
360
362 See BZ::Client::Exception
363
365 BZ::Client, BZ::Client::API, Bugzilla API
366 <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/User.html>
367
369 • Dean Hamstead <dean@bytefoundry.com.au>
370
371 • Jochen Wiedmann <jochen.wiedmann@gmail.com>
372
374 This software is copyright (c) 2021 by Dean Hamstad.
375
376 This is free software; you can redistribute it and/or modify it under
377 the same terms as the Perl 5 programming language system itself.
378
379
380
381perl v5.34.0 2021-07-22 BZ::Client::User(3)