ruby-jss 1.2.4a2 → 1.2.4a3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f394d84e5b001b374b534b114addc50cf5ea911804926912c84b0a57bb1cf658
-  data.tar.gz: 5bdaecdfc2e51632b0defe59d7c91f69b9da3b72605461793251a97a0364167f
+  metadata.gz: 4ab1b92079de4a03997ab5fb60cf3463b63b7560cd45e83122ef52b563dec511
+  data.tar.gz: bedaefb57524c8d8abc820f5078d4a4db005436c71b214818e7f1ca3f2acebaf
 SHA512:
-  metadata.gz: c72272007ed1015d0647cb49ffba9701be8b19293cdad46eb04eff7a3c47d505441faf4ed95fb25de0774b4899a92c6659e4079b7c74d9893d83154f65aa619b
-  data.tar.gz: 84d17e840a8e7872222dd1ed4b0ea026a04d6a44dfeeed1f07181f8569919049120838d6aa4c2d6736a9cfbee8ccc42bc42fb8437223cbb655e1670801ac734f
+  metadata.gz: dab434c14f91b160305f25bc8284a3e8731ae6edb842e9e600b667b46f53e126fc7a62e89c3875235a156d0b4b5628d143798e539ef196143d8d963bddb9fd1c
+  data.tar.gz: b5ec8b9709cc9d9b32d4b609a39452d2e7d21b425db3fc36ba3140c5b111d7da084c1969ae27d8d96785cd2e958e5c6f803f7624b4d76fdc077149c249c423bb

data/lib/jamf.rb

@@ -95,6 +95,7 @@ module Jamf
   autoload :CollectionResource, 'jamf/api/abstract_classes/collection_resource'
 
   # Abstract Classes used for JSONObject subclasses
+  autoload :AdvancedSearch, 'jamf/api/abstract_classes/advanced_search'
   autoload :Prestage, 'jamf/api/abstract_classes/prestage'
   autoload :PrestageSkipSetupItems, 'jamf/api/abstract_classes/prestage_skip_setup_items'
 
@@ -123,6 +124,9 @@ module Jamf
   autoload :ChangeLogEntry, 'jamf/api/json_objects/change_log_entry'
   autoload :ComputerPrestageSkipSetupItems, 'jamf/api/json_objects/computer_prestage_skip_setup_items'
   autoload :Country, 'jamf/api/json_objects/country'
+  autoload :Criterion, 'jamf/api/json_objects/criterion'
+  autoload :DeviceEnrollmentDevice, 'jamf/api/json_objects/device_enrollment_device'
+  autoload :DeviceEnrollmentSyncStatus, 'jamf/api/json_objects/device_enrollment_sync_status'
   autoload :ExtensionAttributeValue, 'jamf/api/json_objects/extension_attribute_value'
   autoload :InstalledApplication, 'jamf/api/json_objects/installed_application'
   autoload :InstalledCertificate, 'jamf/api/json_objects/installed_certificate'
@@ -150,15 +154,18 @@ module Jamf
   autoload :AppStoreCountryCodes, 'jamf/api/resources/singleton_resources/app_store_country_codes'
 
   # Subclasses of CollectionResource
+  autoload :AdvancedMobileDeviceSearch, 'jamf/api/resources/collection_resources/advanced_mobile_device_search'
+  autoload :AdvancedUserSearch, 'jamf/api/resources/collection_resources/advanced_user_search'
   autoload :Attachment, 'jamf/api/resources/collection_resources/attachment'
   autoload :Building, 'jamf/api/resources/collection_resources/building'
   autoload :Computer, 'jamf/api/resources/collection_resources/computer'
   autoload :ComputerPrestage, 'jamf/api/resources/collection_resources/computer_prestage'
   autoload :Department, 'jamf/api/resources/collection_resources/department'
+  autoload :DeviceEnrollment, 'jamf/api/resources/collection_resources/device_enrollment'
   autoload :ExtensionAttribute, 'jamf/api/resources/collection_resources/extension_attribute'
   autoload :InventoryPreloadRecord, 'jamf/api/resources/collection_resources/inventory_preload_record'
   autoload :MobileDevice, 'jamf/api/resources/collection_resources/mobile_device'
-  autoload :MobileDevicePrestage, 'jamf/api/resources/collection_resources/md_prestage'
+  autoload :MobileDevicePrestage, 'jamf/api/resources/collection_resources/mobile_device_prestage'
   autoload :Site, 'jamf/api/resources/collection_resources/site'
   autoload :Script, 'jamf/api/resources/collection_resources/script'
 

