ruby-jss 1.6.4 → 2.0.0b1

data/lib/jamf/api/{mixins → jamf_pro/mixins}/filterable.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# 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
@@ -25,27 +25,34 @@
 module Jamf
 
   # process filter strings for resources with filter request parameters
+  #
+  # This should be extended into CollectionResources whose LIST_PATH is
+  # filterable
+  #
+  # Classes doing so must define the FILTER_KEYS constant, an Array of
+  # Symbols of keys from OAPI_PROPERTIES which can be used in filters.
   module Filterable
 
-    # # When this is included
-    # def self.included(klass)
-    #   puts "Filterable was included by #{klass}"
-    # end
-    #
-    # # When this is exdended
-    # def self.extended(klass)
-    #   puts "Filterable was extended by #{klass}"
-    # end
+    def self.extended(extender)
+      Jamf.load_msg "--> #{extender} is extending Jamf::Filterable"
+    end
 
-    private
+    FILTER_PARAM_PREFIX = '&filter='.freeze
 
     # generate the RSQL filter to put into the url
-    def parse_collection_filter(filter)
-      return if filter.nil?
+    # This is callable from anywhere without mixing in.
+    def self.parse_url_filter_param(filter)
+      return filter if filter.nil? || filter.start_with?(FILTER_PARAM_PREFIX)
+
+      "#{FILTER_PARAM_PREFIX}#{CGI.escape filter}"
+    end
 
-      "&filter=#{CGI.escape filter}"
+    def filter_keys
+      defined?(self::FILTER_KEYS) ? self::FILTER_KEYS : []
     end
 
+
+
   end # Filterable
 
 end # Jamf

data/lib/jamf/api/{mixins → jamf_pro/mixins}/immutable.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# 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
@@ -24,16 +24,14 @@
 
 module Jamf
 
-  # 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
+  # When extended with this mixin, OAPIObject.mutable? returns false,
+  # meaning that no setters are ever defined, #save will raise an error
   #
   module Immutable
 
-    def mutable?
-      false
+    def self.extended(extender)
+      Jamf.load_msg "--> #{extender} is extending Jamf::Immutable"
     end
-
-  end # Lockable
+  end # Immutable
 
 end # Jamf

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

@@ -0,0 +1,167 @@
+# 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
+
+  # @see_also Jamf::OAPIObject
+  #
+  module JPAPIResource
+
+    # when this module is included, also extend our Class Methods
+    def self.included(includer)
+      # TODO: only allow being directly mixed in to CollectionResource and
+      # SingletonResource modules.
+      Jamf.load_msg "--> #{includer} is including Jamf::JPAPIResource"
+      includer.extend(ClassMethods)
+    end
+
+    # Constants
+    #####################################
+
+    # which API do APIObjects come from?
+    # The classic equivalent is in Jamf::APIObject
+    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
+
+    # The resource version for previewing new features
+    RSRC_PREVIEW_VERSION = 'preview'.freeze
+
+    #  Class Methods
+    #####################################
+    module ClassMethods
+
+      ######################################
+      def self.extended(extender)
+        Jamf.load_msg "--> #{extender} is extending Jamf::JPAPIResource::ClassMethods"
+      end
+
+      # Indicate that this class comes from the Jamf Pro API.
+      # The same method exists in APIObject to indicate coming from Classic
+      def which_api
+        :jamf_pro
+      end
+
+      # Disallow direct use of ruby's .new class method for creating instances.
+      # Require use of .fetch or .create, or 'all'
+      #
+      def new(**data)
+        calling_method = caller_locations(1..1).first.label
+        unless NEW_CALLERS.include? calling_method
+          raise Jamf::UnsupportedError, 'Use .fetch, .create, or .all(instantiate:true) to instantiate Jamf::JPAPIResource objects'
+        end
+
+        super(**data)
+      end
+
+    end # module class methods
+
+    # attributes
+    #####################################
+
+    # @return [Jamf::Connection] the API connection thru which we deal with
+    #   this resource.
+    attr_reader :cnx
+
+    # @return [String] The path for fetching this thing from the JPAPI
+    #
+    #   this gets set in the constructor in the CollectionResource or
+    #   SingletonResource mixins
+    attr_reader :get_path
+
+    # @return [String] The path for updating this thing from the JPAPI
+    #
+    #   this gets set in the constructor in the CollectionResource or
+    #   SingletonResource mixins
+    #
+    #   We use 'update_path' because some items are updated via a
+    #   PUT_PATH and others via a PATCH_PATH.
+    #   When this gets set, it will contain the appropriate one.
+    attr_reader :update_path
+
+
+    # constructor
+    #####################################
+    def initialize(**data)
+      @cnx = data.delete :cnx
+      super(**data)
+    end
+
+    # Instance Methods
+    #####################################
+
+    # Remove large cached items from
+    # the instance_variables used to create
+    # pretty-print (pp) output.
+    #
+    # @return [Array] the desired instance_variables
+    #
+    def pretty_print_instance_variables
+      vars = super.sort
+      vars.delete :@cnx
+      vars
+    end
+
+    # TODO: error handling
+    def save
+      raise Jamf::UnsupportedError, "#{self.class} objects cannot be changed" unless self.class.mutable?
+
+      if exist?
+        return unless unsaved_changes?
+
+        update_in_jamf
+      else
+        create_in_jamf
+      end
+
+      clear_unsaved_changes
+
+      @id || :saved
+    end
+
+    # Private Instance Methods
+    #####################################
+    private
+
+    ##############################
+    def update_in_jamf
+      if defined? self.class::PUT_OBJECT
+        put_object = self.class::PUT_OBJECT.new(to_jamf)
+        cnx.jp_put(update_path, put_object.to_jamf)
+
+      elsif defined? self.class::PATCH_OBJECT
+        patch_object = self.class::PATCH_OBJECT.new(to_jamf)
+        cnx.jp_patch(update_path, patch_object.to_jamf)
+
+      else
+        raise Jamf::MissingDataError, "Class #{self.class} has not defined a PUT_OBJECT or PATCH_OBJECT"
+      end
+    end # update_in_jamf
+
+  end # class APIObject
+
+end # module JAMF

