ruby-jss 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of ruby-jss might be problematic. Click here for more details.

Files changed (73) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +7 -0
  3. data/CHANGES.md +112 -0
  4. data/LICENSE.txt +174 -0
  5. data/README.md +426 -0
  6. data/THANKS.md +6 -0
  7. data/bin/cgrouper +485 -0
  8. data/bin/subnet-update +400 -0
  9. data/lib/jss-api.rb +2 -0
  10. data/lib/jss.rb +190 -0
  11. data/lib/jss/api_connection.rb +410 -0
  12. data/lib/jss/api_object.rb +616 -0
  13. data/lib/jss/api_object/advanced_search.rb +389 -0
  14. data/lib/jss/api_object/advanced_search/advanced_computer_search.rb +95 -0
  15. data/lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb +96 -0
  16. data/lib/jss/api_object/advanced_search/advanced_user_search.rb +95 -0
  17. data/lib/jss/api_object/building.rb +92 -0
  18. data/lib/jss/api_object/category.rb +147 -0
  19. data/lib/jss/api_object/computer.rb +852 -0
  20. data/lib/jss/api_object/creatable.rb +98 -0
  21. data/lib/jss/api_object/criteriable.rb +189 -0
  22. data/lib/jss/api_object/criteriable/criteria.rb +231 -0
  23. data/lib/jss/api_object/criteriable/criterion.rb +228 -0
  24. data/lib/jss/api_object/department.rb +93 -0
  25. data/lib/jss/api_object/distribution_point.rb +560 -0
  26. data/lib/jss/api_object/extendable.rb +221 -0
  27. data/lib/jss/api_object/extension_attribute.rb +466 -0
  28. data/lib/jss/api_object/extension_attribute/computer_extension_attribute.rb +362 -0
  29. data/lib/jss/api_object/extension_attribute/mobile_device_extension_attribute.rb +189 -0
  30. data/lib/jss/api_object/extension_attribute/user_extension_attribute.rb +117 -0
  31. data/lib/jss/api_object/group.rb +380 -0
  32. data/lib/jss/api_object/group/computer_group.rb +124 -0
  33. data/lib/jss/api_object/group/mobile_device_group.rb +139 -0
  34. data/lib/jss/api_object/group/user_group.rb +139 -0
  35. data/lib/jss/api_object/ldap_server.rb +535 -0
  36. data/lib/jss/api_object/locatable.rb +286 -0
  37. data/lib/jss/api_object/matchable.rb +97 -0
  38. data/lib/jss/api_object/mobile_device.rb +556 -0
  39. data/lib/jss/api_object/netboot_server.rb +148 -0
  40. data/lib/jss/api_object/network_segment.rb +414 -0
  41. data/lib/jss/api_object/osx_configuration_profile.rb +262 -0
  42. data/lib/jss/api_object/package.rb +839 -0
  43. data/lib/jss/api_object/peripheral.rb +335 -0
  44. data/lib/jss/api_object/peripheral_type.rb +295 -0
  45. data/lib/jss/api_object/policy.rb +898 -0
  46. data/lib/jss/api_object/purchasable.rb +316 -0
  47. data/lib/jss/api_object/removable_macaddr.rb +98 -0
  48. data/lib/jss/api_object/scopable.rb +136 -0
  49. data/lib/jss/api_object/scopable/scope.rb +621 -0
  50. data/lib/jss/api_object/script.rb +631 -0
  51. data/lib/jss/api_object/self_servable.rb +356 -0
  52. data/lib/jss/api_object/site.rb +93 -0
  53. data/lib/jss/api_object/software_update_server.rb +109 -0
  54. data/lib/jss/api_object/updatable.rb +117 -0
  55. data/lib/jss/api_object/uploadable.rb +138 -0
  56. data/lib/jss/api_object/user.rb +272 -0
  57. data/lib/jss/client.rb +504 -0
  58. data/lib/jss/compatibility.rb +66 -0
  59. data/lib/jss/composer.rb +185 -0
  60. data/lib/jss/configuration.rb +306 -0
  61. data/lib/jss/db_connection.rb +298 -0
  62. data/lib/jss/exceptions.rb +95 -0
  63. data/lib/jss/ruby_extensions.rb +35 -0
  64. data/lib/jss/ruby_extensions/filetest.rb +43 -0
  65. data/lib/jss/ruby_extensions/hash.rb +79 -0
  66. data/lib/jss/ruby_extensions/ipaddr.rb +91 -0
  67. data/lib/jss/ruby_extensions/pathname.rb +77 -0
  68. data/lib/jss/ruby_extensions/string.rb +59 -0
  69. data/lib/jss/ruby_extensions/time.rb +63 -0
  70. data/lib/jss/server.rb +108 -0
  71. data/lib/jss/utility.rb +478 -0
  72. data/lib/jss/version.rb +31 -0
  73. metadata +187 -0
