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

NAME

6       BZ::Client::User - Creates and edits user accounts in Bugzilla
7

VERSION

9       version 4.4004
10

SYNOPSIS

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

CLASS METHODS

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

EXCEPTION HANDLING

362       See BZ::Client::Exception
363

SEE ALSO

365       BZ::Client, BZ::Client::API, Bugzilla API
366       <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/User.html>
367

AUTHORS

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)
Impressum