ruby-jss 1.6.4 → 2.0.0b1

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

@@ -1,288 +0,0 @@
-# Copyright 2020 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
-
-  # a mix-in module for Jamf::Resource subclasses.
-  #
-  # Many Jamf resources maintain an 'object history', available in the WebUI via
-  # the 'History' button at the bottom of a page. Ad-hoc history entries can
-  # be added containing textual notes, which is useful for objects that don't
-  # have a real 'notes' or 'description' field, like policies.
-  #
-  # In the Jamf Pro API, this history is usually available at a resource path
-  # ending with '/history' (see NON-STANDARD 'history' Paths below)
-  #
-  # Due to the many kinds of history available in Jamf,  like management
-  # history, application usage history, and so on, ruby-jss uses the term
-  # 'change log' to refer to a Jamf resource's 'object history', and access
-  # to the change log is provided by this module.
-  #
-  # The change log can be available in different places:
-  #
-  # - instances of a CollectionResources (e.g. individual policies)
-  #   - mix-in this module by including it, to get instance methods
-  # - CollectionResources as a whole (e.g. Inventory Preload Records)
-  #   - mix-in this module by extending it, to get class methods
-  # - SingletonResources (e.g. Client Checkin Settings )
-  #   - mix-in this module by including AND extending, to get both
-  #
-  # ##### NON-STANDARD 'history' Paths
-  # For most classes, the change log path is the #rsrc_path with '/history'
-  # appended, and in that case it will be determined automatically.
-  # If the object has some other path for the change log, e.g.
-  # InventoryPreloadRecord, the class can define a constant CHANGE_LOG_RSRC
-  # with the non-standard path. If that constant is defined, it will be used.
-  #
-  #
-  # This module will add these public methods:
-  #
-  #   1) #change_log, will fetch an Array of readonly
-  #     Jamf::ChangeLogEntry instances. possibly sorted, filtered, paged,
-  #     or cached
-  #
-  #   2) #next_page_of_change_log, will retrieve the next page of a paged
-  #      #change_log call
-  #
-  #   3) #add_change_log_note(note), which takes a string and adds it to the
-  #     object's change history as a note and clears the cached the logs.
-  #
-  module ChangeLog
-
-    # Add a note to this resource's change log.
-    #
-    # If the change history has been cached already, the cache is
-    # flushed after adding the note.
-    #
-    # @param note[String] The note to add. It cannot be empty.
-    #
-    # @return [void]
-    #
-    def add_change_log_note(note, cnx: Jamf.cnx)
-      # this should only be true for instances of CollectionResources
-      cnx = @cnx if @cnx
-
-      note = Jamf::Validate.non_empty_string note
-      note_to_send = { note: note }
-      cnx.post change_log_rsrc, note_to_send
-
-      # flush the cached data, force reload when next accessed, to get new note
-      @change_log = nil
-    end
-
-    # The change and note history for this resource.
-    # This is a collection of objects as a sub-resource of some
-    # primary resource. As such, retriving the change log returns
-    # an array of objects, and can be paged, sorted and filtered.
-    #
-    # This method is very similar to CollectionResource.all, see the
-    # docs for that method for more details
-    #
-    # @param sort [String, Array<String>] Server-side sorting criteria in the format:
-    #   property:direction, where direction is 'asc' or 'desc'. Multiple
-    #   properties are supported, either as separate strings in an Array, or
-    #   a single string, comma separated.
-    #
-    # @param filter [String] An RSQL filter string. Not all change_log resources
-    #   currently support filters, and if they don't, this will be ignored.
-    #
-    # @param paged [Boolean] Defaults to false. Returns only the first page of
-    #   `page_size` log entries. Use {.next_page_of_change_log} to retrieve each
-    # successive page.
-    #
-    # @param page_size [Integer] How many log entries are returned per page?
-    #   Minimum is 1, maximum is 2000, default is 100. Ignored unless paged: is
-    #   truthy.
-    #   Note: the final page may contain fewer entries than the page_size
-    #
-    # @param refresh [Boolean] re-fetch and re-cache the full list of all entries.
-    #   Ignored if paged:, page_size:, sort:, or filter: are used.
-    #
-    # @param cnx [Jamf::Connection] The API connection to use, default: Jamf.cnx.
-    #   If this is an instance of a Collection Resource, this is always
-    #   the connection from which it was fetched.
-    #
-    # @return [Array<Jamf::ChangeLogEntry>] The change log entries requested
-    #
-    def change_log(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, cnx: Jamf.cnx)
-      # this should only be true for instances of CollectionResources
-      cnx = @cnx if @cnx
-
-      # use the cache if not paging, filtering or sorting
-      return cached_change_log(refresh, cnx) if !paged && !sort && !filter
-
-      sort = parse_change_log_sort(sort)
-
-      filter &&= "&filter=#{CGI.escape filter.to_s}"
-
-      return first_change_log_page(page_size, sort, filter, cnx) if paged
-
-      fetch_all_change_log_entries(sort, filter, cnx)
-    end
-
-    # Fetch the next page of a paged #change_log request
-    # Returns an empty array if there's been no paged request
-    # or if the last one has no more pages.
-    #
-    # @return [Array<Jamf::ChangeHistoryEntry>] The next page of the change
-    #   and note history for this resource
-    #
-    def next_page_of_change_log
-      case @change_log_page
-      when :first
-        @change_log_page = 0
-      when Integer
-        @change_log_page += 1
-      else
-        # if here, we haven't initiated a paged request, or
-        # all pages have already been delivered
-        return []
-      end
-
-      raw = @change_log_paged_cnx.get "#{change_log_rsrc}?page=#{@change_log_page}&page-size=#{@change_log_page_size}#{@change_log_sort}#{@change_log_filter}"
-
-      @change_log_paged_fetched_count += raw[:results].size
-      @change_log_paged_total_count = raw[:totalCount]
-
-      # did we get the last of them in the this page?
-      # if so, clear all the paging data
-      clear_change_log_paging_data if @change_log_paged_fetched_count >= @change_log_paged_total_count
-
-      # return the page results
-      raw[:results].map { |le| Jamf::ChangeLogEntry.new le }
-    end
-
-    # how many change log entries are there?
-    # needed when using paged #change_log calls
-    #
-    # @param cnx [Jamf::Connection] The API connection to use, default: Jamf.cnx
-    #   This is ignored for instances of Collection Resources, which always use
-    #   the same connection from which they were fetched.
-    #
-    # @return [Integer] How many changelog entries exist?
-    #
-    def change_log_count(cnx: Jamf.cnx)
-      cnx = @cnx if @cnx
-      cnx.get("#{change_log_rsrc}?page=0&page-size=1")[:totalCount]
-    end
-
-    # Private methods
-    ###########################
-
-    private
-
-    # @return [String] The rest resource to get change logs for this object
-    #
-    def change_log_rsrc
-      @change_log_rsrc ||= defined?(self::CHANGE_LOG_RSRC) ? self::CHANGE_LOG_RSRC : "#{rsrc_path}/history"
-    end
-
-    def parse_change_log_sort(sort)
-      case sort
-      when nil
-        sort
-      when String
-        "&sort=#{CGI.escape sort}"
-      when Array
-        "&sort=#{CGI.escape sort.join(',')}"
-      else
-        raise ArgumentError, 'sort criteria must be a String or Array of Strings'
-      end
-    end
-
-    # get the first page of a paged change log request, and set up for
-    # getting later pages
-    #
-    # @param page_size [Integer] how many items per page
-    #
-    # @param sort [String,Array<String>] server-side sorting parameters
-    #
-    # @param filter [String] RSQL String limiting the result set
-    #
-    # @param cnx [Jamf::Connection] The API connection to use
-    #
-    # @return [Array<Object>] The first page of the change logs for this resource
-    #
-    def first_change_log_page(page_size, sort, filter, cnx)
-      page_size ||= Jamf::Pageable::DFT_PAGE_SIZE
-      raise ArgumentError, "page_size must be an Integer from #{MIN_PAGE_SIZE} to #{MAX_PAGE_SIZE}" unless Jamf::Pageable::PAGE_SIZE_RANGE.include? page_size
-
-      # set all these values then call for the next page
-      @change_log_paged_cnx = cnx
-      @change_log_page = :first
-      @change_log_page_size = page_size
-      @change_log_sort = sort
-      @change_log_filter = filter
-      @change_log_paged_fetched_count = 0
-      next_page_of_change_log
-    end
-
-    def clear_change_log_paging_data
-      @change_log_paged_cnx = nil
-      @change_log_page = nil
-      @change_log_page_size = nil
-      @change_log_sort = nil
-      @change_log_filter = nil
-      @change_log_paged_total_count = nil
-      @change_log_paged_fetched_count = nil
-    end
-
-    # return the cached/cachable version of .change_log
-    #
-    # @param refresh [Boolean] refetch the cache from the server?
-    #
-    # @param cnx [Jamf::Connection] The Connection to use
-    #
-    # @return [Array<Jamf::ChangeLogEntry>] All the change_log entries
-    #
-    def cached_change_log(refresh, cnx)
-      @change_log = nil if refresh
-      return @change_log if @change_log
-
-      sort = nil
-      filter = nil
-      @change_log = fetch_all_change_log_entries(sort, filter, cnx)
-    end
-
-    def fetch_all_change_log_entries(sort, filter, cnx)
-      cnx = @cnx if @cnx
-      paged_rsrc = "#{change_log_rsrc}?page-size=#{Jamf::Pageable::MAX_PAGE_SIZE}#{sort}#{filter}"
-      page = 0
-
-      raw = cnx.get "#{paged_rsrc}&page=#{page}"
-      results = raw[:results]
-
-      until results.size >= raw[:totalCount]
-        page += 1
-        raw = cnx.get "#{paged_rsrc}&page=#{page}"
-        results += raw[:results]
-      end
-      results.map { |le| Jamf::ChangeLogEntry.new le }
-    end
-
-
-  end # module ChangeLog
-
-end # module

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

