ruby-jss 4.2.0b2 → 4.2.0

data/lib/jamf/api/jamf_pro/api_objects/managed_software_updates/plan.rb

@@ -0,0 +1,237 @@
+# Copyright 2025 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.
+
+# frozen_string_literal: true
+
+module Jamf
+
+  module ManagedSoftwareUpdates
+
+    # A ManagedSoftwareUpdate Plan contains the details for
+    # installing managed software updates via MDM/DDM on a device.
+    # When plans are created for a group there will be one for every member of the group
+    #
+    class Plan < Jamf::OAPISchemas::ManagedSoftwareUpdatePlan
+
+      # Mix-Ins
+      #####################################
+
+      include Jamf::CollectionResource
+      extend Jamf::Filterable
+      include Jamf::Immutable
+
+      ########### RELATED OAPI OBJECTS
+
+      # 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::ManagedSoftwareUpdatePlans
+
+      # The OAPI object class we send with a POST request to make a new member of
+      # the collection in Jamf. This is often the same as the parent class.
+      POST_OBJECT = Jamf::OAPISchemas::ManagedSoftwareUpdatePlanPost
+
+      GROUP_POST_OBJECT = Jamf::OAPISchemas::ManagedSoftwareUpdatePlanGroupPost
+
+      ############# API PATHS
+
+      # 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 = "#{MANAGED_SW_UPDATES_PATH}/plans"
+
+      # GETting this resource provides a list of existing group plans
+      # POSTing to this resource will initiate a new plan targeting a group of devices
+      GROUP_PLANS_PATH = "#{LIST_PATH}/group"
+
+      # Must define this when extending Filterable
+      FILTER_KEYS = %i[
+        planUuid device.deviceId device.objectType updateAction versionType specificVersion maxDeferrals recipeId forceInstallLocalDateTime state
+      ].freeze
+
+      GROUP_TYPES = {
+        computer: 'COMPUTER_GROUP',
+        mobile_device: 'MOBILE_DEVICE_GROUP'
+      }.freeze
+
+      # Class Methods
+      ######################################
+
+      # Get an Array of all plans for a given group, either computer or mobile device.
+      #
+      # @param group_id [Integer] the ID of the group to get plans for
+      # @param type [Symbol] the type of group, either :computer or :mobile_device
+      # @param cnx [Jamf::Connection] the connection to use, defaults to Jamf.cnx
+      # @return [Array<Jamf::ManagedSoftwareUpdates::Plan>] the plans for the group
+      ################################
+      def self.group_plans(group_id:, type:, cnx: Jamf.cnx)
+        gtype = GROUP_TYPES[type.to_sym]
+        raise ArgumentError, "Invalid group type: #{type}, must be one of :#{GROUP_TYPES.keys.join ', :'}" unless gtype
+
+        plans = Jamf.cnx.jp_get("#{GROUP_PLANS_PATH}/#{group_id}?group-type=#{gtype}")[:results]
+        plans.map do |plan_data|
+          plan_data[:cnx] = cnx
+          plan_data[:instantiate_me] = true
+          new(**plan_data)
+        end
+      end
+
+      # Get the declarations for a plan
+      #
+      # @param plan_uuid [String] the UUID of the plan to get declarations for
+      #
+      # @param cnx [Jamf::Connection] the connection to use, defaults to Jamf.cnx
+      #
+      # @return [Array<Jamf::OAPISchemas::DssDeclaration>] the declarations for the plan
+      ############################
+      def self.declarations(planUuid, cnx: Jamf.cnx)
+        cnx.jp_get("#{LIST_PATH}/#{planUuid}/declarations")[:declarations].map do |declaration|
+          Jamf::OAPISchemas::DssDeclaration.new(declaration)
+        end
+      end
+
+      # get the events for a plan
+      #
+      # BUG ? : At lease thru Jamf Pro 11.17.1, this endpoint returns a double-wrapped JSON object
+      # The first one is a Hash with one key :events, which is a String containing the JSON
+      # for the actual events - an Array of Hashes, which don't have an OAPI schema.
+      #
+      # Those Hashes look like this, but aren't consistent
+      #
+      #   {:type=>".QueueAvailableOsUpdatesCommand",
+      #   :eventSentEpoch=>1749158978751,
+      #   :managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
+      #   :processManagerUUID=>"a4b45b0a-4a46-4a52-8322-ab4f9895ab21",
+      #   :availableOSUpdateDelay=>300},
+      #
+      #   {:id=>4238,
+      #   :type=>".AvailableOsUpdateRequestCompletedEvent",
+      #   :deviceObjectId=>1,
+      #   :managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
+      #   :eventReceivedEpoch=>1749159337161,
+      #   :processManagerUUID=>"a4b45b0a-4a46-4a52-8322-ab4f9895ab21",
+      #   :availableOSUpdatesDto=>
+      #   {:deviceObjectId=>1,
+      #     :managementUUID=>"a94b11f0-c870-4006-82fe-e7afa981d61c",
+      #     :availableOsUpdates=>
+      #     [{:build=>"",
+      #       :preview=>false,
+      #       :version=>"16.4",
+      #       :critical=>false,
+      #       :productKey=>"082-41241",
+      #       :installSize=>0,
+      #       :productName=>"",
+      #       :downloadSize=>882235914,
+      #       :majorOSUpdate=>false,
+      #       :firmwareUpdate=>false,
+      #       :restartRequired=>false,
+      #       :humanReadableName=>"Command Line Tools for Xcode",
+      #       :allowsInstallLater=>true,
+      #       :appIdentifiersToClose=>[],
+      #       :configurationDataUpdate=>false},
+      #       {:build=>"",
+      #       :preview=>false,
+      #       :version=>"5299",
+      #       :critical=>false,
+      #       :productKey=>"082-54857",
+      #       :installSize=>0,
+      #       :productName=>"",
+      #       :downloadSize=>1256157,
+      #       :majorOSUpdate=>false,
+      #       :firmwareUpdate=>false,
+      #       :restartRequired=>false,
+      #       :humanReadableName=>"XProtectPlistConfigData",
+      #       :allowsInstallLater=>true,
+      #       :appIdentifiersToClose=>[],
+      #       :configurationDataUpdate=>true}],
+      #     :eventReceivedEpoch=>1749159337161
+      #     }
+      #    }
+      #
+      # note that some have id's and some don't. Some have response data (like the available OS updates)
+      # which can contain a more complex data structure.
+      #
+      # NOTE: This may be intentional, but is not documented in the JPAPI docs. The endpoint is "events"
+      # but what's returned is an 'event store'. Its possible that the data comes from Apple as JSON
+      # and Jamf is just passing it through.
+      # Awaiting clarification from Jamf on this.
+      #
+      # In any case, this method will unwrap the JSON and return the events as an Array of Hashes
+      #
+      # @param plan_uuid [String] the UUID of the plan to get events for
+      #
+      # @param cnx [Jamf::Connection] the connection to use, defaults to Jamf.cnx
+      #
+      # @return [Array<Hash>] the events for the plan
+      ############################
+      def self.event_store(planUuid, cnx: Jamf.cnx)
+        data = cnx.jp_get("#{LIST_PATH}/#{planUuid}/events")
+        if data[:events].is_a?(String) && data[:events].start_with?('{"events":')
+          JSON.parse data[:events], symbolize_names: true
+        else
+          data[:events]
+        end
+      end
+
+      # Instance Methods
+      ######################################
+
+      # get the declarations for this plan
+      #
+      # @return [Array<Jamf::OAPISchemas::DssDeclaration>] the declarations for the plan
+      ############################
+      def declarations
+        self.class.declarations(planUuid, cnx: cnx)
+      end
+
+      # get the events for this plan
+      #
+      # @return [Array<Jamf::OAPISchemas::DssDeclaration>] the events for the plan
+      ############################
+      def event_store
+        self.class.event_store(planUuid, cnx: cnx)
+      end
+
+    end # class Plan
+
+  end # module ManagedSoftwareUpdates
+
+end # module Jamf

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

