ruby-jss 1.3.3 → 1.6.0b1

data/lib/jamf/api/{abstract_classes → base_classes}/json_object.rb

@@ -40,7 +40,7 @@ module Jamf
   # objects (Hashes) used anywhere in the Jamf Pro API have a matching Class in
   # ruby-jss which is a subclass of Jamf::JSONObject
   #
-  # The Jamf::JSONObject class is abstract, and cannot be instantiated or used
+  # The Jamf::JSONObject class is a base class, and cannot be instantiated or used
   # directly. It merely provides the common functionality needed for dealing
   # with all JSON objects in the API.
   #
@@ -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 abstract classes:
+  # Here's the relationship between these base classes:
   #
   #                      Jamf::JSONObject
   #                         (abstract)
@@ -179,6 +179,7 @@ module Jamf
   # - enum:
   # - validator:
   # - aliases:
+  # - filter_key:
   #
   # For an example of an OBJECT_MODEL hash, see {Jamf::MobileDeviceDetails::OBJECT_MODEL}
   #
@@ -189,15 +190,27 @@ module Jamf
   # -----------------
   # This is the only required key for all attributes.
   #
-  # Symbol is one of :string, :integer, :float, or :boolean
-  # These are the JSON data types that don't need parsing into ruby
+  # ---
+  # Symbol is one of :string, :integer, :float, :boolean, or :j_id
+  #
+  # The first four are the JSON data types that don't need parsing into ruby
   # beyond that done by `JSON.parse`. When processing an attribute with one of
   # these symbols as the `class:`, the JSON value is used as-is.
   #
-  # When this is not a Symbol, it must be an actual class, such as
+  # The ':j_id' symbol means this value is an id used to reference an object in
+  # a collection resource of the API - all such objects have an 'id' attribute
+  # which is a String containing an Integer.
+  #
+  # These ids are used not only as the id attribute of the object itself, but
+  # if an object contains references to one or more other objects, those
+  # references are also ':j_id' values.
+  # In setters and .create, :j_id values can take either an integer or an
+  # integer-in-a-string, and are stored as integer-in-a-string/
+  #
+  # When 'class:' is not a Symbol, it must be an actual class, such as
   # Jamf::Timestamp or Jamf::PurchasingData.
   #
-  # Classes used this way _must_:
+  # Actual classes used this way _must_:
   #
   # - Have an #initialize method that takes two parameters and performs
   #   validation on them:
@@ -280,10 +293,11 @@ module Jamf
   # 2. so that validation can be performed on values added to the array.
   #
   #
-  # enum: \[Constant -> Array<Constants> ]
+  # enum: \[Constant -> Array ]
   # -----------------
   # This is a constant defined somewhere in the Jamf module. The constant
-  # must contain an Array of other Constant values, usually Strings.
+  # must contain an Array of values, usually Strings. You may or may not choose
+  # to define the array members as constants themselves.
   #
   # Example:
   # > Attribute `:type` has enum: Jamf::ExtentionAttribute::DATA_TYPES
@@ -305,9 +319,10 @@ module Jamf
   # >
   #
   # Setters for attributes with an enum require that the new value is
-  # a member of the array as seen above. When using such setters, its wise to
-  # use the array members themselves rather than a different but identical string,
-  # however either will work.  In other words, this:
+  # a member of the array as seen above. When using such setters, If you defined
+  # the array members as constants themselves, it is wise to use those rather
+  # than a different but identical string, however either will work.
+  # In other words, this:
   #
   #   my_ea.dataType = Jamf::ExtentionAttribute::DATA_TYPE_INTEGER
   #
@@ -356,6 +371,14 @@ module Jamf
   #
   # Attributes of class :boolean automatically have a getter alias ending with a '?'.
   #
