ruby-jss 1.2.4a3 → 1.3.2

data/lib/jamf/api/json_objects/purchasing_data.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/mixins/abstract.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/bulk_deletable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/change_log.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -60,6 +60,8 @@ module Jamf
   #
   module ChangeLog
 
+    # TODO:  note can have a max length of 2500 characters.
+
     # The change and note history for this resource.
     #
     # The history is cached internally and only re-fetched when

data/lib/jamf/api/mixins/extendable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/mixins/immutable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/locatable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/lockable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/referable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/mixins/searchable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -161,7 +161,7 @@ module Jamf
           enum: SORT_DIRECTIONS
         }
       }.freeze
-
+      parse_object_model
     end # class Orderby
 
     class SeachParams < Jamf::JSONObject
@@ -194,7 +194,7 @@ module Jamf
         }
 
       }.freeze
-
+      parse_object_model
     end # class SearchParams
 
   end # module searchable

data/lib/jamf/api/mixins/uncreatable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/mixins/undeletable.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in

data/lib/jamf/api/resources/collection_resources/account.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/advanced_mobile_device_search.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/advanced_user_search.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/building.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/category.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/computer.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/computer_prestage.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/department.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -71,6 +71,7 @@ module Jamf
         required: true
       }
     }.freeze
+
     parse_object_model
 
 

data/lib/jamf/api/resources/collection_resources/device_enrollment.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -144,6 +144,8 @@ module Jamf
 
     LATEST_RSRC = 'latest'.freeze
 
+    DISOWN_RSRC = 'disown'.freeze
+
     TYPES = %i[computers mobiledevices].freeze
 
     COMPUTERS_RE = /mac/i.freeze
@@ -152,7 +154,12 @@ module Jamf
     #########################################
 
     # All devices associated by Apple with a given DeviceEnrollment instance
-    # or all defined DeviceEnrollment instances
+    # or all defined DeviceEnrollment instances.
+    #
+    # This data is cached the first time it is read from the API, similarly to
+    # how CollectionResources are cached. To refresh the cache, pass
+    # a truthy value to the refresh: parameter, or use the Connection's
+    # .flushcache method
     #
     # @param instance_ident[Integer, String] the id or name of the
     #   DeviceEnrollment instance for which to list the devices. If omitted,
@@ -161,17 +168,19 @@ module Jamf
     # @param type[Symbol] Either :computers or :mobiledevices, returns both if
     #  not specified.
     #
+    # @param refresh [Boolean] re-read the data from the API?
+    #
     # @param cnx[Jamf::Connection] The API connection to use
     #
     # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices associated with
-    #   the given, or all,  instances
+    #   the given DeviceEnrollment instance, or all instances
     #
