ruby-jss 1.4.1 → 1.5.1

data/lib/jamf/api/json_objects/md_prestage_skip_setup_items.rb

@@ -26,7 +26,34 @@
 # The module
 module Jamf
 
-  # A 'location' for a computer prestage in Jamf Pro
+  # The 'skip Setup Items' for a mobile device prestage in Jamf Pro
+  # The ones in common with computers are in the superclass
+  # To see the ones that should be here, remove anything that's in
+  # computers's list from the device ones, thus:
+  #
+  # (Jamf::MobileDevicePrestage.all.sample[:skipSetupItems].keys - Jamf::ComputerPrestage.all.sample[:skipSetupItems].keys).sort
+  #  => [:Android,
+  # :CloudStorage,
+  # :ExpressLanguage,
+  # :HomeButtonSensitivity,
+  # :OnBoarding,
+  # :Passcode,
+  # :PreferredLanguage,
+  # :RestoreCompleted,
+  # :SIMSetup,
+  # :ScreenSaver,
+  # :SoftwareUpdate,
+  # :TVHomeScreenSync,
+  # :TVProviderSignIn,
+  # :TVRoom,
+  # :TapToSetup,
+  # :TransferData,
+  # :UpdateCompleted,
+  # :WatchMigration,
+  # :Welcome,
+  # :Zoom,
+  # :iMessageAndFaceTime]
+  #
   class MobileDevicePrestageSkipSetupItems < Jamf::PrestageSkipSetupItems
 
     OBJECT_MODEL = superclass::OBJECT_MODEL.merge(
@@ -87,6 +114,14 @@ module Jamf
         aliases: %i[preferredLanguage preferredlanguage preferred_language]
       },
 
+      # @!attribute RestoreCompleted
+      #   @return [Boolean]
+      RestoreCompleted: {
+        class: :boolean,
+        aliases: %i[restorecompleted restoreCompleted restore_completed]
+      },
+
+
       # @!attribute SIMSetup
       #   @return [Boolean]
       SIMSetup: {
@@ -136,6 +171,20 @@ module Jamf
         aliases: %i[tapToSetup taptosetup tap_to_setup]
       },
 