+  # filter_key: \[Boolean]
+  # -----------------
+  # For subclasses of CollectionResource, GETting the main endpoint will return
+  # the entire collection. Some of these endpoints support RSQL filters to return
+  # only those objects that match the filter. If this attribute can be used as
+  # a field for filtering, set filter_key: to true, and filters will be used
+  # where possible to optimize GET requests.
+  #
   # Documenting your code
   # ---------------------
   # For documenting attributes with YARD, put this above each
@@ -401,22 +424,35 @@ module Jamf
   # attribute as described above. Validation failure will raise an exception,
   # usually Jamf::InvalidDataError.
   #
-  # If the attribute is defined with an enum, the value must be
-  # a key or value of the enum.
+  # Only one value-validation is applied, depending on the attribute definition:
+  #
+  # - If the attribute is defined with a specific validator, the value is passed
+  #   to that validator, and other validators are ignored
+  #
+  # - If the attribute is defined with an enum, the value must be
+  #   a value of the enum.
+  #
+  # - If the attribute is defined as a :string, :integer, :float or :bool
+  #   without an enum or validator, it is confirmed to be the correct type
+  #
+  # - If the attribute is defined to hold a :j_id, the Validate.j_id method
+  #   is used, it must be an integer or integer-in-string
+  #
+  # - If the attribute is defined to hold a JAMF class, (e.g. Jamf::Timestamp)
+  #   the class itself performs validation on the value when instantiated
+  #   with the value.
+  #
+  # - Otherwise, the value is used unchanged with no validation
   #
-  # If the attribute's class: is defined as a Class, (e.g. Jamf::Timestamp)
-  # its .new  method is called with the value and the current API connection.
-  # The class itself performs valuation when the value is used to
-  # instantiate it.
+  # Additionally:
   #
-  # If the attribute is defined with a validator, the value is passed
-  # to that validator.
+  # - If an attribute is an identifier, it must be unique in its class and
+  #   API connection.
   #
-  # If the attribute is defined as a :string, :integer, :float or :bool
-  # without an enum or validator, it is checked to be the correct type
+  # - If an attribute is required, it may not be nil or empty
   #
-  # If an attribute is an identifier, it must be unique in its class and
-  # API connection.
+  # - If an attribute is :multi, the value must be an array and each member
+  #   value is validated individually
   #
   # ### Constructor / Instantiation {#constructor}
   #
@@ -470,7 +506,7 @@ module Jamf
   #
   class JSONObject
 
-    extend Jamf::Abstract
+    extend Jamf::BaseClass
 
     # Constants
     #####################################
@@ -478,12 +514,6 @@ module Jamf
     # These classes are used from JSON in the raw
     JSON_TYPE_CLASSES = %i[string integer float boolean].freeze
 
-    # Predicate (boolean) attibutes that start with this RE will
-    # have an alias without the 'is' so :isManaged will have
-    # getters isManaged? and managed?
-    #
-    PREDICATE_RE = /^is([A-Z]\w+)$/.freeze
-
     # Public Class Methods
     #####################################
 
@@ -523,7 +553,7 @@ module Jamf
     # @return [Symbol, nil] The real object model key for the alias
     #
     def self.attr_key_for_alias(als)
-      validate_not_abstract
+      stop_if_base_class
       self::OBJECT_MODEL.each { |k, deets| return k if k == als || deets[:aliases].to_a.include?(als) }
       nil
     end
@@ -542,7 +572,9 @@ module Jamf
       need_list_methods = ancestors.include?(Jamf::CollectionResource)
 
       self::OBJECT_MODEL.each do |attr_name, attr_def|
-        create_list_methods(attr_name, attr_def) if need_list_methods && attr_def[:identifier]
+
+        # don't make one for :id, that one's hard-coded into CollectionResource
+        create_list_methods(attr_name, attr_def) if need_list_methods && attr_def[:identifier] && attr_name != :id
 
         # there can be only one (primary ident)
         if attr_def[:identifier] == :primary