data/lib/jamf/api/{mixins → jamf_pro/mixins}/lockable.rb

@@ -1,4 +1,4 @@
-# Copyright 2020 Pixar
+# 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
@@ -24,6 +24,8 @@
 
 module Jamf
 
+  # TODO may not be needed anymore
+
   # Classes mixing this in have a 'versionLock' attribute and implement
   # 'Optimistic Locking'
   #  https://stackoverflow.com/questions/129329/optimistic-vs-pessimistic-locking/129397#129397
@@ -38,11 +40,31 @@ module Jamf
   #
   module Lockable
 
+    # when this module is included, also extend our Class Methods
+    def self.included(includer)
+      Jamf.load_msg "--> #{includer} is including Jamf::Lockable"
+      includer.extend(ClassMethods)
+    end
+
+    #  Class Methods
+    #####################################
+    module ClassMethods
+
+      def self.extended(extender)
+        Jamf.load_msg "--> #{extender} is extending Jamf::Lockable"
+      end
+
+      def lockable?
+        true
+      end
+
+    end # module class methods
+
     attr_reader :versionLock
 
-    def initialize(data, cnx: Jamf.cnx)
+    def initialize(**data)
       @versionLock = data[:versionLock]
-      super
+      super(**data)
     end
 
     def to_jamf
@@ -51,6 +73,10 @@ module Jamf
       data
     end
 
+    def lockable?
+      self.class.lockable?
+    end
+
   end # Lockable
 
 end # Jamf

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

