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

NAME

6       BZ::Client::Group - The API for creating, changing, and getting info on
7       Groups
8

VERSION

10       version 4.4002
11

SYNOPSIS

13       This class provides methods for accessing and managing Groups in
14       Bugzilla.
15
16        my $client = BZ::Client->new( url       => $url,
17                                      user      => $user,
18                                      password  => $password );
19
20        my $id = BZ::Client::Group->create( $client, \%params );
21

CLASS METHODS

23       This section lists the class methods, which are available in this
24       module.
25
26   create
27        $id = BZ::Client::Group->create( $client, \%params );
28
29       This allows you to create a new Group in Bugzilla.
30
31       History
32
33       Marked as unstable as of Bugzilla 5.0.
34
35       Parameters
36
37       Some params must be set, or an error will be thrown. These params are
38       noted as Required.
39
40       name
41           name (string) A short name for this group. Must be unique.
42
43           This is infrequently displayed in the web user interface.
44
45           Required.
46
47       description
48           description (string) A human-readable name for this group. Should
49           be relatively short.
50
51           This is what will normally appear in the UI as the name of the
52           group.
53
54           Required.
55
56       user_regexp
57           user_regexp (string) A regular expression. Any user whose Bugzilla
58           username matches this regular expression will automatically be
59           granted membership in this group.
60
61       is_active
62           is_active (boolean) True if new group can be used for bugs,
63
64           False if this is a group that will only contain users and no bugs
65           will be restricted to it.
66
67       icon_url
68           icon_url (boolean) A URL pointing to a small icon used to identify
69           the group. This icon will show up next to users' names in various
70           parts of Bugzilla if they are in this group.
71
72       Returns
73
74       The ID of the newly-created group.
75
76       Errors
77
78       800 - Empty Group Name
79           You must specify a value for the "name" field.
80
81       801 - Group Exists
82           There is already another group with the same "name".
83
84       802 - Group Missing Description
85           You must specify a value for the "description" field.
86
87       803 - Group Regexp Invalid
88           You specified an invalid regular expression in the "user_regexp"
89           field.
90
91   update
92        $id = BZ::Client::Group->update( $client, \%params );
93
94       This allows you to update a Group in Bugzilla.
95
96       History
97
98       As of Bugzilla 5.0. this is marked as unstable.
99
100       Parameters
101
102       Either "ids" or "names" is required to select the bugs you want to
103       update.
104
105       All other values change or set something in the product.
106
107       ids ids (array) Numeric ID's of the groups you wish to update.
108
109       names
110           names (array) Text names of the groups that you wish to update.
111
112       name
113           name (string) A new name for group.
114
115       description
116           description (string) A new description for groups. This is what
117           will appear in the UI as the name of the groups.
118
119       user_regexp
120           user_regexp (string) A new regular expression for email. Will
121           automatically grant membership to these groups to anyone with an
122           email address that matches this perl regular expression.
123
124       is_active
125           is_active (boolean) Set if groups are active and eligible to be
126           used for bugs. True if bugs can be restricted to this group, false
127           otherwise.
128
129       icon_url
130           icon_url (string) A URL pointing to an icon that will appear next
131           to the name of users who are in this group.
132
133       Returns
134
135       An array or arrayref of hashes containing the following:
136
137       id  id (int) The ID of the Group that was updated.
138
139       changes
140           The changes that were actually done on this Group. The keys are the
141           names of the fields that were changed, and the values are a hash
142           with two keys:
143
144           added
145               added (string)  The values that were added to this field,
146               possibly a comma-and-space-separated list if multiple values
147               were added.
148
149           removed
150               removed (string) The values that were removed from this field,
151               possibly a comma-and-space-separated list if multiple values
152               were removed.
153
154           Note that booleans will be represented with the strings 1 and <0>.
155
156       Errors
157
158       800 - Empty Group Name
159           You must specify a value for the "name" field.
160
161       801 - Group Exists
162           There is already another group with the same "name".
163
164       802 - Group Missing Description
165           You must specify a value for the "description" field.
166
167       803 - Group Regexp Invalid
168           You specified an invalid regular expression in the "user_regexp"
169           field.
170
171   get
172       Returns information about "Bugzilla::Group".
173
174       History
175
176       This function was added in Bugzilla 5.0.
177
178       Parameters
179
180       If neither "ids" or "names" is passed, and you are in the creategroups
181       or editusers group, then all groups will be retrieved.
182
183       Otherwise, only groups that you have bless privileges for will be
184       returned.
185
186       ids ids (array) Contain IDs of groups to update.
187
188       names
189           names (array) Contain names of groups to update.
190
191       membership
192           membership (boolean) Set to 1 then a list of members of the passed
193           groups' names and IDs will be returned.
194
195       Returns
196
197       If the user is a member of the "creategroups"" group they will receive
198       information about all groups or groups matching the criteria that they
199       passed. You have to be in the creategroups group unless you're
200       requesting membership information.
201
202       If the user is not a member of the Ccreategroups> group, but they are
203       in the "editusers" group or have bless privileges to the groups they
204       require membership information for, the is_active, is_bug_group and
205       user_regexp values are not supplied.
206
207       The return value will be a hash containing group names as the keys,
208       each group name will point to a hash that describes the group and has
209       the following items:
210
211       id  id (int) The unique integer ID that Bugzilla uses to identify this
212           group. Even if the name of the group changes, this ID will stay the
213           same.
214
215       name
216           name (string) The name of the group.
217
218       description
219           description (string) The description of the group.
220
221       is_bug_group
222           is_bug_group (int) Whether this groups is to be used for bug
223           reports or is only administrative specific.
224
225       user_regexp
226           user_regexp (string) A regular expression that allows users to be
227           added to this group if their login matches.
228
229       is_active
230           is_active (int) Whether this group is currently active or not.
231
232       users
233           users (array) An array of hashes, each hash contains a user object
234           for one of the members of this group, only returned if the user
235           sets the "membership" parameter to 1, the user hash has the
236           following items:
237
238           id  id (int) The ID of the user.
239
240           real_name
241               real_name (string) The actual name of the user.
242
243           email
244               emaiL (string) The email address of the user.
245
246           name
247               name (string) The login name of the user. Note that in some
248               situations this is different than their email.
249
250           can_login
251               can_login (boolean) A boolean value to indicate if the user can
252               login into bugzilla.
253
254           email_enabled
255               email_enabled (boolean) A boolean value to indicate if bug-
256               related mail will be sent to the user or not.
257
258           disabled_text
259               disabled_text (string) A text field that holds the reason for
260               disabling a user from logging into bugzilla, if empty then the
261               user account is enabled otherwise it is disabled/closed.
262
263       Errors
264
265       51 - Invalid Object
266           A non existing group name was passed to the function, as a result
267           no group object existed for that invalid name.
268
269       805 - Cannot view groups
270           Logged-in users are not authorized to edit bugzilla groups as they
271           are not members of the creategroups group in bugzilla, or they are
272           not authorized to access group member's information as they are not
273           members of the "editusers" group or can bless the group.
274

INSTANCE METHODS

276       FIXME Not yet implemented
277

EXCEPTION HANDLING

279       See BZ::Client::Exception
280

SEE ALSO

282       BZ::Client, BZ::Client::API, Bugzilla API
283       <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Group.html>
284

AUTHORS

286       ·   Dean Hamstead <dean@bytefoundry.com.au>
287
288       ·   Jochen Wiedmann <jochen.wiedmann@gmail.com>
289
291       This software is copyright (c) 2017 by Dean Hamstad.
292
293       This is free software; you can redistribute it and/or modify it under
294       the same terms as the Perl 5 programming language system itself.
295
296
297
298perl v5.32.0                      2020-07-28              BZ::Client::Group(3)
Impressum