@@ -1,75 +0,0 @@
-# Copyright 2020 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
-
-  #
-  module Extendable
-
-    # The Array of extensionAttributes converted to a Hash of
-    # 'Name' => value
-    def ext_attrs
-      extensionAttributes.map { |ea| [ea.name, ea.value] }.to_h.freeze
-    end
-
-    def ext_attr_names
-      extensionAttributes.map(&:name).freeze
-    end
-
-    def set_ext_attr(ea_name, new_val)
-      raise Jamf::NoSuchItemError, "No ext attr named '#{ea_name}'" unless ext_attr_names.include? ea_name
-      eattr = extensionAttributes.select { |ea| ea.name == ea_name }.first
-      eattr.send :new_value=, new_val
-    end
-
-    def ext_attrs_to_update
-      extensionAttributes.select(&:unsaved_changes?)
-    end
-
-    def ext_attrs_unsaved_changes
-      ext_attrs_to_update.map do |ea|
-        [ea.name,
-         {
-           old: ea.unsaved_changes[:value][:old],
-           new: ea.unsaved_changes[:value][:new]
-         }]
-      end.to_h
-    end
-
-    def ext_attrs_unsaved_changes?
-      !ext_attrs_to_update.empty?
-    end
-
-    def ext_attrs_clear_unsaved_changes
-      ext_attrs_to_update.each(&:clear_unsaved_changes)
-    end
-
-    def ext_attrs_to_jamf
-      ext_attrs_to_update.map(&:to_jamf)
-    end
-
-  end # extendable
-
-end # module

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

