1BZ::Client::Group(3) User Contributed Perl Documentation BZ::Client::Group(3)
2
6 BZ::Client::Group - The API for creating, changing, and getting info on
7 Groups
8
10 version 4.4002
11
13 This class provides methods for accessing and managing Groups in
14 Bugzilla.
15 my $client = BZ::Client->new( url => $url,
17 user => $user,
18 password => $password );
19 my $id = BZ::Client::Group->create( $client, \%params );
21
23 This section lists the class methods, which are available in this
24 module.
25 create
27 $id = BZ::Client::Group->create( $client, \%params );
28 This allows you to create a new Group in Bugzilla.
30 History
32 Marked as unstable as of Bugzilla 5.0.
34 Parameters
36 Some params must be set, or an error will be thrown. These params are
38 noted as Required.
39 name
41 name (string) A short name for this group. Must be unique.
42 This is infrequently displayed in the web user interface.
44 Required.
46 description
48 description (string) A human-readable name for this group. Should
49 be relatively short.
50 This is what will normally appear in the UI as the name of the
52 group.
53 Required.
55 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 is_active
62 is_active (boolean) True if new group can be used for bugs,
63 False if this is a group that will only contain users and no bugs
65 will be restricted to it.
66 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 Returns
73 The ID of the newly-created group.
75 Errors
77 800 - Empty Group Name
79 You must specify a value for the "name" field.
80 801 - Group Exists
82 There is already another group with the same "name".
83 802 - Group Missing Description
85 You must specify a value for the "description" field.
86 803 - Group Regexp Invalid
88 You specified an invalid regular expression in the "user_regexp"
89 field.
90 update
92 $id = BZ::Client::Group->update( $client, \%params );
93 This allows you to update a Group in Bugzilla.
95 History
97 As of Bugzilla 5.0. this is marked as unstable.
99 Parameters
101 Either "ids" or "names" is required to select the bugs you want to
103 update.
104 All other values change or set something in the product.
106 ids ids (array) Numeric ID's of the groups you wish to update.
108 names
110 names (array) Text names of the groups that you wish to update.
111 name
113 name (string) A new name for group.
114 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 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 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 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 Returns
134 An array or arrayref of hashes containing the following:
136 id id (int) The ID of the Group that was updated.
138 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 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 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 Note that booleans will be represented with the strings 1 and <0>.
155 Errors
157 800 - Empty Group Name
159 You must specify a value for the "name" field.
160 801 - Group Exists
162 There is already another group with the same "name".
163 802 - Group Missing Description
165 You must specify a value for the "description" field.
166 803 - Group Regexp Invalid
168 You specified an invalid regular expression in the "user_regexp"
169 field.
170 get
172 Returns information about "Bugzilla::Group".
173 History
175 This function was added in Bugzilla 5.0.
177 Parameters
179 If neither "ids" or "names" is passed, and you are in the creategroups
181 or editusers group, then all groups will be retrieved.
182 Otherwise, only groups that you have bless privileges for will be
184 returned.
185 ids ids (array) Contain IDs of groups to update.
187 names
189 names (array) Contain names of groups to update.
190 membership
192 membership (boolean) Set to 1 then a list of members of the passed
193 groups' names and IDs will be returned.
194 Returns
196 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 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 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 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 name
216 name (string) The name of the group.
217 description
219 description (string) The description of the group.
220 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 user_regexp
226 user_regexp (string) A regular expression that allows users to be
227 added to this group if their login matches.
228 is_active
230 is_active (int) Whether this group is currently active or not.
231 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 id id (int) The ID of the user.
239 real_name
241 real_name (string) The actual name of the user.
242 email
244 emaiL (string) The email address of the user.
245 name
247 name (string) The login name of the user. Note that in some
248 situations this is different than their email.
249 can_login
251 can_login (boolean) A boolean value to indicate if the user can
252 login into bugzilla.
253 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 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 Errors
264 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 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
276 FIXME Not yet implemented
277
279 See BZ::Client::Exception
280
282 BZ::Client, BZ::Client::API, Bugzilla API
283 <https://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Group.html>
284
286 · Dean Hamstead <dean@bytefoundry.com.au>
287 · Jochen Wiedmann <jochen.wiedmann@gmail.com>
289
291 This software is copyright (c) 2017 by Dean Hamstad.
292 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.
295perl v5.30.1 2020-01-29 BZ::Client::Group(3)