1BZ::Client::User(3pm) User Contributed Perl DocumentationBZ::Client::User(3pm)
2
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 my $client = BZ::Client->new( url => $url,
16 user => $user,
17 password => $password );
18 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 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 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 This is the recommended way to create a Bugzilla account.
37 Parameters
39 email
41 email (string) The email address to send the offer to.
42 Note: email can be provided as the single option as a scalar as
44 shown above.
45 Returns
47 nothing if successful
49 Errors
51 50 - Email parameter missing
53 The email parameter was not provided.
54 500 - Account Already Exists
56 An account with that email address already exists in Bugzilla.
57 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 get
64 my $users = BZ::Client::User->get( $client, \%params );
65 Gets information about user accounts in Bugzilla.
67 History
69 Added in Bugzilla 3.4
71 Parameters
73 Note: At least one of "ids", "names", or "match" must be specified.
75 Note: Users will only appear once in the returned list, even if that
77 user is matched by more than one search argument.
78 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 ids (array)
84 An array of integers, representing user ID's.
85 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 names (array)
91 An array of login names (strings).
92 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 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 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 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 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 Added in Bugzilla 4.0
120 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 Added in Bugzilla 4.0
127 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 Added in Bugzilla 4.0, default behaviour for "match" was then
136 changed to exclude disabled users.
137 Returns
139 A hash containing one item, "users", that is an array of hashes. Each
141 hash describes a user, and has the following items:
142 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 real_name
147 real_name (string) The actual name of the user. May be blank.
148 email
150 email (string) The email address of the user.
151 name
153 name (string) The login name of the user. Note that in some
154 situations this is different than their email.
155 can_login
157 can_login (boolean) A boolean value to indicate if the user can
158 login into bugzilla.
159 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 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 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 Added in Bugzilla 4.4
178 id id (int) The group ID
180 name
182 name (string) The name of the group
183 description
185 description (string) The description for the group
186 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 Added in Bugzilla 4.4
192 id id (int) An integer ID uniquely identifying the saved search.
194 name
196 name (string) The name of the saved search.
197 query
199 query (string) The CGI parameters for the saved search.
200 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 Added in Bugzilla 4.4
206 id id (int) An integer ID uniquely identifying the saved report.
208 name
210 name (string) The name of the saved report.
211 query
213 query (string) The CGI parameters for the saved report.
214 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 Errors
226 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 52 - Invalid Parameter
232 The value used must be an integer greater then zero.
233 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 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 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 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 new
250 my $user = BZ::Client::User->new( id => $id );
251 Creates a new instance with the given ID.
253 create
255 my $id = BZ::Client::User->create( $client, \%params );
256 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 You must be logged in and have the "editusers" privilege in order to
263 call this function.
264 Params:
266 email
268 email (string) - The email address for the new user.
269 Required.
271 full_name
273 full_name (string) The user's full name. Will be set to empty if
274 not specified.
275 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 Returns
285 The numeric ID of the user that was created.
287 Errors
289 The same as "offer_account_by_email". If a password is specified, the
291 function may also throw:
292 502 - Password Too Short
294 The password specified is too short. (Usually, this means the
295 password is under three characters.)
296 503 - Password Too Long
298 Removed in Bugzilla 3.6
299 update
301 my $users = BZ::Client::User->update( $client, \%params );
302 Updates user accounts in Bugzilla.
304 Parameters
306 ids array Contains ID's of user to update.
308 names
310 array Contains email/login of user to update.
311 full_name
313 full_name (string) The new name of the user.
314 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 password
322 password (string) The password of the user.
323 email_enabled
325 email_enabled (boolean) A boolean value to enable/disable sending
326 bug-related mail to the user.
327 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 Returns
334 An array of hashes with the following fields:
336 id id (int) The ID of the user that was updated.
338 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 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 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 Errors
354 51 - Bad Login Name
356 You passed an invalid login name in the "names" array.
357 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 • Jochen Wiedmann <jochen.wiedmann@gmail.com>
372
374 This software is copyright (c) 2021 by Dean Hamstad.
375 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.
378perl v5.38.0 2023-07-20 BZ::Client::User(3pm)