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,362 @@
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
+ ### The definition of a Computer extension attribute in the JSS
49
+ ###
50
+ ### @see JSS::ExtensionAttribute
51
+ ###
52
+ ### @see JSS::APIObject
53
+ ###
54
+ class ComputerExtensionAttribute < JSS::ExtensionAttribute
55
+
56
+ #####################################
57
+ ### Mix-Ins
58
+ #####################################
59
+
60
+ #####################################
61
+ ### Class Methods
62
+ #####################################
63
+
64
+ #####################################
65
+ ### Class Constants
66
+ #####################################
67
+
68
+ ### The base for REST resources of this class
69
+ RSRC_BASE = "computerextensionattributes"
70
+
71
+ ### the hash key used for the JSON list output of all objects in the JSS
72
+ RSRC_LIST_KEY = :computer_extension_attributes
73
+
74
+ ### The hash key used for the JSON object output.
75
+ ### It's also used in various error messages
76
+ RSRC_OBJECT_KEY = :computer_extension_attribute
77
+
78
+ ### these keys, as well as :id and :name, are present in valid API JSON data for this class
79
+ VALID_DATA_KEYS = [:description, :inventory_display, :recon_display]
80
+
81
+ ### these ext attribs are related to these kinds of objects
82
+ TARGET_CLASS = JSS::Computer
83
+
84
+ ### A criterion that will return all members of the TARGET_CLASS
85
+ ALL_TARGETS_CRITERION = JSS::Criteriable::Criterion.new(:and_or => "and", :name => "Username", :search_type => "like", :value => '')
86
+
87
+ ### When the intput type is script, what platforms can they run on?
88
+ PLATFORMS = ["Mac","Windows"]
89
+
90
+ ### When the platform is Windows, what languages can be user?
91
+ WINDOWS_SCRIPTING_LANGUAGES = ["VBScript", "Batch File", "PowerShell"]
92
+
93
+ ### Where can it be displayed in the Recon App?
94
+ RECON_DISPLAY_CHOICES = [
95
+ "Computer",
96
+ "User and Location",
97
+ "Purchasing",
98
+ "Extension Attributes"
99
+ ]
100
+
101
+ DEFAULT_RECON_DISPLAY_CHOICE = "Extension Attributes"
102
+
103
+ ######################
104
+ ### Attributes
105
+ ######################
106
+
107
+ ### When the @input_type is "script", The platform on which a script will run.
108
+ ###
109
+ ### NOTE: The web app seems to let you have both Mac and Windows
110
+ ### scripts defined when the type is "script",
111
+ ### however the API will only return the Mac script info if both are defined.
112
+ ###
113
+ ### @return [String]
114
+ attr_reader :platform
115
+
116
+ ### @return [String] the script code that will be executed when the @input_type is "script",
117
+ attr_reader :script
118
+
119
+
120
+ ### The scripting language of the @script when @input_type is "script",
121
+ ### and the @platform is "Windows"
122
+ ###
123
+ ### @return [String]
124
+ attr_reader :scripting_language
125
+
126
+ ### @return [String] In which part of the Recon App does the data appear?
127
+ attr_reader :recon_display
128
+
129
+ #####################################
130
+ ### Constructor
131
+ #####################################
132
+
133
+ ###
134
+ ### @see JSS::APIObject#initialize
135
+ ###
136
+ def initialize(args = {})
137
+
138
+ super args
139
+
140
+ @recon_display = @init_data[:recon_display] || DEFAULT_RECON_DISPLAY_CHOICE
141
+
142
+ if @init_data[:input_type]
143
+ @platform = @init_data[:input_type][:platform]
144
+ @script = @init_data[:input_type][:script]
145
+ @scripting_language = @init_data[:input_type][:scripting_language]
146
+ end
147
+ end # init
148
+
149
+
150
+ #####################################
151
+ ### Public Instance Methods
152
+ #####################################
153
+
154
+ ###
155
+ ### @see JSS::Creatable#create
156
+ ###
157
+ ### @return [Integer] the JSS id of the newly created object
158
+ ###
159
+ def create
160
+ if @input_type == "script"
161
+ raise MissingDataError, "No platform set for script input_type." unless @platform
162
+ raise MissingDataError, "No script set for script input_type." unless @script
163
+ if @platform == "Windows"
164
+ raise MissingDataError, "No scripting_language set for Windows script input_type." unless @scripting_language
165
+ end
166
+ end # case
167
+
168
+ super
169
+ end
170
+
171
+ ###
172
+ ### Change the recon_display of this EA
173
+ ###
174
+ def recon_display= (new_val)
175
+ return nil if @recon_display == new_val
176
+ raise JSS::InvalidDataError, "recon_display must be a string, one of: #{RECON_DISPLAY_CHOICES.join(", ")}" unless RECON_DISPLAY_CHOICES.include? new_val
177
+ @recon_display = new_val
178
+ @need_to_update = true
179
+ end #
180
+
181
+
182
+ ###
183
+ ### Change the input type of this EA
184
+ ###
185
+ ### @see JSS::ExtensionAttribute#input_type=
186
+ ###
187
+ ### @return [void]
188
+ ###
189
+ def input_type= (new_val)
190
+ raise JSS::InvalidDataError, "ComputerExtensionAttribute input_types cannot be 'LDAP Attribute Mapping'" if new_val == 'LDAP Attribute Mapping'
191
+
192
+ super
193
+
194
+ case @input_type
195
+ when *["Text Field","Pop-up Menu"]
196
+ @script = nil
197
+ @scripting_language = nil
198
+ @platform = nil
199
+ when "script"
200
+ @popup_choices = nil
201
+ end # case
202
+ end #
203
+
204
+ ###
205
+ ### This unsets any script-related attributes
206
+ ###
207
+ ### @param (see JSS::ExtensionAttribute#popup_choices=)
208
+ ###
209
+ ### @return [void]
210
+ ###
211
+ def popup_choices= (new_val)
212
+ super
213
+ @script = nil
214
+ @scripting_language = nil
215
+ @platform = nil
216
+ end #
217
+
218
+ ###
219
+ ### Change the platform of this EA.
220
+ ### Setting this automatically sets input_type to script
221
+ ###
222
+ ### @param new_val[String] the new value, which must be a member of PLATFORMS
223
+ ###
224
+ ### @return [void]
225
+ ###
226
+ def platform= (new_val)
227
+ return nil if @platform == new_val
228
+ raise JSS::InvalidDataError, "platform must be a string, one of: #{PLATFORMS.join(", ")}" unless PLATFORMS.include? new_val
229
+ self.input_type = "script"
230
+ @platform = new_val
231
+ @need_to_update = true
232
+ end #
233
+
234
+ ###
235
+ ### Change the script of this EA.
236
+ ### Setting this automatically sets input_type to script
237
+ ###
238
+ ### @param new_val[String] the new value
239
+ ###
240
+ ### @return [void]
241
+ ###
242
+ def script= (new_val)
243
+ return nil if @script == new_val
244
+ self.input_type = "script"
245
+ @script = new_val
246
+ @need_to_update = true
247
+ end #
248
+
249
+
250
+ ###
251
+ ### Change the scripting_language of this EA.
252
+ ### Setting this automatically sets input_type to 'script'
253
+ ### and the platform to "Windows"
254
+ ###
255
+ ### @param new_val[String] the new value, which must be one of {WINDOWS_SCRIPTING_LANGUAGES}
256
+ ###
257
+ ### @return [void]
258
+ ###
259
+ def scripting_language= (new_val)
260
+ return nil if @scripting_language == new_val
261
+ raise JSS::InvalidDataError, "Scripting language must be a string, one of: #{WINDOWS_SCRIPTING_LANGUAGES.join(", ")}" unless WINDOWS_SCRIPTING_LANGUAGES.include? new_val
262
+ self.input_type = "script"
263
+ self.platform = "Windows"
264
+ @scripting_language = new_val
265
+ @need_to_update = true
266
+ end #
267
+
268
+
269
+
270
+
271
+ ### Return an Array of Hashes showing the history of reported values for this EA on one computer.
272
+ ###
273
+ ### Each hash contains these 2 keys:
274
+ ### * :value - String, Integer, or Time, depending on @data_type
275
+ ### * :timestamp - Time
276
+ ###
277
+ ### This method requires a MySQL database connection established via JSS::DB_CNX.connect
278
+ ###
279
+ ### @see JSS::DBConnection
280
+ ###
281
+ ### @param computer[Integer,String] the id or name of the Computer.
282
+ ###
283
+ ### @return [Array<Hash{:timestamp=>Time,:value=>String,Integer,Time}>]
284
+ ###
285
+ def history(computer)
286
+ raise JSS::NoSuchItemError, "EA Not In JSS! Use #create to create this #{RSRC_OBJECT_KEY}." unless @in_jss
287
+ raise JSS::InvalidConnectionError, "Database connection required for 'history' query." unless JSS::DB_CNX.connected?
288
+
289
+ computer_id = case computer
290
+ when *JSS::Computer.all_ids
291
+ computer
292
+ when *JSS::Computer.all_names
293
+ JSS::Computer.map_all_ids_to(:name).invert[computer]
294
+ else nil
295
+ end # case
296
+
297
+ raise JSS::NoSuchItemError, "No computer found matching '#{computer}'" unless computer_id
298
+
299
+ the_query = <<-END_Q
300
+ SELECT eav.value_on_client AS value, r.date_entered_epoch AS timestamp_epoch
301
+ FROM extension_attribute_values eav JOIN reports r ON eav.report_id = r.report_id
302
+ WHERE r.computer_id = #{computer_id}
303
+ AND eav.extension_attribute_id = #{@id}
304
+ AND eav.value_on_client != ''
305
+ AND eav.value_on_client IS NOT NULL
306
+ AND eav.value_on_client != '(null)'
307
+ ORDER BY timestamp_epoch
308
+ END_Q
309
+
310
+ qrez = JSS::DB_CNX.db.query the_query
311
+ history = []
312
+
313
+ qrez.each_hash do |entry|
314
+ value = case @data_type
315
+ when 'String' then entry['value']
316
+ when 'Integer' then entry['value'].to_i
317
+ when 'Date' then JSS.parse_datetime(entry['value'])
318
+ end # case
319
+ newhash = {:value => value, :timestamp => JSS.epoch_to_time(entry['timestamp_epoch']) }
320
+ history << newhash
321
+ end # each hash
322
+
323
+ history
324
+ end # history
325
+
326
+
327
+ ### Aliases here, since YARD seems to have issues with them above
328
+ alias code script
329
+ alias code= script=
330
+
331
+ ######################
332
+ ### Private Instance Methods
333
+ #####################
334
+
335
+ private
336
+
337
+ ###
338
+ ### Return the REST XML for this pkg, with the current values,
339
+ ### for saving or updating
340
+ ###
341
+ def rest_xml
342
+
343
+ cea = rest_rexml # See parent class
344
+ cea.add_element('recon_display').text = @recon_display
345
+
346
+ if @input_type == 'script'
347
+ it = cea.elements["input_type"]
348
+ it.add_element('script').text = @script
349
+ it.add_element('platform').text = @platform
350
+ it.add_element('scripting_language').text = @scripting_language if @scripting_language
351
+ end
352
+
353
+ doc = REXML::Document.new APIConnection::XML_HEADER
354
+ doc << cea
355
+
356
+ return doc.to_s
357
+ end # rest xml
358
+
359
+ end # class ExtAttrib
360
+
361
+
362
+ end # module
@@ -0,0 +1,189 @@
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
+ ### An extension attribute as defined in the JSS
49
+ ###
50
+ ### @see JSS::ExtensionAttribute
51
+ ###
52
+ ### @see JSS::APIObject
53
+ ###
54
+ class MobileDeviceExtensionAttribute < JSS::ExtensionAttribute
55
+
56
+ #####################################
57
+ ### Mix-Ins
58
+ #####################################
59
+
60
+ #####################################
61
+ ### Class Methods
62
+ #####################################
63
+
64
+ #####################################
65
+ ### Class Constants
66
+ #####################################
67
+
68
+ ### The base for REST resources of this class
69
+ RSRC_BASE = "mobiledeviceextensionattributes"
70
+
71
+ ### the hash key used for the JSON list output of all objects in the JSS
72
+ RSRC_LIST_KEY = :mobile_device_extension_attributes
73
+
74
+ ### The hash key used for the JSON object output.
75
+ ### It's also used in various error messages
76
+ RSRC_OBJECT_KEY = :mobile_device_extension_attribute
77
+
78
+ ### these keys, as well as :id and :name, are present in valid API JSON data for this class
79
+ VALID_DATA_KEYS = [:description, :inventory_display, :recon_display]
80
+
81
+ ### these ext attribs are related to these kinds of objects
82
+ TARGET_CLASS = JSS::MobileDevice
83
+
84
+ ### A criterion that will return all members of the TARGET_CLASS
85
+ ALL_TARGETS_CRITERION = JSS::Criteriable::Criterion.new(:and_or => "and", :name => "Last Inventory Update", :search_type => "after (yyyy-mm-dd)", :value => "2003-01-01")
86
+
87
+ ######################
88
+ ### Attributes
89
+ ######################
90
+
91
+ ### @return [String] the name of the LDAP attribute to use when the @input Type is "LDAP Attribute Mapping"
92
+ attr_reader :attribute_mapping
93
+
94
+
95
+ #####################################
96
+ ### Constructor
97
+ #####################################
98
+
99
+ ###
100
+ ### See JSS::APIObject.initialize
101
+ ###
102
+ def initialize(args = {})
103
+
104
+ super args
105
+
106
+ if @init_data[:input_type]
107
+ @attribute_mapping = @init_data[:input_type][:attribute_mapping]
108
+ end
109
+ end # init
110
+
111
+
112
+ #####################################
113
+ ### Public Instance Methods
114
+ #####################################
115
+
116
+ ###
117
+ ### @see JSS::Creatable#create
118
+ ###
119
+ def create
120
+ if @input_type == 'LDAP Attribute Mapping'
121
+ raise MissingDataError, "No attribute_mapping defined for 'LDAP Attribute Mapping' input_type." unless @attribute_mapping
122
+ end
123
+ super
124
+ end
125
+
126
+
127
+ ###
128
+ ### @see JSS::ExtensionAttribute#web_display=
129
+ ###
130
+ def web_display= (new_val)
131
+ raise JSS::InvalidDataError, "web_display cannot be 'Operating System' for Mobile Device Extension Attributes." if new_val == 'Operating System'
132
+ super
133
+ end #
134
+
135
+
136
+ ###
137
+ ### @see JSS::ExtensionAttribute#input_type=
138
+ ###
139
+ def input_type= (new_val)
140
+ raise JSS::InvalidDataError, "Mobile Device Extension Attribute input_type cannot be 'script'" if new_val == 'script'
141
+
142
+ super
143
+
144
+ if @input_type == 'LDAP Attribute Mapping'
145
+ @popup_choices = nil
146
+ else
147
+ @attribute_mapping = nil
148
+ end
149
+ end #
150
+
151
+ ###
152
+ ### Set the ldap attribute to use for input_type 'LDAP Attribute Mapping'
153
+ ###
154
+ ### @param ldap_attrib[String] the attribute to use
155
+ ###
156
+ ### @return [void]
157
+ ###
158
+ def attribute_mapping= (ldap_attrib)
159
+ return nil if ldap_attrib == @attribute_mapping
160
+ @attribute_mapping = ldap_attrib
161
+ @need_to_update = true
162
+ end
163
+
164
+ ######################
165
+ ### Private Instance Methods
166
+ #####################
167
+
168
+ private
169
+
170
+ ###
171
+ ### Return the REST XML for this item, with the current values,
172
+ ### for saving or updating
173
+ ###
174
+ def rest_xml
175
+ mdea = rest_rexml
176
+ if @input_type == 'LDAP Attribute Mapping'
177
+ it = mdea.elements["input_type"]
178
+ it.add_element('attribute_mapping').text = @attribute_mapping
179
+ end
180
+
181
+ doc = REXML::Document.new APIConnection::XML_HEADER
182
+ doc << mdea
183
+
184
+ return doc.to_s
185
+ end # rest xml
186
+
187
+ end # class ExtAttrib
188
+
189
+ end # module