@@ -0,0 +1,117 @@
1
+ ### Copyright 2016 Pixar
2
+ ###
3
+ ### Licensed under the Apache License, Version 2.0 (the "Apache License")
4
+ ### with the following modification; you may not use this file except in
5
+ ### compliance with the Apache License and the following modification to it:
6
+ ### Section 6. Trademarks. is deleted and replaced with:
7
+ ###
8
+ ### 6. Trademarks. This License does not grant permission to use the trade
9
+ ### names, trademarks, service marks, or product names of the Licensor
10
+ ### and its affiliates, except as required to comply with Section 4(c) of
11
+ ### the License and to reproduce the content of the NOTICE file.
12
+ ###
13
+ ### You may obtain a copy of the Apache License at
14
+ ###
15
+ ### http://www.apache.org/licenses/LICENSE-2.0
16
+ ###
17
+ ### Unless required by applicable law or agreed to in writing, software
18
+ ### distributed under the Apache License with the above modification is
19
+ ### distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20
+ ### KIND, either express or implied. See the Apache License for the specific
21
+ ### language governing permissions and limitations under the Apache License.
22
+ ###
23
+ ###
24
+
25
+ ###
26
+ module JSS
27
+
28
+
29
+
30
+ #####################################
31
+ ### Constants
32
+ #####################################
33
+
34
+ #####################################
35
+ ### Module Variables
36
+ #####################################
37
+
38
+ #####################################
39
+ ### Module Methods
40
+ #####################################
41
+
42
+ ####################################
43
+ ### Classes
44
+ #####################################
45
+
46
+
47
+ ###
48
+ ### A User extension attribute as defined in the JSS
49
+ ###
50
+ ### @see JSS::ExtensionAttribute
51
+ ### @see JSS::APIObject
52
+ ###
53
+ class UserExtensionAttribute < JSS::ExtensionAttribute
54
+
55
+ #####################################
56
+ ### Mix-Ins
57
+ #####################################
58
+
59
+ #####################################
60
+ ### Class Methods
61
+ #####################################
62
+
63
+ #####################################
64
+ ### Class Constants
65
+ #####################################
66
+
67
+ ### The base for REST resources of this class
68
+ RSRC_BASE = "userextensionattributes"
69
+
70
+ ### the hash key used for the JSON list output of all objects in the JSS
71
+ RSRC_LIST_KEY = :user_extension_attributes
72
+
73
+ ### The hash key used for the JSON object output.
74
+ ### It's also used in various error messages
75
+ RSRC_OBJECT_KEY = :user_extension_attribute
76
+
77
+ ### these keys, as well as :id and :name, are present in valid API JSON data for this class
78
+ VALID_DATA_KEYS = [:description, :data_type, :input_type]
79
+
80
+ ### these ext attribs are related to these kinds of objects
81
+ TARGET_CLASS = JSS::User
82
+
83
+ ### A criterion that will return all members of the TARGET_CLASS
84
+ ALL_TARGETS_CRITERION = JSS::Criteriable::Criterion.new(:and_or => "and", :name => "Username", :search_type => "like", :value => '')
85
+
86
+ ######################
87
+ ### Attributes
88
+ ######################
89
+
90
+ #####################################
91
+ ### Constructor
92
+ #####################################
93
+
94
+ #####################################
95
+ ### Public Instance Methods
96
+ #####################################
97
+
98
+ ######################
99
+ ### Private Instance Methods
100
+ #####################
101
+ private
102
+
103
+ ###
104
+ ### Return the REST XML for this item, with the current values,
105
+ ### for saving or updating
106
+ ###
107
+ def rest_xml
108
+ uea = rest_rexml
109
+ doc = REXML::Document.new APIConnection::XML_HEADER
110
+ doc << uea
111
+ return doc.to_s
112
+ end # rest xml
113
+
114
+ end # class ExtAttrib
115
+
116
+
117
+ end # module
@@ -0,0 +1,380 @@
1
+ ### Copyright 2016 Pixar
2
+ ###
3
+ ### Licensed under the Apache License, Version 2.0 (the "Apache License")
4
+ ### with the following modification; you may not use this file except in
5
+ ### compliance with the Apache License and the following modification to it:
6
+ ### Section 6. Trademarks. is deleted and replaced with:
7
+ ###
8
+ ### 6. Trademarks. This License does not grant permission to use the trade
9
+ ### names, trademarks, service marks, or product names of the Licensor
10
+ ### and its affiliates, except as required to comply with Section 4(c) of
11
+ ### the License and to reproduce the content of the NOTICE file.
12
+ ###
13
+ ### You may obtain a copy of the Apache License at
14
+ ###
15
+ ### http://www.apache.org/licenses/LICENSE-2.0
16
+ ###
17
+ ### Unless required by applicable law or agreed to in writing, software
18
+ ### distributed under the Apache License with the above modification is
19
+ ### distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20
+ ### KIND, either express or implied. See the Apache License for the specific
21
+ ### language governing permissions and limitations under the Apache License.
22
+ ###
23
+ ###
24
+
25
+ ###
26
+ module JSS
27
+
28
+ #####################################
29
+ ### Module Constants
30
+ #####################################
31
+
32
+ #####################################
33
+ ### Module Variables
34
+ #####################################
35
+
36
+ #####################################
37
+ ### Module Methods
38
+ #####################################
39
+
40
+ #####################################
41
+ ### Classes
42
+ #####################################
43
+
44
+ ###
45
+ ### This is the parent class of the smart/static group objects in the JSS
46
+ ### namely, {ComputerGroup}, {MobileDeviceGroup}, and {UserGroup}
47
+ ###
48
+ ### It provides methods for working with the membership of static groups and, by
49
+ ### including {JSS::Criteriable}, the criteria for smart groups.
50
+ ###
51
+ ### When changing the criteria of a smart group, use the #criteria attribute,
52
+ ### which is a {JSS::Criteria} instance.
53
+ ###
54
+ ### Subclasses must define the constant MEMBER_CLASS which indicates Ruby class
55
+ ### to which the group members belong (e.g. JSS::MobileDevice)
56
+ ###
57
+ ### @see JSS::APIObject
58
+ ###
59
+ ### @see JSS::Criteriable
60
+ ###
61
+ class Group < JSS::APIObject
62
+
63
+ #####################################
64
+ ### Mix-Ins
65
+ #####################################
66
+ include JSS::Creatable
67
+ include JSS::Updatable
68
+ include JSS::Criteriable
69
+
70
+
71
+ #####################################
72
+ ### Class Constants
73
+ #####################################
74
+
75
+ ### the types of groups allowed for creation
76
+ GROUP_TYPES = [:smart, :static]
77
+
78
+ #####################################
79
+ ### Class Variables
80
+ #####################################
81
+
82
+ #####################################
83
+ ### Class Methods
84
+ #####################################
85
+
86
+ ###
87
+ ### Returns an Array of all the smart
88
+ ### groups.
89
+ ###
90
+ def self.all_smart(refresh = false)
91
+ self.all(refresh).select{|g| g[:is_smart] }
92
+ end
93
+
94
+ ###
95
+ ### Returns an Array of all the static
96
+ ### groups.
97
+ ###
98
+ def self.all_static(refresh = false)
99
+ self.all(refresh).select{|g| not g[:is_smart] }
100
+ end
101
+
102
+ #####################################
103
+ ### Attributes
104
+ #####################################
105
+
106
+ ### @return [Array<Hash>] the group membership
107
+ ###
108
+ ### Each hash contains the identifiers for
109
+ ### a member of the group, those being:
110
+ ### - :id, :name, and possibly :udid, :serial_number, :mac_address, :alt_mac_address, and :wifi_mac_address
111
+ ###
112
+ ### @see #member_ids
113
+ ###
114
+ ### @see #member_names
115
+ ###
116
+ attr_reader :members
117
+
118
+ ### @return [Boolean] is this a smart group
119
+ attr_reader :is_smart
120
+
121
+ ### @return [Boolean] does this group send notifications when it changes?
122
+ attr_reader :notify_on_change
123
+
124
+
125
+ ### @return [String] the :name of the site for this group
126
+ attr_reader :site
127
+
128
+
129
+ #####################################
130
+ ### Constructor
131
+ #####################################
132
+
133
+ ###
134
+ ### When creating a new group in the JSS, you must call .new with a :type key
135
+ ### and a value of :smart or :static, as well as a :name and the :id => :new
136
+ ###
137
+ ### @see JSS::APIObject
138
+ ###
139
+ def initialize(args = {})
140
+
141
+ if args[:id] == :new
142
+ raise JSS::InvalidDataError, "New group creation must specify a :type of :smart or :static" unless GROUP_TYPES.include? args[:type]
143
+ end
144
+
145
+ super args
146
+
147
+ @is_smart = @init_data[:is_smart] || (args[:type] == :smart)
148
+
149
+ @members = if @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY]
150
+ @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY]
151
+ else
152
+ []
153
+ end
154
+
155
+ @site = JSS::APIObject.get_name(@init_data[:site])
156
+
157
+ parse_criteria
158
+
159
+ end #init
160
+
161
+ #####################################
162
+ ### Public Instance Methods
163
+ #####################################
164
+
165
+ ###
166
+ ### @see Creatable#create
167
+ ###
168
+ def create
169
+ if @is_smart
170
+ raise JSS::MissingDataError, "No criteria specified for smart group" unless @criteria
171
+ end
172
+ super
173
+ refresh_members
174
+ return @id
175
+ end
176
+
177
+
178
+ ###
179
+ ### @see Updatable#update
180
+ ###
181
+ def update
182
+ super
183
+ refresh_members
184
+ true
185
+ end
186
+
187
+ ###
188
+ ### @see APIObject#delete
189
+ ###
190
+ def delete
191
+ super
192
+ @is_smart = nil
193
+ @criteria = nil
194
+ @site = nil
195
+ @members = []
196
+ end # delete
197
+
198
+ ###
199
+ ### Apply a new set of criteria to a smart group
200
+ ###
201
+ ### @param new_criteria[JSS::Criteria] the new criteria for the smart group
202
+ ###
203
+ def criteria= (new_criteria)
204
+ raise InvalidDataError, "Only smart groups have criteria." unless @is_smart
205
+ super
206
+ end
207
+
208
+ ###
209
+ ### How many members of the group?
210
+ ###
211
+ ### @return [Integer] the number of members of the group
212
+ ###
213
+ def size
214
+ @members.count
215
+ end
216
+
217
+
218
+ ###
219
+ ### @return [Array<String>] the names of the group members
220
+ ###
221
+ def member_names
222
+ @members.map{|m| m[:name]}
223
+ end
224
+
225
+ ###
226
+ ### @return [Array<Integer>] the ids of the group members
227
+ ###
228
+ def member_ids
229
+ @members.map{|m| m[:id]}
230
+ end
231
+
232
+ ###
233
+ ### Replace all @members with an array of uniq device identfiers (names, ids, serial numbers, etc)
234
+ ### E.g: [ 'lambic', 1233, '2341', 'monkey']
235
+ ###
236
+ ### They must all be in the JSS or an error is raised
237
+ ### before doing anything. See {#check_member}
238
+ ###
239
+ ### @param new_members[Array<Integer,String>] the new group members
240
+ ###
241
+ ### @return [void]
242
+ ###
243
+ def members= (new_members)
244
+ raise UnsupportedError, "Smart group members can't be changed." if @is_smart
245
+ raise InvalidDataError, "Arg must be an array of names and/or ids" unless new_members.kind_of? Array
246
+ ok_members = []
247
+ new_members.each do |m|
248
+ ok_members << check_member(m)
249
+ end
250
+
251
+ ok_members.uniq!
252
+
253
+ ### make sure we've actually changed...
254
+ unless members.map{|m| m[:id]}.sort == ok_members.map{|m| m[:id]}.sort
255
+ @members = ok_members
256
+ @need_to_update = true
257
+ end
258
+ end
259
+
260
+ ###
261
+ ### Add a member, by name or id
262
+ ###
263
+ ### @param m[Integer,String] the id or name of the member to add
264
+ ###
265
+ ### @return [void]
266
+ ###
267
+ def add_member(m)
268
+ raise UnsupportedError, "Smart group members can't be changed." if @is_smart
269
+ @members << check_member(m)
270
+ @need_to_update = true
271
+ end
272
+
273
+ ###
274
+ ### Remove a member by id, or name
275
+ ###
276
+ ### @param m[Integer,String] the id or name of the member to remove
277
+ ###
278
+ ### @return [void]
279
+ ###
280
+ def remove_member(m)
281
+ raise InvalidDataError, "Smart group members can't be changed." if @is_smart
282
+
283
+ if @members.reject!{ |mm| [mm[:id], mm[:name]].include? m }
284
+ @need_to_update = true
285
+ else
286
+ raise JSS::NoSuchItemError, "No member matches '#{m}'"
287
+ end
288
+ end
289
+
290
+ ###
291
+ ### Remove all members
292
+ ###
293
+ ### @return [void]
294
+ ###
295
+ def clear
296
+ raise InvalidDataError, "Smart group members can't be changed." if @is_smart
297
+ return if @members.empty?
298
+ @members.clear
299
+ @need_to_update = true
300
+ end
301
+
302
+ ###
303
+ ### Refresh the membership from the API
304
+ ###
305
+ ### @return [Array<Hash>] the refresh membership
306
+ ###
307
+ def refresh_members
308
+ @members = JSS::API.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY]
309
+ end
310
+
311
+ ###
312
+ ### Change the site for this group
313
+ ###
314
+ ### @param new_val[String] the name of the new site
315
+ ###
316
+ ### @return [void]
317
+ ###
318
+ def site= (new_val)
319
+ raise JSS::NoSuchItemError, "No site named #{new_val} in the JSS" unless JSS::Site.all_names.include? new_val
320
+ @site = new_val
321
+ @need_to_update = true
322
+ end
323
+
324
+
325
+ ### aliases
326
+
327
+ alias smart? is_smart
328
+ alias notify_on_change? notify_on_change
329
+ alias notify? notify_on_change
330
+ alias count size
331
+
332
+ #####################################
333
+ ### Public Instance Methods
334
+ #####################################
335
+ private
336
+
337
+ ###
338
+ ### Check that a potential group member is valid in the JSS.
339
+ ### Arg must be an id or name.
340
+ ### An exception is raised if the device doesn't exist.
341
+ ###
342
+ ### @return [Hash{:id=>Integer,:name=>String}] the valid id and name
343
+ ###
344
+ def check_member(m)
345
+ potential_members = self.class::MEMBER_CLASS.map_all_ids_to(:name)
346
+ if m.to_s =~ /\d+/
347
+ return {:id=>m.to_i, :name=> potential_members[m]} if potential_members.keys.include? m.to_i
348
+ else
349
+ return {:name=>m, :id=> potential_members.invert[m]} if potential_members.values.include? m
350
+ end
351
+ raise JSS::NoSuchItemError, "No #{self.class::MEMBER_CLASS::RSRC_OBJECT_KEY} matching '#{m}' in the JSS."
352
+ end
353
+
354
+ ###
355
+ ### the xml formated data for adding or updating this in the JSS,
356
+ ###
357
+ def rest_xml
358
+ doc = REXML::Document.new JSS::APIConnection::XML_HEADER
359
+ group = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
360
+ group.add_element('name').text = @name
361
+ group.add_element('site').add_element('name').text = @site if @site
362
+ group.add_element('is_smart').text = @is_smart
363
+ if @is_smart
364
+ group << @criteria.rest_xml if @criteria
365
+ else
366
+ group << self.class::MEMBER_CLASS.xml_list(@members, :id)
367
+ end
368
+
369
+ return doc.to_s
370
+
371
+ end #rest_xml
372
+
373
+ end # class ComputerGroup
374
+
375
+ end # module JSS
376
+
377
+ require "jss/api_object/group/computer_group"
378
+ require "jss/api_object/group/mobile_device_group"
379
+ require "jss/api_object/group/user_group"
380
+