ruby-jss 1.2.4a2 → 1.2.4a3

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

@@ -29,7 +29,11 @@ module Jamf
   # Classes
   #####################################
   class InventoryPreloadExtensionAttribute < Jamf::JSONObject
-    OBJECT_MODEL= {
+
+    OBJECT_MODEL = {
+
+      # TODO: validation for ea's existance and value data type, once EAs are
+      # implemented in JPAPI
 
       # @!attribute name
       #   @return [String]
@@ -47,6 +51,7 @@ module Jamf
     }.freeze
 
     parse_object_model
+
   end # class
 
 end # module

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

@@ -29,6 +29,8 @@ module Jamf
   # A 'location' for a managed object in Jamf Pro
   class PrestageAssignment < Jamf::JSONObject
 
+    extend Jamf::Immutable
+
     OBJECT_MODEL = {
 
       # @!attribute serialNumber
@@ -52,8 +54,19 @@ module Jamf
 
     parse_object_model
 
-    def assignmentTimestamp
-      @assignmentTimestamp ||= Jamf::Timestamp.new @assignmentEpoch
+    # The assignment epoch as a Jamf::Timestamp object.
+    #
+    # NOTE: I expct this will go away once Jamf conforms to its own standard
+    # of exchanging ALL timestamp data as ISO6801 strings. At that time
+    # the assignment epoch won't be a thing anymore.
+    #
+    # @return [Jamf::Timestamp]
+    #
+    attr_reader :assignmentTimestamp
+
+    def initialize(*args)
+      super
+      @assignmentTimestamp = Jamf::Timestamp.new @assignmentEpoch
     end
 
   end # class Country

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

@@ -26,9 +26,12 @@
 # The module
 module Jamf
 
-  # A 'location' for a managed object in Jamf Pro
+  # A container for an array of Jamf::PrestageAssignment
+  # objects, each of which represents a serial number assigned to the
+  # prestage that contains this scope.
   class PrestageScope < Jamf::JSONObject
 
+    extend Jamf::Immutable
     include Jamf::Lockable
 
     OBJECT_MODEL = {
@@ -49,6 +52,6 @@ module Jamf
 
     parse_object_model
 
-  end # class Country
+  end # class PrestageScope
 
 end # module

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

@@ -24,7 +24,7 @@
 
 module Jamf
 
-  # This mixin overrides JSONObject.mutable? to return false,
+  # When extended with this mixin, JSONObject.mutable? returns false,
   # meaning that no setters are ever defined, and if the
   # object is a Jamf::Resource, #save will raise an error
   #

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

@@ -33,16 +33,24 @@ module Jamf
   # from elsewhere since we fetched it, and a 409 Conflict error is raised with
   # the reason OPTIMISTIC_LOCK_FAILED.
   #
-  # If that happens, the save doesnt happen, the object is re-fetched,
+  # If that happens, the save doesnt happen, the object must be re-fetched,
   # and the user can try again.
   #
   module Lockable
 
+    attr_reader :versionLock
+
     def initialize(data, cnx: Jamf.cnx)
       @versionLock = data[:versionLock]
       super
     end
 
+    def to_jamf
+      data = super
+      data[:versionLock] = @versionLock
+      data
+    end
+
   end # Lockable
 
 end # Jamf

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

@@ -0,0 +1,52 @@
+# Copyright 2019 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 Computer Prestage
+  class AdvancedMobileDeviceSearch < Jamf::AdvancedSearch
+
+    # Constants
+    #####################################
+
+    RSRC_VERSION = 'v1'.freeze
+
+    RSRC_PATH = 'advanced-mobile-device-searches'.freeze
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = superclass::OBJECT_MODEL
+
+    parse_object_model
+
+  end # class
+
+end # module

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

@@ -0,0 +1,52 @@
+# Copyright 2019 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 Computer Prestage
+  class AdvancedUserSearch < Jamf::AdvancedSearch
+
+    # Constants
+    #####################################
+
+    RSRC_VERSION = 'v1'.freeze
+
+    RSRC_PATH = 'advanced-user-content-searches'.freeze
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = superclass::OBJECT_MODEL
+
+    parse_object_model
+
+  end # class
+
+end # module

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

@@ -70,11 +70,13 @@ module Jamf
         class: :integer,
         multi: true
       }
-
     ).freeze
 
     parse_object_model
 
+    # Class Methods
+    ###############################################
+
   end # class
 
 end # module

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

@@ -0,0 +1,292 @@
+# Copyright 2019 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 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::CollectionResource
+
+    # Mix-Ins
+    #####################################
+
+    include Jamf::ChangeLog
+
+    # Constants
+    #####################################
+
+    RSRC_VERSION = 'v1'.freeze
+
+    RSRC_PATH = 'device-enrollment'.freeze
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = {
+
+      # @!attribute id
+      #   @return [Integer]
+      id: {
+        class: :integer,
+        identifier: :primary,
+        readonly: true
+      },
+
+      # @!attribute name
+      #   @return [String]
+      name: {
+        class: :string,
+        identifier: true
+      },
+
+      # @!attribute supervisionIdentityId
+      #   @return [Integer]
+      supervisionIdentityId: {
+        class: :integer
+      },
+
+      # @!attribute siteId
+      #   @return [Integer]
+      siteId: {
+        class: :integer
+      },
+
+      # @!attribute serverName
+      #   @return [String]
+      serverName: {
+        class: :string
+      },
+
+      # @!attribute serverUuid
+      #   @return [String]
+      serverUuid: {
+        class: :string
+      },
+
+      # @!attribute adminId
+      #   @return [String]
+      adminId: {
+        class: :string
+      },
+
+      # @!attribute orgName
+      #   @return [String]
+      orgName: {
+        class: :string
+      },
+
+      # @!attribute orgEmail
+      #   @return [String]
+      orgEmail: {
+        class: :string
+      },
+
+      # @!attribute orgPhone
+      #   @return [String]
+      orgPhone: {
+        class: :string
+      },
+
+      # @!attribute orgAddress
+      #   @return [String]
+      orgAddress: {
+        class: :string
+      },
+
+      # @!attribute tokenExpirationDate
+      #   @return [Jamf::Timestamp]
+      tokenExpirationDate: {
+        class: Jamf::Timestamp
+      }
+    }.freeze
+
+    parse_object_model
+
+    DEVICES_RSRC = 'devices'.freeze
+
+    SYNC_RSRC = 'sync'.freeze
+
+    LATEST_RSRC = 'latest'.freeze
+
+    TYPES = %i[computers mobiledevices].freeze
+
+    COMPUTERS_RE = /mac/i.freeze
+
+    # Class Methods
+    #########################################
+
+    # All devices associated by Apple with a given DeviceEnrollment instance
+    # or all defined DeviceEnrollment instances
+    #
+    # @param instance_ident[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 cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices associated with
+    #   the given, or all,  instances
+    #
+    def self.devices(instance_ident = nil, type: nil, 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)
+      return devs unless type
+
+      if type == :computers
+        devs.select { |d| d.model =~ COMPUTERS_RE }
+      else
+        devs.reject { |d| d.model =~ COMPUTERS_RE }
+      end
+    end
+
+    # 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)
+    end
+
+    # See .devices
+    #
+    # @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
+    end
+
+    # See .devices
+    # Returns just those devices with the desired profileStatus, which must be
+    # an item in DeviceEnrollmentDevice::PROFILE_STATUSES
+    #
+    # @param status[String] A member of DeviceEnrollmentDevice::PROFILE_STATUSES
+    #
+    # @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)
+      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 }
+    end
+
+    #
+    def self.sync_history(instance_ident = nil, latest = false, cnx: Jamf.cnx)
+      if instance_ident
+        instance_id = valid_id instance_ident, cnx: cnx
+        raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
+
+        rsrc = "#{RSRC_VERSION}/#{RSRC_PATH}/#{SYNC_RSRC}/#{instance_id}"
+        rsrc += "/#{LATEST_RSRC}" if latest
+      else
+        rsrc = "#{RSRC_VERSION}/#{RSRC_PATH}/#{SYNC_RSRC}"
+      end
+      data = cnx.get rsrc
+
+      return Jamf::DeviceEnrollmentSyncStatus.new data if data.is_a? Hash
+
+      data.map! { |s| Jamf::DeviceEnrollmentSyncStatus.new s }
+    end
+
+    # Private Class Methods
+    ###############################################
+
+    # Private, used by the .devices class method
+    def self.fetch_devices(instance_ident, cnx)
+      if instance_ident
+        instance_id = valid_id instance_ident, cnx: cnx
+        raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
+
+        devs = devices_for_instance_id instance_id, cnx
+      else
+        devs = []
+        all_ids.each do |id|
+          devs += devices_for_instance_id id, 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)
+      data = cnx.get("#{RSRC_VERSION}/#{RSRC_PATH}/#{instance_id}/#{DEVICES_RSRC}")[:results]
+
+      data.map { |dev| Jamf::DeviceEnrollmentDevice.new dev }
+    end
+    private_class_method :devices_for_instance_id
+
+    # Instance Methods
+    #########################################
+
+    def devices(type: nil)
+      self.class.devices @id, type: type, cnx: @cnx
+    end
+
+    def device_sns(type: nil)
+      devices(type: type).map(&:serialNumber)
+    end
+
+    def include?(sn, type: nil)
+      device_sns(type: type).j_ci_include? sn
+    end
+
+    def devices_with_status(status, type: nil)
+      self.class.devices_with_status(status, @id, type: type, cnx: @cnx)
+    end
+
+    def sync_history(latest = false)
+      self.class.sync_history(@id, latest, cnx: @cnx)
+    end
+
+    def latest_sync
+      sync_history :latest
+    end
+
+  end # class
+
+end # module