data/lib/jamf/api/abstract_classes/advanced_search.rb

@@ -0,0 +1,86 @@
+# 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 building defined in the JSS
+  class AdvancedSearch < Jamf::CollectionResource
+
+    extend Jamf::Abstract
+
+    # Constants
+    #####################################
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = {
+
+      # @!attribute [r] id
+      #   @return [Integer]
+      id: {
+        class: :integer,
+        identifier: :primary,
+        readonly: true
+      },
+
+      # @!attribute name
+      #   @return [String]
+      name: {
+        class: :string,
+        identifier: true
+      },
+
+      # @!attribute criteria
+      #   @return [Array<Jamf::Criterion>]
+      criteria: {
+        class: Jamf::Criterion,
+        multi: true,
+        required: true
+      },
+
+      # @!attribute displayFields
+      #   @return [Array<String>]
+      displayFields: {
+        class: :string,
+        multi: true
+      },
+
+      # @!attribute site
+      #   @return [Jamf::Site::Reference]
+      site: {
+        class: Jamf::Site::Reference
+      }
+
+    }.freeze
+
+  end # class
+
+end # module

data/lib/jamf/api/abstract_classes/collection_resource.rb

@@ -74,13 +74,6 @@ module Jamf
       self::OBJECT_MODEL.select { |_attr, deets| deets[:identifier] }.keys
     end
 
-    # An array of attribute names that are required when
-    # making new CollectionResources
-    # See the OBJECT_MODEL documentation in {Jamf::JSONObject}
-    def self.required_attributes
-      self::OBJECT_MODEL.select { |_attr, deets| deets[:required] }.keys
-    end
-
     # The Collection members Array for this class, retrieved from
     # the RSRC_PATH as Parsed JSON, but not instantiated into instances
     # unless instantiate: is truthy.
@@ -122,7 +115,9 @@ module Jamf
       cnx.collection_cache[self].map { |m| new m }
     end
 
-    # An array of the ids for all collection members
+    # An array of the ids for all collection members. According to the
+    # specs ALL collection resources must have an ID, which is used in the
+    # resource path.
     #
     # @param refresh (see .all)
     #

data/lib/jamf/api/abstract_classes/json_object.rb

@@ -51,7 +51,7 @@ module Jamf
   # you will make a subclass of either Jamf::JSONObject, Jamf::SingletonResource
   # or Jamf::CollectionResource.
   #
-  # Here's the relationship between these MetaClasses:
+  # Here's the relationship between these abstract classes:
   #
   #                      Jamf::JSONObject
   #                         (abstract)
@@ -241,8 +241,7 @@ module Jamf
   # required: \[Boolean]
   # -----------------
   # If true, this attribute must be provided when creating a new local instance
-  # with .make, and cannot be nil or empty when sending a new instance to the
-  # API with \#create
+  # and cannot be set to nil or empty
   #
   #
   # readonly: \[Boolean]
@@ -501,6 +500,13 @@ module Jamf
       true
     end
 
+    # An array of attribute names that are required when
+    # making new instances
+    # See the OBJECT_MODEL documentation in {Jamf::JSONObject}
+    def self.required_attributes
+      self::OBJECT_MODEL.select { |_attr, deets| deets[:required] }.keys
+    end
+
     # Given a Symbol that might be an alias of a key fron OBJECT_MODEL
     # return the real key
     #
@@ -926,8 +932,8 @@ module Jamf
       data
     end
 
-    # DOESN"T SEEM TO WORK FOR BUILDINGS - need the whole JSON object
-    # not just the changes.
+    # Only works for PATCH endpoints.
+    #
     # @return [Hash] The changes that need to be sent to the API, as a Hash
     #  to be converted to JSON by the Jamf::Connection
     #

data/lib/jamf/api/abstract_classes/prestage.rb

@@ -33,6 +33,10 @@ module Jamf
   class Prestage < Jamf::CollectionResource
 
     extend Jamf::Abstract
+
+    # for now, subclasses are not creatable
+    extend Jamf::UnCreatable
+
     include Jamf::Lockable
 
     # Constants
@@ -95,7 +99,8 @@ module Jamf
       # @!attribute isDefaultPrestage
       #   @return [Boolean]
       isDefaultPrestage: {
-        class: :boolean
+        class: :boolean,
+        aliases: [:default?]
       },
 
       # @!attribute enrollmentSiteId