@@ -0,0 +1,291 @@
+# Copyright 2025 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.
+
+# frozen_string_literal: true
+
+module Jamf
+
+  # This module provides access to the Managed Software Updates endpoints of the Jamf Pro API.
+  #
+  # Sending managed software updates is done by creating a "plan" for one or more devices, or
+  # a group of devices, either computers or mobile devices. Plans are created with the
+  # {.send_managed_sw_update} module method, which takes the target devices or group, the update action,
+  # the version type, and other optional parameters such as specific version, build version.
+  #
+  # Once created/sent, Plans, identified by their planUuid, can be retrieved with the
+  # Jamf::ManagedSoftwareUpdate::Plan class which encapsulates the details of the plan, including
+  # the latest status of the update from the Jamf Pro server.
+  #
+  # You can also retrieve the status of any computer or group from the MDM server/Client Machines via the
+  # Jamf::ManagedSoftwareUpdates.status method, which returns an array of Status objects
+  # for the devices or group members you specify.
+  #
+  # TODO: We will integrate the ManagedSoftwareUpdate::Plan class into Jamf::Computer,
+  # Jamf::MobileDevice, Jamf::ComputerGroup, and Jamf::MobileDeviceGroup (and/or their JP API versions)
+  # as both a class method and an instance method, so that you can send updates directly
+  # from those classes and instances.
+  #
+  # We will probably not add support for the "feature-toggle" endpoints, since eventually
+  # this 'feature' will be the only way to do these updates, and that such toggling is better
+  # done in the web app.
+  #
+  module ManagedSoftwareUpdates
+
+    ############# API PATHS
+
+    MANAGED_SW_UPDATES_PATH = 'v1/managed-software-updates'
+
+    AVAILABLE_VERSIONS_PATH = "#{MANAGED_SW_UPDATES_PATH}/available-updates"
+
+    DEVICE_POST_PATH = "#{MANAGED_SW_UPDATES_PATH}/plans"
+
+    GROUP_POST_PATH = "#{MANAGED_SW_UPDATES_PATH}/plans/group"
+
+    STATUS_PATH = "#{MANAGED_SW_UPDATES_PATH}/update-statuses"
+
+    COMPUTER_STATUS_PATH = "#{STATUS_PATH}/computers"
+
+    COMPUTER_GROUP_STATUS_PATH = "#{STATUS_PATH}/computer-groups"
+
+    MOBILE_DEVICE_STATUS_PATH = "#{STATUS_PATH}/mobile-devices"
+
+    MOBILE_DEVICE_GROUP_STATUS_PATH = "#{STATUS_PATH}/mobile-device-groups"
+
+    STATUS_FILTER_KEYS = %i[
+      osUpdatesStatusId device.deviceId device.objectType downloaded downloadPercentComplete productKey status deferralsRemaining maxDeferrals nextScheduledInstall created updated
+    ].freeze
+
+    DEVICE_TYPES = Jamf::OAPISchemas::PlanDevicePost::OBJECT_TYPE_OPTIONS
+
+    GROUP_TYPES = Jamf::OAPISchemas::PlanGroupPost::OBJECT_TYPE_OPTIONS
+
+    UPDATE_ACTIONS = Jamf::OAPISchemas::PlanConfigurationPost::UPDATE_ACTION_OPTIONS
+
+    VERSION_TYPES = Jamf::OAPISchemas::PlanConfigurationPost::VERSION_TYPE_OPTIONS
+
+    # Class Methods
+    ######################################
+
+    # get the list of available OS versions for macOS and/or iOS/iPadOS
+    #
+    # @param cnx [Jamf::Connection] the connection to use, defaults to Jamf.cnx
+    # @return [Hash {Symbol => Array<String>}]
+    ###################
+    def self.available_os_updates(cnx: Jamf.cnx)
+      cnx.jp_get(AVAILABLE_VERSIONS_PATH)[:availableUpdates]
+    end
+
+    # Send an MDM/DDM OS update command to one or more target devices or a group
+    #
+    # TODO: Integrate this into Jamf::Computer, Jamf::MobileDevice, Jamf::ComputerGroup,
+    # and Jamf::MobileDeviceGroup as both a class method and an instance method.
+    #
+    # @param deviceIds [String, Integer, Array<String, Integer>] Required if no groupId is given.
+    #   The Jamf ID for the device targets, may be integers or integer-strings.
+    #
+    # @param groupId [String, Integer] Requied if no deviceIds are given. The Jamf ID for
+    #   the group target, may be integer or integer-string.
+    #
+    # @param targetType [Symbol, String] Required. The type of device or group.
+    #   For devices, one of :computer, :mobile_device, :apple_tv.
+    #   For groups, one of :computer_group, :mobile_device_group.
+    #
+    # @param updateAction [Symbol, String] Required. One of :download_only, :download_install,
+    #   :download_install_allow_deferral, :download_install_restart, :download_install_schedule.
+    #
+    # @param versionType [Symbol, String] Required. One of :latest_major, :latest_minor,
+    #   :latest_any, :specific_version, :custom_version
+    #
+    # @param specificVersion [String] Optional. Indicates the specific version to update to.
+    #   Only available when the versionType is set to specific_version or custom_version
+    #
+    # @param buildVersion [String] Optional. Indicates the build version to update to.
+    #   Only available when the version type is set to custom version.
+    #
+    # @param maxDeferrals [Integer] Required when the provided updateAction is :download_install_allow_deferral.
+    #   Not applicable to all updateActions.
+    #
+    # @param forceInstallLocalDateTime [Time, Jamf::Timestamp, String] Optional. The local date and time
+    # of the device to force update by. NOTE: This operation requires Declarative Device Management and
+    # is only available for Jamf Cloud customers.
+    #
+    # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
+    #
+    # @return [Hash {String => String}] deviceId => planUuid, for all devices targeted.
+    ########################
+    def self.send_managed_sw_update(targetType:, updateAction:, versionType:, deviceIds: nil, groupId: nil, cnx: Jamf.cnx, **opts)
+      deviceIds, groupId, targetType = validate_targets(targetType: targetType, deviceIds: deviceIds, groupId: groupId)
+
+      # Ensure we have a valid update action
+      updateAction = validate_update_action(updateAction)
+
+      # Ensure we have a valid version type
+      versionType = validate_version_type(versionType)
+
+      # Build the request body, starting with the common config
+      request_body = {
+        config: {
+          updateAction: updateAction,
+          versionType: versionType
+        }
+      }
+
+      request_body[:config][:specificVersion] = opts[:specificVersion] if opts[:specificVersion]
+      request_body[:config][:buildVersion] = opts[:buildVersion] if opts[:buildVersion]
+      request_body[:config][:maxDeferrals] = opts[:maxDeferrals] if opts[:maxDeferrals]
+      if opts[:forceInstallLocalDateTime]
+        time = Time.parse opts[:forceInstallLocalDateTime] unless opts[:forceInstallLocalDateTime].is_a? Time
+        request_body[:config][:forceInstallLocalDateTime] = time.strftime('%FT%T')
+      end
+
+      # Add the target information
+      if deviceIds
+        request_body[:devices] = deviceIds.map { |id| { deviceId: id, objectType: targetType } }
+        post_path = DEVICE_POST_PATH
+      else
+        request_body[:group] = {
+          groupId: groupId,
+          objectType: targetType
+        }
+        post_path = GROUP_POST_PATH
+      end
+
+      response = cnx.jp_post(post_path, request_body)
+      parsed_response = Jamf::OAPISchemas::ManagedSoftwareUpdatePlanPostResponse.new response
+
+      result = {}
+      parsed_response.plans.each do |plan|
+        result[plan.device.deviceId] = plan.planId
+      end
+
+      result
+    end
+
+    # Retrieve one or more ManagedSoftwareUpdateStatuses objects for a device, group members,
+    # or the result of an arbitrary filter on all Status objects.
+    #
+    # TODO: Integrate this into Jamf::Computer, Jamf::MobileDevice, Jamf::ComputerGroup,
+    # and Jamf::MobileDeviceGroup as both a class method and an instance method.
+    #
+    # @param type [Symbol] Required unless using a filter. One of :computer, :mobile_device,
+    #   :mobile_device_group, :computer_group.
+    #
+    # @param id [Integer, String] Required unless using a filter. The Jamf ID of the device or group
+    #
+    # @param filter [String] Required unless providing type: and id:.  An RSQL filter string to apply
+    #   to the collection of Status objects. Available filter keys are: osUpdatesStatusId device.deviceId
+    #   device.objectType downloaded downloadPercentComplete productKey status deferralsRemaining
+    #   maxDeferrals nextScheduledInstall created updated
+    #
+    # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
+    #
+    # @return [Array<Jamf::OAPISchemas::ManagedSoftwareUpdateStatus>] The Status objects for the device
+    #    or members of the group, or the filter results.
+    #
+    ###############################
+    def self.status(type: nil, id: nil, filter: nil, cnx: Jamf.cnx)
+      raise ArgumentError, 'Must provide either type and id, or a filter' if (type || id) && filter
+      raise ArgumentError, 'Must provide both type and id if using either' if (type || id) && !(type && id)
+
+      get_path =
+        case type
+        when :computer
+          "#{COMPUTER_STATUS_PATH}/#{id}"
+        when :mobile_device
+          "#{MOBILE_DEVICE_STATUS_PATH}/#{id}"
+        when :computer_group
+          "#{COMPUTER_GROUP_STATUS_PATH}/#{id}"
+        when :mobile_device_group
+          "#{MOBILE_DEVICE_GROUP_STATUS_PATH}/#{id}"
+        else
+          unless type.nil?
+            raise ArgumentError,
+                  "Invalid type: #{type}, must be one of: #{%i[computer mobile_device computer_group mobile_device_group].join ', '}"
+          end
+          raise ArgumentError, 'filter required if not using type and id' unless filter
+
+          "#{STATUS_PATH}/?filter=#{CGI.escape filter}"
+        end
+
+      Jamf::OAPISchemas::ManagedSoftwareUpdateStatuses.new(cnx.jp_get(get_path)).results
+    end
+
+    # Validate the device or group ids and type, returen validated values.
+    #
+    # @param deviceIds [String, Integer, Array<String, Integer>] Required if no groupId is given.
+    #   Identifiers for the device targets.
+    #
+    # @param groupId [String, Integer] Requied if no deviceIds are given. Identifier for
+    #   the group target.
+    #
+    # @param type [Symbol, String] Required. The type of device or group.
+    #   For devices, one of :computer, :mobile_device, :apple_tv.
+    #   For groups, one of :computer_group, :mobile_device_group.
+    #
+    # @return [Hash] a hash with the keys :type, :deviceIds, and :groupId
+    ##########################
+    def self.validate_targets(targetType:, deviceIds: nil, groupId: nil)
+      raise ArgumentError, 'Must provide either deviceIds or groupId' if deviceIds.nil? && groupId.nil?
+      raise ArgumentError, 'Must specify either deviceIds or groupId, but not both' if deviceIds && groupId
+
+      targetType = targetType.to_s.upcase
+      if deviceIds
+        # Ensure we have a valid device type
+        raise ArgumentError, "Invalid device type: #{targetType}, mst be one of: #{DEVICE_TYPES.join ', '}" unless DEVICE_TYPES.include?(targetType)
+
+        deviceIds = [deviceIds] unless deviceIds.is_a?(Array)
+      else
+        # Ensure we have a valid group type
+        raise ArgumentError, "Invalid group type: #{targetType}, mst be one of: #{GROUP_TYPES.join ', '}" unless GROUP_TYPES.include?(targetType)
+      end
+
+      [deviceIds, groupId, targetType]
+    end
+    private_class_method :validate_targets
+
+    # Validate the update action, convert it to the format expected by the API
+    # @param updateAction [Symbol, String] the update action to validate
+    # @return [String] the update action in the format expected by the API
+    ###########################
+    def self.validate_update_action(updateAction)
+      updateAction = updateAction.to_s.upcase
+      raise ArgumentError, "Invalid updateAction: #{updateAction}, must be one of: #{UPDATE_ACTIONS.join ', '}" unless UPDATE_ACTIONS.include?(updateAction)
+
+      updateAction
+    end
+    private_class_method :validate_update_action
+
+    # Validate the version type, convert it to the format expected by the API
+    # @param versionType [Symbol, String] the version type to validate
+    # @return [String] the version type in the format expected by the API
+    #########################
+    def self.validate_version_type(versionType)
+      versionType = versionType.to_s.upcase
+      raise ArgumentError, "Invalid versionType: #{versionType}, must be one of: #{VERSION_TYPES.join ', '}" unless VERSION_TYPES.include?(versionType)
+
+      versionType
+    end
+    private_class_method :validate_version_type
+
+  end # module MacOSManagedUpdates
+
+end # module Jamf