@@ -1,208 +0,0 @@
-# Copyright 2020 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
-
-  # methods for dealing with paged collection GET requests
-  #
-  module Pageable
-
-    # # When This is included
-    # def self.included(klass)
-    #   puts "Pageable was included by #{klass}"
-    # end
-    #
-    # # When this is exdended
-    # def self.extended(klass)
-    #   puts "Pageable was extended by #{klass}"
-    # end
-
-    DFT_PAGE_SIZE = 100
-
-    MIN_PAGE_SIZE = 1
-
-    MAX_PAGE_SIZE = 2000
-
-    PAGE_SIZE_RANGE = (MIN_PAGE_SIZE..MAX_PAGE_SIZE).freeze
-
-    # @param rsrc [String] The collection resource GET endpoint
-    #
-    # @param cnx [Jamf::Connection] The API connection to use
-    #
-    # @return [Integer] How many items exist in this collection?
-    #
-    def collection_count(rsrc, cnx: Jamf.cnx)
-      # this should only be true for instances of CollectionResources
-      cnx = @cnx if @cnx
-      cnx.get("#{rsrc}?page=0&page-size=1")[:totalCount]
-    end
-
-    # Get a specific page of a paged collection request,
-    # possibly sorted & filtered.
-    #
-    # @param rsrc [String] The collection resource GET endpoint
-    #
-    # @param page [Integer] which page to get
-    #
-    # @param page_size [Integer] how many items per page
-    #
-    # @param sort [String,Array<String>] server-side sorting parameters
-    #
-    # @param filter [String] RSQL String limiting the result set
-    #
-    # @param cnx [Jamf::Connection] The API connection to use
-    #
-    # @return [Array<Object>] The parsed JSON for the requested page
-    #
-    def fetch_collection_page(rsrc, page, page_size, sort, filter, cnx: Jamf.cnx)
-      page_size ||= DFT_PAGE_SIZE
-      validate_page_params page_size, page
-      raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
-
-      raw[:results]
-    end
-
-    ################### Private methods
-    private
-
-    # get the first page of a paged collection, and set up for
-    # getting later pages
-    #
-    # @param rsrc [String] The collection resource GET endpoint
-    #
-    # @param page_size [Integer] how many items per page
-    #
-    # @param sort [String,Array<String>] server-side sorting parameters
-    #
-    # @param filter [String] RSQL String limiting the result set
-    #
-    # @param cnx [Jamf::Connection] The API connection to use
-    #
-    # @return [Array<Object>] The first page of the collection for this resource
-    #
-    def first_collection_page(rsrc, page_size, sort, filter, cnx)
-      page_size ||= DFT_PAGE_SIZE
-      validate_page_params page_size
-
-      @collection_rsrc_path = rsrc
-      @collection_cnx = cnx
-      @collection_page = :first
-      @collection_page_size = page_size
-      @collection_sort = sort
-      @collection_filter = filter
-      @collection_paged_fetched_count = 0
-
-      next_collection_page
-    end
-
-    # Fetch the next page of a paged collection request.
-    #
-    # Returns an empty array if there's been no paged request
-    # or if the last one has no more pages.
-    #
-    # @return [Array<Object>] The next page of the collection for this resource
-    #
-    def next_collection_page
-      case @collection_page
-      when :first
-        @collection_page = 0
-      when Integer
-        @collection_page += 1
-      else
-        # if here, we haven't initiated a paged request, or
-        # all pages have already been delivered
-        return []
-      end
-
-      raw = @collection_cnx.get "#{@collection_rsrc_path}?page=#{@collection_page}&page-size=#{@collection_page_size}#{@collection_sort}#{@collection_filter}"
-
-      @collection_paged_fetched_count += raw[:results].size
-      @collection_paged_total_count = raw[:totalCount]
-
-      # did we get everything in the this page?
-      # if so, clear all the paging data
-      clear_collection_paging_data if @collection_paged_fetched_count >= @collection_paged_total_count
-
-      # return the page results
-      raw[:results]
-    end
-
-    def clear_collection_paging_data
-      @collection_rsrc_path = nil
-      @collection_cnx = nil
-      @collection_sort = nil
-      @collection_filter = nil
-      @collection_page = nil
-      @collection_page_size = nil
-      @collection_paged_total_count = nil
-      @collection_paged_fetched_count = nil
-    end
-
-    # ensure valid page && page_size
-    #
-    # @param page_size [Integer] the page_size to be validated, must be in range
-    #
-    # @param page [Integer] the page number requested, must be >= 0
-    #
-    # @return [void]
-    #
-    def validate_page_params(page_size, page = nil)
-      raise ArgumentError, "page_size must be an Integer from #{MIN_PAGE_SIZE} to #{MAX_PAGE_SIZE}" unless PAGE_SIZE_RANGE.include? page_size
-
-      # if page is nil, ignore it, one of the auto paging methods is calling us
-      return if page.nil?
-
-      raise ArgumentError, 'page must be an Integer zero or higher' unless page.is_a?(Integer) && page > -1
-    end
-
-    # Description of #fetch_all_collection_pages
-    #
-    # @param rsrc [String] The collection resource GET endpoint
-    #
-    # @param sort [String,Array<String>] server-side sorting parameters
-    #
-    # @param filter [String] RSQL String limiting the result set
-    #
-    # @param cnx [Type] describe_cnx_here
-    #
-    # @return [Type] description_of_returned_object
-    #
-    def fetch_all_collection_pages(rsrc, sort, filter, cnx)
-      page = 0
-      page_size = MAX_PAGE_SIZE
-
-      raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
-      results = raw[:results]
-
-      until results.size >= raw[:totalCount]
-        page += 1
-        raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
-        results += raw[:results]
-      end
-      results
-    end
-
-  end # Pagable
-
-end # Jamf