@@ -190,28 +195,206 @@ module Jamf
     # Class Methods
     #####################################
 
-    # Return all scoped computer serial numbers and the id of the prestage
-    # they are assigned to
+    # Return the Prestage subclass that is marked as default,
+    # i.e. the one that new SNs are assigned to when first added.
+    # Nil if no default is defined
+    # @return [Jamf::Prestage, nil]
+    #
+    def self.default
+      id = all.select { |ps| ps[:isDefaultPrestage] }.first.dig :id
+      return nil unless id
+
+      fetch id: id
+    end
+
+    # Return all scoped serial numbers and the id of the prestage
+    # they are assigned to. Data is cached, use a truthy first param to refresh.
+    #
+    # @param refresh[Boolean] re-read the list from the API?
     #
     # @param cnx[Jamf::Connection] the API connection to use
     #
     # @return [Hash {String => Integer}] The Serials and prestage IDs
     #
-    def self.serials_by_prestage_id(cnx: Jamf.cnx)
+    def self.serials_by_prestage_id(refresh = false, cnx: Jamf.cnx)
       @serials_by_prestage_rsrc ||= "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{SCOPE_RSRC}"
-      cnx.get(@serials_by_prestage_rsrc)[SERIALS_KEY].transform_keys!(&:to_s)
+      @serials_by_prestage_id = nil if refresh
+      @serials_by_prestage_id ||= cnx.get(@serials_by_prestage_rsrc)[SERIALS_KEY].transform_keys!(&:to_s)
+    end
+
+    # Get the assigned serialnumbers for a given prestage
+    #
+    # @paream prestage_ident [Integer, String] the id or name of
+    #   an existing prestage.
+    #
+    # @param refresh[Boolean] re-read the list from the API?
+    #
+    # @param cnx[Jamf::Connection] the API connection to use
+    #
+    # @return [Array<String>] the SN's assigned to the prestage
+    #
+    def self.serials_for_prestage(prestage_ident, refresh = false, cnx: Jamf.cnx)
+      id = valid_id prestage_ident, cnx: cnx
+      raise Jamf::NoSuchItemError, "No #{self} matching '#{ident}'" unless id
+
+      serials_by_prestage_id(refresh, cnx: cnx).select { |_sn, psid| id == psid }.keys
+    end
+
+    # The id of the prestage to which the given serialNumber is assigned.
+    # nil if not assigned
+    #
+    # NOTE: If a serial number isn't assigned to any prestage, it may really be
+    # unassigned or it may not exist in your DEP. At the moment there's no way
+    # via the JP-API to know the SNs in DEP that are not assigned
+    #
+    # @param sn [String] the serial number to look for
+    #
+    # @param refresh[Boolean] re-read the list from the API?
+    #
+    # @param cnx[Jamf::Connection] the API connection to use
+    #
+    # @return [Integer, nil] The id of prestage to which the SN is assigned
+    #
+    def self.assigned_prestage_id(sn, refresh = false, cnx: Jamf.cnx)
+      serials_by_prestage_id(refresh, cnx: cnx)[sn]
+    end
+
+    # Is the given serialNumber assigned to any prestage, or to the
+    # given prestage if a prestage_ident is specified?
+    #
+    # NOTE: If a serial number isn't assigned to any prestage, it may really be
+    # unassigned or it may not exist in your DEP. At the moment there's no way
+    # via the JP-API to know the SNs in DEP but not assigned
+    #
+    # @param sn [String] the serial number to look for
+    #
+    # @param refresh[Boolean] re-read the list from the API?
+    #
+    # @paream prestage_ident[Integer, String] If provided, the id or name of
+    #   an existing prestage in which to look for the sn. if omitted, all
+    #   prestages are searched.
+    #
+    # @param cnx[Jamf::Connection] the API connection to use
+    #
+    # @return [Boolean] Is the sn assigned, at all or to the given prestage?
+    #
+    def self.assigned?(sn, prestage_ident = nil, refresh: false, cnx: Jamf.cnx)
+      assigned_id = assigned_prestage_id(sn, refresh, cnx: cnx)
+      return false unless assigned_id
+
+      if prestage_ident
+        id = valid_id prestage_ident, cnx: cnx
+        raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id
+
+        return id == assigned_id
+      end
+
+      true
+    end
+
+    # We subtract the serials_by_prestage_id.keys from all known DEP SNs
+    # rather than just looking for Jamf::DeviceEnrollment.devices  with status
+    # REMOVED, because of the delay in updating the status for
+    # Jamf::DeviceEnrollment::Devices, which must come from apple.
+    #
+    # @return [Array<String>] The serial numbers of devices that are in DEP but
+    #    not assigned to any prestage
+    #
+    def self.unassigned_sns(cnx: Jamf.cnx)
+      type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
+      Jamf::DeviceEnrollment.device_sns(type: type, cnx: cnx) - serials_by_prestage_id(:refresh, cnx: cnx).keys
+    end
+
+    # @return [Array<String>] The serial numbers of devices that are not in DEP
+    #   at all
+    def self.sns_not_in_device_enrollment
+      # type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
+      nil # TODO: this, once MobileDevice is implemented
     end
 
     # Instance Methods
     #####################################
 