data/lib/jamf/api/jamf_pro/base_classes/oapi_object.rb

@@ -104,6 +104,11 @@ module Jamf
         create_setters attr_name, attr_def
       end #  do |attr_name, attr_def|
 
+      if defined? self::OBJECT_NAME_ATTR
+        alias_method(:name, self::OBJECT_NAME_ATTR)
+        alias_method('name=', "#{self::OBJECT_NAME_ATTR}=")
+      end
+
       @oapi_properties_parsed = true
     end # parse_object_model
 
@@ -470,6 +475,9 @@ module Jamf
     # Comparable by the sha1 hash of our properties.
     # Subclasses or mixins may override this in ways that make
     # sense for them
+    # TODO: Using this may not make sense for most objects, esp
+    # when comparing objects instantiated from Create vs those
+    # from Fetch.
     def <=>(other)
       sha1_hash <=> other.sha1_hash
     end

data/lib/jamf/api/jamf_pro/mixins/collection_resource.rb

@@ -380,6 +380,9 @@ module Jamf
         # if we're here, we should know our ident key and value
         raise ArgumentError, 'Required parameter "identifier: value", where identifier is id:, name: etc.' unless ident && value
 
+        # if the ident is :name, and there's a constant for the name attr, use that
+        ident = self::OBJECT_NAME_ATTR if defined?(self::OBJECT_NAME_ATTR) && ident == :name
+
         return raw_data_by_id(value, cnx: cnx) if ident == :id
         return unless identifiers.include? ident
 
