ruby-jss 1.6.4 → 2.0.0b1

data/lib/jamf/api/jamf_pro/api_objects/computer_prestage.rb

@@ -0,0 +1,82 @@
+# Copyright 2022 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # A building in the Jamf Pro API
+  #
+  # The parent class is the OAPI object representing a single member of the
+  # collection, i.e. the 'GET_OBJECT' similar to the POST_OBJECT defined in the
+  # class below.
+  #
+  class ComputerPrestage < Jamf::OAPISchemas::GetComputerPrestageV2
+
+    include Jamf::CollectionResource
+    include Jamf::Prestage
+
+    ########### RELATED OAPI OBJECTS
+    # These objects should be OAPIObjects, NOT subclasses of them and
+    # not Collection or Singleton resources.
+    #
+    # TODO: See if these constants can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The OAPI object class we get back from a 'list' query to get the
+    # whole collection, or a subset of it. It contains a :results key
+    # which is an array of data for objects of the parent class.
+    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::ComputerPrestageSearchResultsV2
+
+    # The OAPI object class we send with a POST request to make a new member of
+    # the collection in Jamf. This is usually the same as the parent class.
+    POST_OBJECT = Jamf::OAPISchemas::PostComputerPrestageV2
+
+    # The OAPI object class we send with a PUT request to change an object in
+    # Jamf by specifying all its values. Most updates happen this way,
+    # and this is usually the same as the parent class
+    PUT_OBJECT = Jamf::OAPISchemas::PutComputerPrestageV2
+
+    ############# API PATHS
+    # TODO: See if these paths can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The path for GETting the list of all objects in the collection, possibly
+    # filtered, sorted, and/or paged
+    #
+    # REQUIRED for all collection resources
+    #
+    # GET_, PUT_, PATCH_, POST_, and DELETE_ paths don't need to be
+    # defined if they are the same as LIST_PATH (followed by an id if needed)
+    #
+    LIST_PATH = 'v2/computer-prestages'.freeze
+
+    # alt and non-unique idents are defined in the prestage module
+
+  end # class
+
+end # module

data/lib/jamf/api/jamf_pro/api_objects/device_enrollment.rb