@@ -591,9 +623,6 @@ module Jamf
     ##############################
     def self.define_predicates(attr_name)
       alias_method("#{attr_name}?", attr_name)
-      return unless attr_name.to_s =~ PREDICATE_RE
-
-      alias_method("#{Regexp.last_match(1).downcase}?", attr_name)
     end
 
     # create setter(s) for an attribute, and any aliases needed
@@ -610,6 +639,7 @@ module Jamf
         new_value = validate_attr attr_name, new_value
         old_value = instance_variable_get("@#{attr_name}")
         return if new_value == old_value
+
         instance_variable_set("@#{attr_name}", new_value)
         note_unsaved_change attr_name, old_value
       end # define method
@@ -638,9 +668,11 @@ module Jamf
       define_method("#{attr_name}=") do |new_value|
         instance_variable_set("@#{attr_name}", []) unless instance_variable_get("@#{attr_name}").is_a?(Array)
         raise Jamf::InvalidDataError, 'Value must be an Array' unless new_value.is_a? Array
+
         new_value.map! { |item| validate_attr attr_name, item }
         old_value = instance_variable_get("@#{attr_name}")
         return if new_value == old_value
+
         instance_variable_set("@#{attr_name}", new_value)
         note_unsaved_change attr_name, old_value
       end # define method
@@ -739,39 +771,10 @@ module Jamf
     end # create_insert_setters
     private_class_method :create_delete_if_setters
 
-    # Raise an exception if this is an abstract class
-    # Used in class methods that are defined in abstract classes.
-    # Instantiation is already prevented by the Abstract mixin
-    ##############################
-    def self.validate_not_abstract
-      raise Jamf::UnsupportedError, "Unsupported: #{self} is an abstract class, ." if Jamf::Abstract.abstract_classes.include? self
-    end
-    private_class_method :validate_not_abstract
-
     # Used by auto-generated setters and .create to validate new values.
     #
     # returns a valid value or raises an exception
     #
-    # If the attribute is defined to hold a JAMF class, (e.g. Jamf::Timestamp)
-    # the class itself performs validation on the value when instantiated
-    # with the value.
-    #
-    # If the attribute is defined with an enum, the value must be
-    # a key of the enum.
-    #
-    # If the attribute is defined with a validator, the value is passed
-    # to that validator.
-    #
-    # If the attribute is defined as a :string, :integer, :float or :bool
-    # without an enum or validator, it is confirmed to be the correct type
-    #
-    # If the attribute is required, it can't be nil or empty
-    #
-    # If the attribute is an identifier, and the class is a subclass of
-    # CollectionResource, it must be unique among the collection
-    #
-    # Otherwise, the value is returned unchanged.
-    #
     # This method only validates single values. When called from multi-value
     # setters, it is used for each value individually.
     #
@@ -783,36 +786,11 @@ module Jamf
     #
     def self.validate_attr(attr_name, value, cnx: Jamf.cnx)
       attr_def = self::OBJECT_MODEL[attr_name]
-
       raise ArgumentError, "Unknown attribute: #{attr_name} for #{self} objects" unless attr_def
 
       # validate our value, which will raise an error or
       # convert the value to the required type.
-      value =
-
-        # by enum, must be a value of the enum
-        if attr_def[:enum]
-          return value if attr_def[:enum].include? value
-          raise Jamf::InvalidDataError, "Value must be one of: :#{attr_def[:enum].join ', :'}"
-
-        # by class, the class validates the value passed with .new
-        elsif attr_def[:class].is_a? Class
-          klass = attr_def[:class]
-          # validation happens in klass.new
-          value.is_a?(klass) ? value : klass.new(value, cnx: cnx)
-
-        # by specified Validate method - pass to the method
-        elsif attr_def[:validator]
-          Jamf::Validate.send(attr_def[:validator], value)
-
-        # By json primative type - pass to the matching validate method
-        elsif JSON_TYPE_CLASSES.include? attr_def[:class]
-          Jamf::Validate.send(attr_def[:class], value)
-
-        # raw, no validation, should be rare
-        else
-          value
-        end # if
+      value = validate_attr_value(attr_def, value, cnx: Jamf.cnx)
 
       # if this is required, it can't be nil or empty
       if attr_def[:required]
