1# This Source Code Form is subject to the terms of the Mozilla Public
2# License, v. 2.0. If a copy of the MPL was not distributed with this
3# file, You can obtain one at http://mozilla.org/MPL/2.0/.
4#
5# This Source Code Form is "Incompatible With Secondary Licenses", as
6# defined by the Mozilla Public License, v. 2.0.
7
8package Bugzilla::WebService::Classification;
9
10use strict;
11
12use base qw (Bugzilla::WebService);
13
14use Bugzilla::Classification;
15use Bugzilla::Error;
16use Bugzilla::WebService::Util qw(filter validate params_to_objects);
17
18use constant READ_ONLY => qw(
19    get
20);
21
22use constant PUBLIC_METHODS => qw(
23    get
24);
25
26sub get {
27    my ($self, $params) = validate(@_, 'names', 'ids');
28
29    defined $params->{names} || defined $params->{ids}
30        || ThrowCodeError('params_required', { function => 'Classification.get',
31                                               params => ['names', 'ids'] });
32
33    my $user = Bugzilla->user;
34
35    Bugzilla->params->{'useclassification'}
36      || $user->in_group('editclassifications')
37      || ThrowUserError('auth_classification_not_enabled');
38
39    Bugzilla->switch_to_shadow_db;
40
41    my @classification_objs = @{ params_to_objects($params, 'Bugzilla::Classification') };
42    unless ($user->in_group('editclassifications')) {
43        my %selectable_class = map { $_->id => 1 } @{$user->get_selectable_classifications};
44        @classification_objs = grep { $selectable_class{$_->id} } @classification_objs;
45    }
46
47    my @classifications = map { filter($params, $self->_classification_to_hash($_)) } @classification_objs;
48
49    return { classifications => \@classifications };
50}
51
52sub _classification_to_hash {
53    my ($self, $classification) = @_;
54
55    my $user = Bugzilla->user;
56    return unless (Bugzilla->params->{'useclassification'} || $user->in_group('editclassifications'));
57
58    my $products = $user->in_group('editclassifications') ?
59                     $classification->products : $user->get_selectable_products($classification->id);
60    my %hash = (
61        id          => $self->type('int',    $classification->id),
62        name        => $self->type('string', $classification->name),
63        description => $self->type('string', $classification->description),
64        sort_key    => $self->type('int',    $classification->sortkey),
65        products    => [ map { $self->_product_to_hash($_) } @$products ],
66    );
67
68    return \%hash;
69}
70
71sub _product_to_hash {
72    my ($self, $product) = @_;
73    my %hash = (
74       id          => $self->type('int', $product->id),
75       name        => $self->type('string', $product->name),
76       description => $self->type('string', $product->description),
77   );
78
79   return \%hash;
80}
81
821;
83
84__END__
85
86=head1 NAME
87
88Bugzilla::Webservice::Classification - The Classification API
89
90=head1 DESCRIPTION
91
92This part of the Bugzilla API allows you to deal with the available Classifications.
93You will be able to get information about them as well as manipulate them.
94
95=head1 METHODS
96
97See L<Bugzilla::WebService> for a description of how parameters are passed,
98and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.
99
100=head1 Classification Retrieval
101
102=head2 get
103
104B<EXPERIMENTAL>
105
106=over
107
108=item B<Description>
109
110Returns a hash containing information about a set of classifications.
111
112=item B<Params>
113
114In addition to the parameters below, this method also accepts the
115standard L<include_fields|Bugzilla::WebService/include_fields> and
116L<exclude_fields|Bugzilla::WebService/exclude_fields> arguments.
117
118You could get classifications info by supplying their names and/or ids.
119So, this method accepts the following parameters:
120
121=over
122
123=item C<ids>
124
125An array of classification ids.
126
127=item C<names>
128
129An array of classification names.
130
131=back
132
133=item B<Returns>
134
135A hash with the key C<classifications> and an array of hashes as the corresponding value.
136Each element of the array represents a classification that the user is authorized to see
137and has the following keys:
138
139=over
140
141=item C<id>
142
143C<int> The id of the classification.
144
145=item C<name>
146
147C<string> The name of the classification.
148
149=item C<description>
150
151C<string> The description of the classificaion.
152
153=item C<sort_key>
154
155C<int> The value which determines the order the classification is sorted.
156
157=item C<products>
158
159An array of hashes. The array contains the products the user is authorized to
160access within the classification. Each hash has the following keys:
161
162=over
163
164=item C<name>
165
166C<string> The name of the product.
167
168=item C<id>
169
170C<int> The id of the product.
171
172=item C<description>
173
174C<string> The description of the product.
175
176=back
177
178=back
179
180=item B<Errors>
181
182=over
183
184=item 900 (Classification not enabled)
185
186Classification is not enabled on this installation.
187
188=back
189
190=item B<History>
191
192=over
193
194=item Added in Bugzilla B<4.4>.
195
196=back
197
198=back
199
200