-    def self.devices(instance_ident = nil, type: nil, cnx: Jamf.cnx)
+    def self.devices(instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
       if type
         raise ArgumentError, "Type must be one of: :#{TYPES.join ', :'}" unless TYPES.include? type
       end
 
-      devs = fetch_devices(instance_ident, cnx)
+      devs = fetch_devices(instance_ident, refresh, cnx)
       return devs unless type
 
       if type == :computers
@@ -181,23 +190,33 @@ module Jamf
       end
     end
 
+    # The serial numbers assigned bu Apple to one, or all of your
+    # Device Enrollment instances
+    #
     # See .devices
+    #
     # @return [Array<String>] just the serial numbers for the devices
     #
-    def self.device_sns(instance_ident = nil, type: nil, cnx: Jamf.cnx)
-      devices(instance_ident, type: type, cnx: cnx).map(&:serialNumber)
+    def self.device_sns(instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      devices(instance_ident, type: type, refresh: refresh, cnx: cnx).map(&:serialNumber)
     end
 
+    # Is the given serial number in one, or any, or your Device Enrollment
+    # instances?
+    #
     # See .devices
     #
+    # @param sn [String] the serialNumber to look for
+    #
     # @return [Boolean] is the given SN in a given DeviceEnrollment instance
     # or in DEP at all?
     #
-    def self.include?(sn, instance_ident = nil, type: nil, cnx: Jamf.cnx)
-      device_sns(instance_ident, type: type, cnx: cnx).j_ci_include? sn
+    def self.include?(sn, instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      device_sns(instance_ident, type: type, refresh: refresh, cnx: cnx).j_ci_include? sn
     end
 
     # See .devices
+    #
     # Returns just those devices with the desired profileStatus, which must be
     # an item in DeviceEnrollmentDevice::PROFILE_STATUSES
     #
@@ -206,14 +225,54 @@ module Jamf
     # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices with the desired
     #   status, associated with the given, or all,  instances
     #
-    def self.devices_with_status(status, instance_ident = nil, type: nil, cnx: Jamf.cnx)
+    def self.devices_with_status(status, instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
       unless Jamf::DeviceEnrollmentDevice::PROFILE_STATUSES.include? status
         raise ArgumentError, "profileStatus must be one of: '#{Jamf::DeviceEnrollmentDevice::PROFILE_STATUSES.join "', '"}'"
       end
 
-      devices(instance_ident, type: type, cnx: cnx).select { |d| d.profileStatus == status }
+      devices(instance_ident, type: type, refresh: refresh, cnx: cnx).select { |d| d.profileStatus == status }
     end
 
+    # Fetch a single device from any defined DeviceEnrollment instance.
+    # The instance id containing the device is available in its
+    # .deviceEnrollmentProgramInstanceId attribute.
+    #
+    # @pararm sn [String] the serial number of the device
+    #
+    # @param instance_ident [String, Integer] the name or id of the instance
+    # in which to look for the sn. All instances are searched if omitted.
+    #
+    # @param refresh [Boolean] re-read the data from the API?
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Jamf::DeviceEnrollmentDevice] the device as known to DEP
+    #
+    def self.device(sn, instance_ident = nil, refresh: false, cnx: Jamf.cnx)
+      sn.upcase! # SNs from apple are always uppercase
+      devs = devices(instance_ident, refresh: refresh, cnx: cnx)
+      dev = devs.select { |d| d.serialNumber == sn }.first
+      return dev if dev
+
+      searched = instance_ident ? "DeviceEnrollment instance #{instance_ident}" : 'any DeviceEnrollment instance'
+      raise Jamf::NoSuchItemError, "No device with serialNumber '#{sn}' in #{searched}"
+    end
+
+    # The history of sync operations between Apple and a given DeviceEnrollment
+    # instanace, or all instances.
+    #
+    # @param instance_ident[Integer, String] the id or name of the
+    #   DeviceEnrollment instance for which to get the history. If omitted,
+    #   the history for all instances will be returned.
+    #
+    # @param latest [Boolean] show only the latest sync? Only valid when an
+    #   instance_ident is provided.
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Jamf::DeviceEnrollmentSyncStatus] When latest = true, the latest
+    #   sync status.
+    # @return [Array<Jamf::DeviceEnrollmentSyncStatus>] The known sync statuses.
     #
     def self.sync_history(instance_ident = nil, latest = false, cnx: Jamf.cnx)
       if instance_ident
@@ -232,31 +291,60 @@ module Jamf
       data.map! { |s| Jamf::DeviceEnrollmentSyncStatus.new s }
     end
 
+    # disown one or more serial numbers from a given DeviceEnrollment instance
+    #
+    # @param sns[Array<String>] One or more serial numbers to disown
+    #
+    # @param from_instance [Integer, String] the id or name of the instance
+    #  from which to disown the serial numbers
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [void]
+    #
+    def self.disown(*sns, from_instance:, cnx: Jamf.cnx)
+      instance_id = valid_id from_instance, cnx: cnx
+      raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id
+
+      sns.flatten!
+      sns.map!(&:to_s)
+      data = { devices: sns }
+      disown_rsrc = "#{self.class::RSRC_VERSION}/#{self.class::RSRC_PATH}/#{instance_id}/#{DISOWN_RSRC}"
+
+      cnx.post(disown_rsrc, data)
+    end
+
     # Private Class Methods
     ###############################################
 
     # Private, used by the .devices class method
-    def self.fetch_devices(instance_ident, cnx)
+    def self.fetch_devices(instance_ident, refresh, cnx)
       if instance_ident
         instance_id = valid_id instance_ident, cnx: cnx
-        raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
+        raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
 
-        devs = devices_for_instance_id instance_id, cnx
+        devs = devices_for_instance_id instance_id, refresh, cnx
       else
         devs = []
         all_ids.each do |id|
-          devs += devices_for_instance_id id, cnx
+          devs += devices_for_instance_id id, refresh, cnx
         end
       end
       devs
     end
     private_class_method :fetch_devices
 
-    # Private, used by the .devices class method
-    def self.devices_for_instance_id(instance_id, cnx)
+    # Private, used by the .fetch_devices class method
+    def self.devices_for_instance_id(instance_id, refresh, cnx)
+      @device_cache ||= {}
+      @device_cache[cnx] ||= {}
+      @device_cache[cnx][instance_id] = nil if refresh
+      return @device_cache[cnx][instance_id] if @device_cache[cnx][instance_id]
+
       data = cnx.get("#{RSRC_VERSION}/#{RSRC_PATH}/#{instance_id}/#{DEVICES_RSRC}")[:results]
 
-      data.map { |dev| Jamf::DeviceEnrollmentDevice.new dev }
+      data.map! { |dev| Jamf::DeviceEnrollmentDevice.new dev }
+      @device_cache[cnx][instance_id] = data
     end
     private_class_method :devices_for_instance_id
 
@@ -287,6 +375,10 @@ module Jamf
       sync_history :latest
     end
 
+    def disown(*sns)
+      self.class.disown sns, from_instance: @id, cnx: @cnx
+    end
+
   end # class
 
 end # module

data/lib/jamf/api/resources/collection_resources/extension_attribute.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/inventory_preload_record.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -224,7 +224,7 @@ module Jamf
       extensionAttributes: {
         class: Jamf::InventoryPreloadExtensionAttribute,
         multi: true,
-        aliases: %i[ext_attrs eas]
+        aliases: %i[eas]
       }
 
     }.freeze
@@ -251,6 +251,13 @@ module Jamf
       extensionAttributes_delete_at idx if idx
     end
 
+    # a Hash of ea name => ea_value for all eas currently set.
+    def ext_attrs
+      eas = {}
+      extensionAttributes.each { |ea| eas[ea.name] = ea.value }
+      eas
+    end
+
     # clear all values for this record except id, serialNumber, and deviceType
     def clear
       OBJECT_MODEL.keys.each do |attr|

data/lib/jamf/api/resources/collection_resources/mobile_device.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/mobile_device_prestage.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf/api/resources/collection_resources/script.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")