+    # The scope data for this prestage
+    #
+    # @param refresh[Boolean] reload fromthe API?
+    #
+    # @return [PrestageScope]
+    #
     def scope(refresh = false)
       @scope = nil if refresh
       return @scope if @scope
 
+      @scope = Jamf::PrestageScope.new @cnx.get(scope_rsrc)
+      unless @scope.versionLock == @versionLock
+        raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again"
+      end
+
+      @scope
+    end
+
+    # @return [Array<String>] the serialnumbers assigned to this prestage
+    def assigned_sns
+      scope.assignments.map(&:serialNumber)
+    end
+
+    # Is this SN assigned to this prestage?
+    #
+    # @param sn[String] the sn to look for
+    #
+    # @return [Boolean]
+    #
+    def assigned?(sn)
+      assigned_sns.include? sn
+    end
+    alias include? assigned?
+
+    # Assign
+    def assign(*sns_to_assign)
+      sns_to_assign.map!(&:to_s)
+      new_scope_sns = assigned_sns
+      new_scope_sns += sns_to_assign
+      new_scope_sns.uniq!
+      update_scope(new_scope_sns)
+    end
+    alias add assign
+
+    def unassign(*sns_to_unassign)
+      sns_to_unassign.map!(&:to_s)
+      new_scope_sns = assigned_sns
+      new_scope_sns -= sns_to_unassign
+      update_scope(new_scope_sns)
+    end
+    alias remove unassign
+
+    def save
+      super
+      # the scope needs to be refreshed, since its versionLock will need to be
+      # updated
+      @scope = nil
+    end
+
+    # Private Instance Methods
+    ############################
+    private
+
+    def scope_rsrc
       @scope_rsrc ||= "#{self.class::RSRC_VERSION}/#{self.class::RSRC_PATH}/#{@id}/#{SCOPE_RSRC}"
+    end
 
-      @scope = Jamf::PrestageScope.new @cnx.get @scope_rsrc
+    def update_scope(new_scope_sns)
+      assignment_data = {
+        serialNumbers: new_scope_sns,
+        versionLock: @scope.versionLock
+      }
+      begin
+        @scope = Jamf::PrestageScope.new @cnx.put(scope_rsrc, assignment_data)
+      rescue Jamf::Connection::APIError => e
+        raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again" if e.status == 409
+
+        raise e
+      end # begin
+      @versionLock = @scope.versionLock
     end
 
   end # class

data/lib/jamf/api/abstract_classes/resource.rb

@@ -220,7 +220,6 @@ module Jamf
     # @return [String] the resouce path for this object
     attr_reader :rsrc_path
 
-
     # Instance Methods
     #####################################
 
@@ -233,7 +232,7 @@ module Jamf
       exist? ? update_in_jamf : create_in_jamf
       clear_unsaved_changes
 
-      @id ? @id : :saved
+      @id || :saved
     end
 
     # Private Instance Methods
@@ -242,7 +241,13 @@ module Jamf
 
     # TODO: handle PATCH when it becomes a thing
     def update_in_jamf
-      @cnx.put( rsrc_path, to_jamf)
+      @cnx.put(rsrc_path, to_jamf)
+    rescue Jamf::Connection::APIError => e
+      if e.status == 409 && self.class.included_modules.include?(Jamf::Lockable)
+        raise Jamf::VersionLockError, "The #{self.class} has been modified since it was fetched. Please refetch and try again."
+      end
+
+      raise e
     end
 
   end # class APIObject