@@ -826,12 +804,40 @@ module Jamf
     end # validate_attr(attr_name, value)
     private_class_method :validate_attr
 
-    # Attributes
-    #####################################
-
-    # @return [Jamf::Connection] the API connection thru which we deal with
-    #   this objcet.
-    attr_reader :cnx
+    # Validate an attribute value itself, as part of validating the attribute
+    # as a whole. Only one validation is applied, which one is
+    # determined in the order described in the #### Data Validation section
+    # of the JSONObject class comments
+    #
+    # See .validate_attr, which calls this
+    def self.validate_attr_value(attr_def, value, cnx: Jamf.cnx)
+      # by specified Validate method
+      if attr_def[:validator]
+        Jamf::Validate.send attr_def[:validator], value
+
+      # by enum, must be a value of the enum
+      elsif attr_def[:enum]
+        Jamf::Validate.in_enum(value, attr_def[:enum])
+
+      # By json primative type - pass to the matching validate method
+      elsif JSON_TYPE_CLASSES.include? attr_def[:class]
+        Jamf::Validate.send attr_def[:class], value
+
+      # a JPAPI id?
+      elsif attr_def[:class] == :j_id
+        Jamf::Validate.j_id value
+
+      # by Class, the class validates the value passed with .new
+      elsif attr_def[:class].is_a? Class
+        klass = attr_def[:class]
+        value.is_a?(klass) ? value : klass.new(value, cnx: cnx)
+
+      # raw, no validation, should be rare
+      else
+        value
+      end # if
+    end
+    private_class_method :validate_attr_value
 
     # Constructor
     #####################################
@@ -1046,6 +1052,10 @@ module Jamf
       elsif attr_def[:class].class == Class
         attr_def[:class].new api_value, cnx: @cnx
 
+      # a :j_id value. See the docs for OBJECT_MODEL in Jamf::JSONObject
+      elsif attr_def[:class] == :j_id
+        api_value.to_s
+
       # a JSON value
       else
         api_value
@@ -1058,11 +1068,9 @@ module Jamf
     # @return (see parse_single_init_value)
     #
     def parse_enum_value(api_value, attr_name, attr_def)
-      if attr_def[:enum].include? api_value
-        api_value
-      else
-        raise Jamf::InvalidDataError, "#{api_value} is not in the enum for attribute #{attr_name}"
-      end
+      raise Jamf::InvalidDataError, "#{api_value} is not in the enum for attribute #{attr_name}" unless attr_def[:enum].include? api_value
+
+      api_value
     end
 
     # call to_jamf on a single value

data/lib/jamf/api/{abstract_classes → base_classes}/prestage.rb

@@ -29,14 +29,11 @@ module Jamf
   # Classes
   #####################################
 
-  # A building defined in the JSS
+  # The parent class of ComputerPrestage, and MobileDevicePrestage
+  # holding common code.
   class Prestage < Jamf::CollectionResource
 
-    extend Jamf::Abstract
-
-    # for now, subclasses are not creatable
-    extend Jamf::UnCreatable
-
+    extend Jamf::BaseClass
     include Jamf::Lockable
 
     # Constants
@@ -49,9 +46,9 @@ module Jamf
     OBJECT_MODEL = {
 
       # @!attribute [r] id
-      #   @return [Integer]
+      #   @return [String]
       id: {
-        class: :integer,
+        class: :j_id,
         identifier: :primary,
         readonly: true
       },
@@ -66,15 +63,15 @@ module Jamf
         aliases: %i[name]
       },
 
-      # @!attribute isMandatory
+      # @!attribute mandatory
       #   @return [Boolean]