@@ -421,6 +424,7 @@ module Jamf
         return pager(filter: "#{identifier}==\"#{value}\"", page_size: 1, cnx: cnx).page(:first).first if filterable? && filter_keys.include?(identifier)
 
         # otherwise we have to loop thru all the objects looking for the value
+        # which can be slow if there are lots of objects.
         cmp_val = value.to_s
         all(cnx: cnx).each do |data|
           return data if data[identifier].to_s.casecmp? cmp_val
@@ -469,7 +473,16 @@ module Jamf
       #
       ######################################
       def valid_id(searchterm = nil, cnx: Jamf.cnx, **ident_and_val)
-        raw_data(searchterm, cnx: cnx, **ident_and_val)&.dig(:id)
+        data =
+          if ident_and_val.empty?
+            raw_data(searchterm, cnx: cnx)
+          else
+            ident = ident_and_val.keys.first
+            value = ident_and_val.values.first
+            raw_data(cnx: cnx, ident: ident, value: value)
+          end
+
+        data&.dig(:id)
       end
 
       # By default, Collection Resources are creatable,
@@ -585,28 +598,35 @@ module Jamf
 
       # Dynamically create_identifier_list_methods
       # when one is called.
+      ######################################
       def method_missing(method, *args, &block)
         if available_list_methods.key? method.to_s
           attr_name = available_list_methods[method.to_s]
           create_identifier_list_method attr_name.to_sym, method
           send method, *args