+      # @!attribute TransferData
+      #   @return [Boolean]
+      TransferData: {
+        class: :boolean,
+        aliases: %i[transferData transferdata transfer_data]
+      },
+
+      # @!attribute UpdateCompleted
+      #   @return [Boolean]
+      UpdateCompleted: {
+        class: :boolean,
+        aliases: %i[updateCompleted updatecompleted update_completed]
+      },
+
       # @!attribute WatchMigration
       #   @return [Boolean]
       WatchMigration: {

data/lib/jamf/api/json_objects/prestage_location.rb

@@ -36,7 +36,7 @@ module Jamf
       # @!attribute id
       #   @return [Integer]
       id: {
-        class: :integer,
+        class: :j_id,
         identifier: :primary
       },
 
@@ -79,14 +79,14 @@ module Jamf
       #   @param [integer]
       #   @return [integer]
       departmentId: {
-        class: :integer
+        class: :j_id
       },
 
       # @!attribute building
       #   @param [integer]
       #   @return [integer]
       buildingId: {
-        class: :integer
+        class: :j_id
       },
 
       # @!attribute room

data/lib/jamf/api/json_objects/prestage_purchasing_data.rb

@@ -36,28 +36,28 @@ module Jamf
       # @!attribute id
       #   @return [Integer]
       id: {
-        class: :integer,
+        class: :j_id,
         identifier: :primary
       },
 
-      # @!attribute isPurchased
+      # @!attribute purchased
       #   @param [Boolean]
       #   @return [Boolean]
-      isPurchased: {
+      purchased: {
         class: :boolean
       },
 
-      # @!attribute isLeased
+      # @!attribute leased
       #   @param [Boolean]
       #   @return [Boolean]
-      isLeased: {
+      leased: {
         class: :boolean
       },
 
-      # @!attribute appleCareID
+      # @!attribute appleCareId
       #   @param [String]
       #   @return [String]
-      appleCareID: {
+      appleCareId: {
         class: :string
       },
 

data/lib/jamf/api/json_objects/prestage_scope.rb

@@ -39,7 +39,7 @@ module Jamf
       # @!attribute prestageId
       #   @return [Integer]
       prestageId: {
-        class: :integer
+        class: :j_id
       },
 
       # @!attribute assignments

data/lib/jamf/api/{resources/collection_resources → json_objects}/time_zone.rb

@@ -23,28 +23,11 @@
 #
 #
 
-# The Module
+# The module
 module Jamf
 
-  # Classes
-  #####################################
-
-  # A building defined in the JSS
-  class TimeZone < Jamf::CollectionResource
-
-    # Mix-Ins
-    #####################################
-
-    extend Jamf::Immutable
-    extend Jamf::UnCreatable
-    extend Jamf::UnDeletable
-
-    # Constants
-    #####################################
-
-    RSRC_VERSION = 'v1'.freeze
-
-    RSRC_PATH = 'time-zones'.freeze
+  # A Time Zone known to Jamf Pro
+  class TimeZone < Jamf::JSONObject
 
     # Object Model / Attributes
     # See APIObject class documentation for details
@@ -57,6 +40,7 @@ module Jamf
       zoneId: {
         class: :string,
         identifier: :primary,
+        read_only: true,
         aliases: [:id]
       },
 
@@ -65,13 +49,15 @@ module Jamf
       displayName: {
         class: :string,
         identifier: true,
+        read_only: true,
         aliases: [:name]
       },
 
       # @!attribute [r] region
       #   @return [String]
       region: {
-        class: :string
+        class: :string,
+        read_only: true
       }
     }.freeze
     parse_object_model
@@ -83,7 +69,7 @@ module Jamf
     #
     # Note that ISO8601 accepts the formats: +/-hh:mm, +/-hhmm, or +/-hh
     #
-    # @return [Integer] The offset from UTC, as a string
+    # @return [String] The offset from UTC, as a string
     #
     def utc_offset_str
       return @utc_offset_str if @utc_offset_str
@@ -114,6 +100,6 @@ module Jamf
       othertime.getlocal utc_offset
     end
 
-  end # class
+  end # class TimeZone
 
 end # module

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

@@ -24,14 +24,35 @@
 
 module Jamf
 
-  # This mixin overrides JSONObject.mutable? to return false,
-  # meaning that no setters are ever defined, and if the
-  # object is a Jamf::Resource, #save will raise an error
+  # This mixin implements the .../delete-multiple endpoints that
+  # some collection resources have (and eventually all will??)
+  # It should be extended into classes representing those resources
   #
-  module Immutable
+  module BulkDeletable
 
-    def mutable?
-      false
+    DELETE_MULTIPLE_ENDPOINT = 'delete-multiple'.freeze
+
+    # Delete multiple objects by providing an array of their
+    #
+    # @param ids [Array<String,Integer>] The ids to delete
+    #
+    # @param cnx [Jamf::Connection] The connection to use, default: Jamf.cnx
+    #
+    # @return [Array<Jamf::Connection::APIError::ErrorInfo] Info about any ids
+    #   that failed to be deleted.
+    #
+    def bulk_delete(ids, cnx: Jamf.cnx)
+      ids = [ids] unless ids.is_a? Array
+      request_body = { ids: ids.map(&:to_s) }
+
+      begin
+        cnx.post "#{rsrc_path}/#{DELETE_MULTIPLE_ENDPOINT}", request_body
+        []
+      rescue Jamf::Connection::APIError => e
+        raise e unless e.httpStatus == 400
+
+        e.errors
+      end
     end
 
   end # Lockable

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

@@ -33,7 +33,7 @@ module Jamf
   # 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'
+  # 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
@@ -49,49 +49,32 @@ module Jamf
   # - SingletonResources (e.g. Client Checkin Settings )
   #   - mix-in this module by including AND extending, to get both
   #
-  # This module will add two methods:
+  # ##### 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.
   #
-  #   1) #change_log,  will fetch and cache an Array of readonly
-  #     Jamf::ChangeLogEntry instances. passing any truthy parameter will
-  #     cause it to re-fetch the Array from the server.
   #
-  #   2) #add_history_note(note), which takes a string and adds it to the
-  #     object's change history as a note and re-fetches & caches the history.
+  # 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
 
-    # TODO:  note can have a max length of 2500 characters.
-
-    # The change and note history for this resource.
-    #
-    # The history is cached internally and only re-fetched when
-    # a truthy parameter is given.
-    #
-    # @param refresh[Boolean] re-fetch and re-cache the history
-    #
-    # @return [Array<Jamf::ChangeHistoryEntry>] The change and note history for
-    #   this resource
-    #
-    def change_log(refresh = false, cnx: Jamf.cnx)
-      # this should only be true for instances of CollectionResources
-      cnx = @cnx if @cnx
-
-      @change_log = nil if refresh
-      @change_log ||= cnx.get(change_log_rsrc)[:results].map! do |l|
-        #
-        # TODO: Report bug in jamf data, sometimes there's no details in the JSON
-        # so add an empty string if needed. DO it for note too, just in case
-        l[:details] ||= Jamf::BLANK
-        l[:note] ||= Jamf::BLANK
-
-        Jamf::ChangeLogEntry.new l
-      end # map!
-    end
-
     # Add a note to this resource's change log.
     #
-    # If the change history has been cached already, it is
-    # recached after adding the note.
+    # 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.
     #
@@ -104,35 +87,202 @@ module Jamf
       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
 
-    # TODO: Implement paging
+    # @return [String] The rest resource to get change logs for this object
+    #
     def change_log_rsrc
-      @change_log_rsrc ||= "#{rsrc_path}/history"
+      @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
 
-    # def change_log_rsrc(page: nil, size: nil)
-    #   params = ''
-    #   params << '?' if page || size
-    #   if page
+    # return the cached/cachable version of .change_log
     #
-    #   end
+    # @param refresh [Boolean] refetch the cache from the server?
     #
-    #   if size
+    # @param cnx [Jamf::Connection] The Connection to use
     #
-    #   end
-    #   params << '?' if page || size
-    #   params << '?' if page || size
+    # @return [Array<Jamf::ChangeLogEntry>] All the change_log entries
     #
-    #   @change_log_rsrc ||= "#{rsrc_path}/history"
-    # end
+    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 ChangeHistory
+  end # module ChangeLog
 
 end # module