@@ -0,0 +1,168 @@
+# 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.
+#
+#
+
+module Jamf
+
+  # This module should be mixed in to Jamf::Computer and Jamf::ComputerGroup
+  #
+  # It provides access to the macos-managed-software-updates JPAPI resource for 
+  # managed OS update commands to managed macs running Big Sur or higher.
+  #
+  module MacOSManagedUpdates
+
+    # when this module is included, also extend our Class Methods
+    def self.included(includer)
+      Jamf.load_msg "--> #{includer} is including Jamf::MacOSManagedUpdates"
+      includer.extend(ClassMethods)
+    end
+
+    # These resources in the Jamf Pro API can be used to send Managed macOS 
+    # updates to clients running Big Sur or higher
+    MANAGED_SW_UPDATES_RSRC = 'v1/macos-managed-software-updates'
+
+    # GETting this resource provides a list of available OS versions
+    MANAGED_SW_UPDATES_AVAILABLE_VERSIONS_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/available-updates"
+
+    # POSTing JSON data to this resource will send the MDM commands to install os updates
+    # For details about the data to send, see 
+    # https://developer.jamf.com/jamf-pro/reference/post_v1-macos-managed-software-updates-send-updates
+    MANAGED_SW_UPDATES_SEND_UPDATES_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/send-updates"
+
+    # Class Methods
+    #####################################
+    module ClassMethods
+
+      # when this module is included, also extend our Class Methods
+      def self.extended(extender)
+        Jamf.load_msg "--> #{extender} is extending Jamf::MacOSManagedUpdates::ClassMethods"
+      end
+
+      # get the list of available OS versions
+      #
+      # @return [Array<String>]
+      ###################
+      def available_os_updates(cnx: Jamf.cnx)
+        data = cnx.jp_get(MANAGED_SW_UPDATES_AVAILABLE_VERSIONS_RSRC)
+        Jamf::OAPISchemas::AvailableUpdates.new(data).availableUpdates
+      end
+
+      # Send the os update command to target Macs or a group
+      #
+      # @param updateAction [String] Required. 'DOWNLOAD_AND_INSTALL' or 'DOWNLOAD_ONLY'
+      #
+      # @param deviceIds [String, Integer, Array<String, Integer>] Identiiers for the 
+      #   computer targets. Required if no groupId is given.
+      #
+      # @param groupId [String, Integer] Identifier for the computer group target.
+      #   Requied if no deviceIDs are given.
+      #
+      # @param maxDeferrals [Integer] Allow users to defer the update the provided number 
+      #   of times before macOS forces the update. If a value is provided, the Software 
+      #   Update will use the InstallLater install action. MaxDeferral is ignored if using the 
+      #   DOWNLOAD_ONLY updateAction.
+      #
+      # @param version [String] If no value is provided, the version will default to latest
+      #   version based on device eligibility.
+      #
+      # @param skipVersionVerification [Boolean] If no value is provided, will default to false.
+      #   If true, the specified version will be forced to complete DownloadAndInstall
+      #   install action.
+      #
+      # @param applyMajorUpdate [Boolean] available only when updating to the latest version
+      #   based on device eligibility. Defaults to false. If false the calculated latest version
+      #   will only include minor version updates. If a value is provided, the calculated latest
+      #   version will include minor and major version updates.
+      #
+      # @param forceRestart [Boolean]  will default to false. Can only be true if updateAction 
+      #   is DOWNLOAD_AND_INSTALLn and the devices the command is sent to are on macOs 11 or higher. 
+      #   If true, the DownloadAndInstall action is performed, a restart will be forced. 
+      #   MaxDeferral will be ignored if true. 
+      #
+      # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx 
+      #
+      # @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse] 
+      ########################
+      def send_managed_os_update(updateAction:, deviceIds: nil, groupId: nil, maxDeferrals: nil, version: nil, skipVersionVerification: false, applyMajorUpdate: false, forceRestart: false, cnx: Jamf.cnx)
+        if self == Jamf::Computer 
+          raise ArgumentError, 'Must provide one or more deviceIds' unless deviceIds
+        elsif self == Jamf::ComputerGroup
+          raise ArgumentError, 'Must provide a groupId' unless groupId
+        else
+          raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup' 
+        end
+
+        if version
+          available_versions = available_os_updates
+          raise ArgumentError, "Invalid version, must be one of: #{available_versions.join ', '}" unless available_versions.include? version
+        end
+
+        if deviceIds
+          deviceIds = [deviceIds] unless deviceIds.is_a?(Array)
+          deviceIds.map! { |id| valid_id id }
+        end
+        groupId = valid_id groupId if groupId
+
+        data = {}
+        # ids in the JPAPI are string containing integers
+        data[:deviceIds] = deviceIds.map(&:to_s) if deviceIds
+        data[:groupId] = groupId.to_s if groupId
+
+        data[:maxDeferrals] = maxDeferrals if maxDeferrals
+        data[:version] = version if version
+        data[:skipVersionVerification] = skipVersionVerification if skipVersionVerification
+        data[:applyMajorUpdate] = applyMajorUpdate if applyMajorUpdate
+        data[:updateAction] = updateAction if updateAction
+        data[:forceRestart] = forceRestart if forceRestart  
+        
+        payload = Jamf::OAPISchemas::MacOsManagedSoftwareUpdate.new(data).to_json
+        
+        result = cnx.jp_post MANAGED_SW_UPDATES_SEND_UPDATES_RSRC, payload
+        Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse.new result
+      end
+
+    end # module ClassMethods
+
+    # Instance Methods
+    ######################################
+
+    def send_managed_os_update(updateAction:, maxDeferrals: nil, version: nil, skipVersionVerification: false, applyMajorUpdate: false, forceRestart: false, cnx: Jamf.cnx)
+      deviceIds = is_a?(Jamf::Computer) ? @id : nil
+      groupId = is_a?(Jamf::Computer) ? nil : @id
+
+      self.class.send_managed_os_update(
+        deviceIds: deviceIds, 
+        groupId: groupId, 
+        maxDeferrals: maxDeferrals, 
+        version: version, 
+        skipVersionVerification: skipVersionVerification, 
+        applyMajorUpdate: applyMajorUpdate, 
+        forceRestart: forceRestart, 
+        updateAction: updateAction, 
+        cnx: @cnx
+      )
+    end
+
+  end # module MacOSManagedUpdates
+
+end # module Jamf