+        elsif method.to_s == 'all_names' && defined?(self::OBJECT_NAME_ATTR)
+          define_singleton_method(:all_names) do |_refresh = nil, cnx: Jamf.cnx, cached_list: nil|
+            send "all_#{self::OBJECT_NAME_ATTR}s", *args
+          end
+          send method, *args
         else
           super
         end
       end
 
       # this is needed to prevent problems with method_missing!
+      ######################################
       def respond_to_missing?(method, *)
-        available_list_methods.key?(method.to_s) || super
+        available_list_methods.key?(method.to_s) || method.to_s == 'all_names' || super
       end
 
       # @return [Hash{String: Symbol}] Method name to matching attribute name for
       #   all identifiers
+      ######################################
       def available_list_methods
         return @available_list_methods if @available_list_methods
 
         @available_list_methods = {}
-
         identifiers.each do |i|
           meth_name = i.to_s.end_with?('s') ? "all_#{i}es" : "all_#{i}s"
           @available_list_methods[meth_name] = i

data/lib/jamf/api/jamf_pro/mixins/filterable.rb

@@ -31,6 +31,8 @@ module Jamf
   #
   # Classes doing so must define the FILTER_KEYS constant, an Array of
   # Symbols of keys from OAPI_PROPERTIES which can be used in filters.