-      isMandatory: {
+      mandatory: {
         class: :boolean
       },
 
-      # @!attribute isMdmRemovable
+      # @!attribute mdmRemovable
       #   @return [Boolean]
-      isMdmRemovable: {
+      mdmRemovable: {
         class: :boolean
       },
 
@@ -96,9 +93,9 @@ module Jamf
         class: :string
       },
 
-      # @!attribute isDefaultPrestage
+      # @!attribute defaultPrestage
       #   @return [Boolean]
-      isDefaultPrestage: {
+      defaultPrestage: {
         class: :boolean,
         aliases: [:default?]
       },
@@ -106,24 +103,24 @@ module Jamf
       # @!attribute enrollmentSiteId
       #   @return [Integer]
       enrollmentSiteId: {
-        class: :integer
+        class: :j_id
       },
 
-      # @!attribute isKeepExistingSiteMembership
+      # @!attribute keepExistingSiteMembership
       #   @return [Boolean]
-      isKeepExistingSiteMembership: {
+      keepExistingSiteMembership: {
         class: :boolean
       },
 
-      # @!attribute isKeepExistingLocationInformation
+      # @!attribute keepExistingLocationInformation
       #   @return [Boolean]
-      isKeepExistingLocationInformation: {
+      keepExistingLocationInformation: {
         class: :boolean
       },
 
-      # @!attribute isRequireAuthentication
+      # @!attribute requireAuthentication
       #   @return [Boolean]
-      isRequireAuthentication: {
+      requireAuthentication: {
         class: :boolean
       },
 
@@ -133,16 +130,22 @@ module Jamf
         class: :string
       },
 
-      # @!attribute isEnableDeviceBasedActivationLock
+      # @!attribute preventActivationLock
       #   @return [Boolean]
-      isEnableDeviceBasedActivationLock: {
+      preventActivationLock: {
+        class: :boolean
+      },
+
+      # @!attribute enableDeviceBasedActivationLock
+      #   @return [Boolean]
+      enableDeviceBasedActivationLock: {
         class: :boolean
       },
 
       # @!attribute deviceEnrollmentProgramInstanceId
       #   @return [Integer]
       deviceEnrollmentProgramInstanceId: {
-        class: :integer
+        class: :j_id
       },
 
       # @!attribute locationInformation
@@ -169,19 +172,37 @@ module Jamf
       # @!attribute enrollmentCustomizationId
       #   @return [Integer]
       enrollmentCustomizationId: {
-        class: :integer
+        class: :j_id
+      },
+
+      # @!attribute language
+      #   @return [String]
+      language: {
+        class: :string
+      },
+
+      # @!attribute region
+      #   @return [String]
+      region: {
+        class: :string
+      },
+
+      # @!attribute autoAdvanceSetup
+      #   @return [Boolean]
+      autoAdvanceSetup: {
+        class: :boolean
       },
 
       # @!attribute profileUUID
       #   @return [String]
-      profileUUID: {
+      profileUuid: {
         class: :string
       },
 
       # @!attribute siteId
       #   @return [Integer]
       siteId: {
-        class: :integer
+        class: :j_id
       }
 
     }.freeze
@@ -201,10 +222,14 @@ module Jamf
     # @return [Jamf::Prestage, nil]
     #
     def self.default
-      id = all.select { |ps| ps[:isDefaultPrestage] }.first.dig :id
-      return nil unless id
+      # only one can be true at a time, so sort desc by that field,
+      # and the true one will be at the top
+      default_prestage_data = all(sort: 'defaultPrestage:desc', paged: true, page_size: 1).first
+
+      # Just in case there was no true one, make sure defaultPrestage is true
+      return unless default_prestage_data&.dig(:defaultPrestage)
 
-      fetch id: id
+      fetch id: default_prestage_data[:id]
     end
 
     # Return all scoped serial numbers and the id of the prestage