@@ -0,0 +1,358 @@
+# Copyright 2022 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # A decvice enrollment defined in the Jamf Pro.
+  #
+  # This is a connection to Apple's Automated Device Enrollment Program.
+  # A single Jamf server may have many of them, and they can belong to
+  # different sites.
+  #
+  # These objects can be used to find the details of all the devices
+  # connected to them, including the device serial numbers.
+  # To see how or if those devices are assigned to prestages, see
+  # Jamf::Prestage and its subclasses ComputerPrestage and MobileDevicePrestage
+  #
+  class DeviceEnrollment < Jamf::OAPISchemas::DeviceEnrollmentInstance
+
+    include Jamf::CollectionResource
+
+    # Mix-Ins
+    #####################################
+
+    # include Jamf::ChangeLog
+
+    # Constants
+    #####################################
+
+    ########### RELATED OAPI OBJECTS
+    # These objects should be OAPIObjects, NOT subclasses of them and
+    # not Collection or Singleton resources.
+    #
+    # TODO: See if these constants can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The OAPI object class we get back from a 'list' query to get the
+    # whole collection, or a subset of it. It contains a :results key
+    # which is an array of data for objects of the parent class.
+    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::DeviceEnrollmentInstanceSearchResults
+
+    # The OAPI object class we send with a POST request to make a new member of
+    # the collection in Jamf. This is usually the same as the parent class.
+    POST_OBJECT = Jamf::OAPISchemas::DeviceEnrollmentToken
+
+    # The OAPI object class we send with a PUT request to change an object in
+    # Jamf by specifying all its values. Most updates happen this way,
+    # and this is usually the same as the parent class
+    PUT_OBJECT = Jamf::OAPISchemas::DeviceEnrollmentInstance
+
+    # The path for GETting the list of all objects in the collection, possibly
+    # filtered, sorted, and/or paged
+    # REQUIRED for all collection resources
+    #
+    # GET_PATH, POST_PATH, PUT_PATH, PATCH_PATH, and DELETE_PATH are automatically
+    # assumed from the LIST_PATH if they follow the standards:
+    # - GET_PATH = "#{LIST_PATH}/id"
+    #   - fetch an object from the collection
+    # - POST_PATH = LIST_PATH
+    #   - create a new object in the collection
+    # - PUT_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing all its values back.
+    #     Most objects use this or PATCH but not both
+    # - PATCH_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing some of its values back
+    #     Most objects use this or PUT but not both
+    # - DELETE_PATH = "#{LIST_PATH}/id"
+    #   - delete an object from the collection
+    #
+    # If those paths differ from the standards, the constants must be defined
+    # here
+    #
+    LIST_PATH = 'v1/device-enrollments'.freeze
+
+    POST_PATH = "#{LIST_PATH}/upload-token".freeze
+
+    PUB_KEY_PATH_SUFFIX = 'public-key'.freeze
+
+    DEVICES_PATH_SUFFIX = 'devices'.freeze
+
+    SYNCS_PATH_SUFFIX = 'syncs'.freeze
+
+    LATEST_PATH_SUFFIX = 'latest'.freeze
+
+    DISOWN_PATH_SUFFIX = 'disown'.freeze
+
+    TYPES = %i[computers mobiledevices].freeze
+
+    COMPUTERS_RE = /mac/i.freeze
+
+    # TODO: Find out if 'name' is enforced to be unique
+    # Identifiers not marked in the superclass's OAPI_PROPERTIES constant
+    # which usually only marks ':id'. These values are unique in the collection
+    # ALT_IDENTIFIERS = %i[name].freeze
+
+    # Values which are useful as identifiers, but are not necessarily unique
+    # in the collection - e.g. more than one computer can have the same name
+    # WARNING
+    # When more than one item in the collection has the same value for
+    # one of these fields, which one is used, returned, selected, is undefined
+    # You Have Been Warned!
+    NON_UNIQUE_IDENTIFIERS = %i[name].freeze
+
+    # Class Methods
+    #########################################
+
+    # All devices associated by Apple with a given DeviceEnrollment instance
+    # 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[Integer, String] the id or name of the
+    #   DeviceEnrollment instance for which to list the devices. If omitted,
+    #   the devices for all instances will be returned.
+    #
+    # @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::OAPISchemas::DeviceEnrollmentDevice>] The devices associated with
+    #   the given DeviceEnrollment instance, or all instances
+    #
+    def self.devices(instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      raise ArgumentError, "Type must be one of: :#{TYPES.join ', :'}" if type && !TYPES.include?(type)
+
+      devs = fetch_devices(instance, refresh, cnx)
+      return devs unless type
+
+      if type == :computers
+        devs.select { |d| d.model =~ COMPUTERS_RE }
+      else
+        devs.reject { |d| d.model =~ COMPUTERS_RE }
+      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 = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      devices(instance, 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 = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      device_sns(instance, 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 Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS
+    #
+    # @param status[String] A member of Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS
+    #
+    # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices with the desired
+    #   status, associated with the given, or all,  instances
+    #
+    def self.devices_with_status(status, instance = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      statuses = Jamf::OAPISchemas::DeviceEnrollmentDevice::PROFILE_STATUS_OPTIONS
+      raise ArgumentError, "profileStatus must be one of: '#{statuses.join "', '"}'" unless statuses.include? status
+
+      devices(instance, 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, nil] the device as known to DEP
+    #
+    def self.device(sn, instance = nil, refresh: false, cnx: Jamf.cnx)
+      sn.upcase! # SNs from apple are always uppercase
+      devs = devices(instance, refresh: refresh, cnx: cnx)
+      devs.select { |d| d.serialNumber == sn }.first
+    end
+
+    # The history of sync operations between Apple and a given DeviceEnrollment
+    # instanace, or all instances.
+    #
+    # @param instance [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 is provided.
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus] When latest = true, the latest
+    #   sync status.
+    # @return [Array<JJamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus>] The known sync statuses.
+    #
+    def self.sync_history(instance = nil, latest: false, cnx: Jamf.cnx)
+      if instance
+        instance_id = valid_id instance, cnx: cnx
+        raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance
+
+        path = "#{get_path}/#{instance_id}/#{SYNCS_PATH_SUFFIX}"
+        path += "/#{LATEST_PATH_SUFFIX}" if latest
+      else
+        path = "#{get_path}/#{SYNCS_PATH_SUFFIX}"
+        latest = false
+      end
+
+      data = cnx.jp_get path
+
+      return Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new data if latest
+
+      data.map! { |s| Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus.new s }
+    end
+
+    # disown one or more serial numbers from a given DeviceEnrollment instance
+    #
+    # @param sns[String, 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 [Hash] The SNs as keys and 'SUCESS' or 'FAILED' as values
+    #
+    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_path = "#{get_path}/#{instance_id}/#{DISOWN_PATH_SUFFIX}"
+      resp = Jamf::OAPISchemas::DeviceEnrollmentDisownResponse.new cnx.jp_post(disown_path, data)
+
+      resp.devices
+    end
+
+    # Private Class Methods
+    ###############################################
+
+    # Private, used by the .devices instance method
+    def self.fetch_devices(instance = nil, refresh, cnx)
+      if instance
+        instance_id = valid_id instance, cnx: cnx
+        raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id
+
+        devs = devices_for_instance_id instance_id, refresh, cnx
+      else
+        devs = []
+        all_ids.each do |id|
+          devs += devices_for_instance_id id, refresh, cnx
+        end
+      end
+      devs
+    end
+    private_class_method :fetch_devices
+
+    # 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 =
+        Jamf::OAPISchemas::DeviceEnrollmentDeviceSearchResults.new(
+          cnx.jp_get("#{LIST_PATH}/#{instance_id}/#{DEVICES_PATH_SUFFIX}")
+        ).results
+      @device_cache[cnx][instance_id] = data
+    end
+    private_class_method :devices_for_instance_id
+
+    # Instance Methods
+    #########################################
+
+    def devices(type: nil, refresh: false)
+      self.class.devices @id, type: type, cnx: @cnx, refresh: refresh
+    end
+
+    def device_sns(type: nil, refresh: false)
+      devices(type: type, refresh: refresh).map(&:serialNumber)
+    end
+
+    def include?(sn, type: nil, refresh: false)
+      device_sns(type: type, refresh: refresh).j_ci_include? sn
+    end
+
+    def devices_with_status(status, type: nil, refresh: false)
+      self.class.devices_with_status(status, @id, type: type, refresh: refresh, cnx: @cnx)
+    end
+
+    def sync_history(latest: false)
+      self.class.sync_history(@id, latest: latest, cnx: @cnx)
+    end
+
+    def latest_sync
+      sync_history latest: true
+    end
+
+    def disown(*sns)
+      self.class.disown sns, from_instance: @id, cnx: @cnx
+    end
+
+  end # class
+
+end # module

data/lib/jamf/api/jamf_pro/api_objects/inventory_preload_record.rb

@@ -0,0 +1,172 @@
+# Copyright 2022 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+# The Module
+module Jamf
+
+  # Classes
+  #####################################
+
+  # An Inventory Preload record for a Computer or Mobile Device in Jamf.
+  #
+  # Since the JPAPI offers access to these records via JSON as well as CSV
+  # uploads, we are implementing JSON access, to stay in line with the rest
+  # of how ruby-jss works, and keep things simple.
+  #
+  # If you want to use a CSV as your data source, you should use a ruby
+  # CSV library, such as the one built in to ruby, and loop thru your CSV
+  # records, creating or fetching instances of this class as needed,
+  # manipulating them, and saving them.
+  #
+  #
+  class InventoryPreloadRecord < Jamf::OAPISchemas::InventoryPreloadRecordV2
+
+    # Mix-Ins
+    #####################################
+    include Jamf::CollectionResource
+    extend Jamf::Filterable
+    include Jamf::ChangeLog
+
+    # extend Jamf::ChangeLog
+
+    # Constants
+    #####################################
+
+    ########### RELATED OAPI OBJECTS
+    # These objects should be OAPIObjects, NOT subclasses of them and
+    # not Collection or Singleton resources.
+    #
+    # TODO: See if these constants can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The OAPI object class we get back from a 'list' query to get the
+    # whole collection, or a subset of it. It contains a :results key
+    # which is an array of data for objects of the parent class.
+    SEARCH_RESULT_OBJECT = Jamf::OAPISchemas::InventoryPreloadRecordSearchResultsV2
+
+    # The OAPI object class we send with a POST request to make a new member of
+    # the collection in Jamf. This is usually the same as the parent class.
+    POST_OBJECT = Jamf::OAPISchemas::InventoryPreloadRecordV2
+
+    # The OAPI object class we send with a PUT request to change an object in
+    # Jamf by specifying all its values. Most updates happen this way,
+    # and this is usually the same as the parent class
+    PUT_OBJECT = Jamf::OAPISchemas::InventoryPreloadRecordV2
+
+    ############# API PATHS
+    # TODO: See if these paths can be auto-generated from the
+    # OAPI schema and baked into the parent class
+
+    # The path for GETting the list of all objects in the collection, possibly
+    # filtered, sorted, and/or paged
+    # REQUIRED for all collection resources
+    #
+    # GET_PATH, POST_PATH, PUT_PATH, PATCH_PATH, and DELETE_PATH are automatically
+    # assumed from the LIST_PATH if they follow the standards:
+    # - GET_PATH = "#{LIST_PATH}/id"
+    #   - fetch an object from the collection
+    # - POST_PATH = LIST_PATH
+    #   - create a new object in the collection
+    # - PUT_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing all its values back.
+    #     Most objects use this or PATCH but not both
+    # - PATCH_PATH = "#{LIST_PATH}/id"
+    #   - update an object passing some of its values back
+    #     Most objects use this or PUT but not both
+    # - DELETE_PATH = "#{LIST_PATH}/id"
+    #   - delete an object from the collection
+    #
+    # If those paths differ from the standards, the constants must be defined
+    # here
+    #
+    LIST_PATH = 'v2/inventory-preload/records'.freeze
+
+    # Identifiers not marked in the superclass's OAPI_PROPERTIES constant
+    # which usually only identifies ':id'
+    ALT_IDENTIFIERS = %i[serialNumber].freeze
+
+    # Must define this when extending Filterable
+    FILTER_KEYS = OAPI_PROPERTIES.keys - [:extensionAttributes]
+
+
+    DEVICE_TYPE_COMPUTER = 'Computer'.freeze
+
+    DEVICE_TYPE_MOBILE_DEV = 'Mobile Device'.freeze
+
+    DEVICE_TYPE_UNKNOWN = 'Unknown'.freeze
+
+    # InvPreload Recs have a non-standard /history path
+    def self.history_path(_id)
+      'v2/inventory-preload/history'
+    end
+
+    # @param ea_name[String] The name of the EA being set
+    #
+    # @param new_val[String, Integer, Jamf::Timestamp, Time] The value being set
+    #
+    # @return [void]
+    #
+    def set_ext_attr(ea_name, new_val)
+      remove_ext_attr(ea_name)
+      extensionAttributes_append(
+        Jamf::OAPISchemas::InventoryPreloadExtensionAttribute.new(name: ea_name, value: new_val)
+      )
+      new_val
+    end
+
+    # remove an EA totally (vs setting its value to nil)
+    def remove_ext_attr(ea_name)
+      idx = extensionAttributes.index { |ea| ea.name == ea_name }
+      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
+      OAPI_PROPERTIES.each do |attr_name, attr_def|
+        next unless attr_def[:nil_ok]
+
+        if attr_name == :extensionAttributes
+          self.extensionAttributes = []
+          next
+        end
+        send "#{attr}=", nil
+      end
+    end
+
+    # InvPreload Recs have a non-standard /history path
+    def history_path(_id)
+      raise Jamf::UnsupportedError, 'InventoryPreloadRecords do not have individual change logs. Use Jamf::InventoryPreloadRecord.change_log'
+    end
+
+  end # class
+
+end # module