+  #
+  # TODO: Actually implement this module in CollectionResources?
   module Filterable
 
     def self.extended(extender)
@@ -41,6 +43,12 @@ module Jamf
 
     # generate the RSQL filter to put into the url
     # This is callable from anywhere without mixing in.
+    #
+    # @param filter [String, nil] the filter to apply, or nil. If the
+    #   filter starts with FILTER_PARAM_PREFIX, it is returned as-is,
+    #   assuming it is already properly escaped.
+    # @return [String] the filter to use in the URL, with FILTER_PARAM_PREFIX
+    ##############################################
     def self.parse_url_filter_param(filter)
       return filter if filter.nil? || filter.start_with?(FILTER_PARAM_PREFIX)
 

data/lib/jamf/api/jamf_pro/mixins/jpapi_resource.rb

@@ -46,7 +46,15 @@ module Jamf
     API_SOURCE = :jamf_pro
 
     # These methods are allowed to call .new
-    NEW_CALLERS = ['fetch', 'create', 'all', 'cached_all', 'block in all', 'block in cached_all'].freeze
+    NEW_CALLERS = [
+      'fetch',
+      'create',
+      'all',
+      'cached_all',
+      'block in all',
+      'block in cached_all',
+      'block in page'
+    ].freeze
 
     # The resource version for previewing new features
     RSRC_PREVIEW_VERSION = 'preview'.freeze
@@ -67,14 +75,20 @@ module Jamf
       end
 
       # Disallow direct use of ruby's .new class method for creating instances.
-      # Require use of .fetch or .create, or 'all'
+      # Require use of a method in NEW_CALLERS, or the data must include
+      # :instantiate_me
+      #
+      # WARNING: do not abuse :instantiate_me, it exists so we don't constantly
+      # have to update NEW_CALLERS
       #
       def new(**data)
         calling_method = caller_locations(1..1).first.label
-        unless NEW_CALLERS.include? calling_method
+        unless NEW_CALLERS.include? calling_method || data[:instantiate_me]
           raise Jamf::UnsupportedError, 'Use .fetch, .create, or .all(instantiate:true) to instantiate Jamf::JPAPIResource objects'
         end
 
+        data.delete :instantiate_me
+
         super(**data)
       end