ruby-jss 1.2.4a3 → 1.2.4a4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab1b92079de4a03997ab5fb60cf3463b63b7560cd45e83122ef52b563dec511
-  data.tar.gz: bedaefb57524c8d8abc820f5078d4a4db005436c71b214818e7f1ca3f2acebaf
+  metadata.gz: 745114754cc7073bbf494e8eb54f48962c9cafff99da985108c90b5bc7ccc62c
+  data.tar.gz: 6455a7c53abc89c47a03b1bd9538bc0bd3375eab1776ca9c5a15425595ed2ed3
 SHA512:
-  metadata.gz: dab434c14f91b160305f25bc8284a3e8731ae6edb842e9e600b667b46f53e126fc7a62e89c3875235a156d0b4b5628d143798e539ef196143d8d963bddb9fd1c
-  data.tar.gz: b5ec8b9709cc9d9b32d4b609a39452d2e7d21b425db3fc36ba3140c5b111d7da084c1969ae27d8d96785cd2e958e5c6f803f7624b4d76fdc077149c249c423bb
+  metadata.gz: 10cd851d966cc1e966dec194b27a4f282bba25b80177886dc03d44429206c8bc8bb223f141c9da27547f096a439937c6db3ae0d7e6498d2d6570b5bca164f716
+  data.tar.gz: a194cd0e76b6264afc1deef0b2567169a83c7fba9aaad796f050171783df202d1fd3ccf04f5eb11606ea387badce68920822c698aab819bfb46a2fd2549a919f

data/README.md

@@ -346,7 +346,7 @@ and then any calls to JSS.api.connect will assume that server and username, and
 
 The config files don't store passwords and the {JSS::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the JSS.api.connect call.
 
-The {JSS::API#connect} method also accepts the symbols :stdin# and :prompt as values for the :pw argument, which will cause it to read the password from a line of stdin, or prompt for it in the shell.
+The {JSS::APIConnection.connect} method also accepts the symbols :stdin# and :prompt as values for the :pw argument, which will cause it to read the password from a line of stdin, or prompt for it in the shell.
 
 If you must store a password in a file, or retrieve it from the network, make sure it's stored securely, and that the JSS user has limited permissions.
 

data/lib/jamf.rb

@@ -168,6 +168,7 @@ module Jamf
   autoload :MobileDevicePrestage, 'jamf/api/resources/collection_resources/mobile_device_prestage'
   autoload :Site, 'jamf/api/resources/collection_resources/site'
   autoload :Script, 'jamf/api/resources/collection_resources/script'
+  autoload :TimeZone, 'jamf/api/resources/collection_resources/time_zone'
 
   # other classes used as attributes inside the resource classes
   autoload :IPAddress, 'jamf/api/attribute_classes/ip_address'

data/lib/jamf/api/abstract_classes/collection_resource.rb

@@ -100,7 +100,11 @@ module Jamf
     def self.all(refresh = false, cnx: Jamf.cnx, instantiate: false)
       validate_not_abstract
       cnx.collection_cache[self] = nil if refresh
-      return cnx.collection_cache[self] if cnx.collection_cache[self]
+      if cnx.collection_cache[self]
+        return cnx.collection_cache[self] unless instantiate
+
+        return cnx.collection_cache[self].map { |m| new m }
+      end
 
       raw = cnx.get rsrc_path
       cnx.collection_cache[self] =
@@ -135,9 +139,10 @@ module Jamf
     # identifier and values are any other attribute.
     #
     # @param ident [Symbol] An identifier of this Class, used as the key
-    #   for the mapping Hash.
+    #   for the mapping Hash. Aliases are acceptable, e.g. :sn for :serialNumber
     #
-    # @param to [Symbol] The attribute to which the ident will be mapped
+    # @param to [Symbol] The attribute to which the ident will be mapped.
+    #   Aliases are acceptable, e.g. :name for :displayName
     #
     # @param refresh (see .all)
     #
@@ -146,11 +151,15 @@ module Jamf
     # @return [Hash {Symbol: Object}] A Hash of identifier mapped to attribute
     #
     def self.map_all(ident, to:, cnx: Jamf.cnx, refresh: false)
+      real_ident = attr_key_for_alias ident
       raise Jamf::InvalidDataError, "No identifier #{ident} for class #{self}" unless
-      identifiers.include? ident
+      identifiers.include? real_ident
 
-      raise Jamf::NoSuchItemError, "No attribute #{to} for class #{self}" unless self::OBJECT_MODEL.key? to
+      real_to = attr_key_for_alias to
+      raise Jamf::NoSuchItemError, "No attribute #{to} for class #{self}" unless self::OBJECT_MODEL.key? real_to
 
+      ident = real_ident
+      to = real_to
       list = all refresh, cnx: cnx
       to_class = self::OBJECT_MODEL[to][:class]
       mapped = list.map do |i|
@@ -163,13 +172,15 @@ module Jamf
     end
     # rubocop:enable Naming/UncommunicativeMethodParamName
 
-    # Given any identfier value for this collection, return the valid
-    # id, or nil if there's no match for the given value.
+    # Given any identfier value for this collection, return the id of the
+    # object that has such an identifier.
+    #
+    # Return nil if there's no match for the given value.
     #
-    # If you know the value is a certain identifier, e.g. a serial_number
-    # then you can specify the identifier, for a faster search:
+    # If you know the value is a certain identifier, e.g. a serialNumber,
+    # then you can specify the identifier for a faster search:
     #
-    #   valid_id serial_number: 'AB12DE34' # => Int or nil
+    #   valid_id serialNumber: 'AB12DE34' # => Int or nil
     #
     # If you don't know wich identifier you have, just pass the value and
     # all identifiers are searched
@@ -188,7 +199,7 @@ module Jamf
     # @param refresh[Boolean] Reload the list data from the API
     #
     # @param ident: [Symbol] Restrict the search to this identifier.
-    #  E.g. if :serial_number, then the value must be
+    #  E.g. if :serialNumber, then the value must be
     #  a known serial number, it is not checked against other identifiers
     #
     # @param cnx: (see .all)
@@ -375,7 +386,7 @@ module Jamf
       ident_map = map_all(ident, to: :id, cnx: cnx, refresh: refresh)
 
       # case-insensitivity for string values
-      value = ident_map.keys.j_ci_fetch_string(value) if value.is_a? String
+      value = ident_map.keys.j_ci_fetch(value) if value.is_a? String
 
       ident_map[value]
     end

data/lib/jamf/api/abstract_classes/json_object.rb

@@ -727,7 +727,7 @@ module Jamf
 
       attr_def[:aliases].each { |al| alias_method "#{al}_delete_if", "#{attr_name}_delete_if" }
     end # create_insert_setters
-    private_class_method :create_delete_at_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.
@@ -762,13 +762,9 @@ module Jamf
     #
     # Otherwise, the value is returned unchanged.
     #
-    # If the attribute is defined as an identifier, it must be unique among
-    # the other objects of this subclass in the JSS.
-    #
     # This method only validates single values. When called from multi-value
     # setters, it is used for each value individually.
     #
-    #
     # @param attr_name[Symbol], a top-level key from OBJECT_MODEL for this class
     #
     # @param value [Object] the value to validate for that attribute.

data/lib/jamf/api/abstract_classes/prestage.rb

@@ -241,11 +241,11 @@ module Jamf
     end
 
     # The id of the prestage to which the given serialNumber is assigned.
-    # nil if not assigned
+    # nil if not assigned or not in DEP.
     #
     # NOTE: If a serial number isn't assigned to any prestage, it may really be
-    # unassigned or it may not exist in your DEP. At the moment there's no way
-    # via the JP-API to know the SNs in DEP that are not assigned
+    # unassigned or it may not exist in your DEP. To see if a SN exists in one
+    # of your Device Enrollment instances, use Jamf::DeviceEnrollment.include?
     #
     # @param sn [String] the serial number to look for
     #
@@ -263,8 +263,8 @@ module Jamf
     # given prestage if a prestage_ident is specified?
     #
     # NOTE: If a serial number isn't assigned to any prestage, it may really be
-    # unassigned or it may not exist in your DEP. At the moment there's no way
-    # via the JP-API to know the SNs in DEP but not assigned
+    # unassigned or it may not exist in your DEP. To see if a SN exists in one
+    # of your Device Enrollment instances, use Jamf::DeviceEnrollment.include?
     #
     # @param sn [String] the serial number to look for
     #
@@ -283,10 +283,10 @@ module Jamf
       return false unless assigned_id
 
       if prestage_ident
-        id = valid_id prestage_ident, cnx: cnx
-        raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id
+        psid = valid_id prestage_ident, cnx: cnx
+        raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless psid
 
-        return id == assigned_id
+        return psid == assigned_id
       end
 
       true
@@ -305,13 +305,84 @@ module Jamf
       Jamf::DeviceEnrollment.device_sns(type: type, cnx: cnx) - serials_by_prestage_id(:refresh, cnx: cnx).keys
     end
 
-    # @return [Array<String>] The serial numbers of devices that are not in DEP
+    # @return [Array<String>] The serial numbers of known hardware not in DEP
     #   at all
     def self.sns_not_in_device_enrollment
       # type = self == Jamf::MobileDevicePrestage ? :mobiledevices : :computers
-      nil # TODO: this, once MobileDevice is implemented
+      nil # TODO: this, once MobileDevice  & Computer classes are implemented
     end
 
+    # Assign one or more serialNumber to a prestage
+    # @return [Jamf::PrestageScope] the new scope for the prestage
+    def self.assign(*sns_to_assign, to_prestage:, cnx: Jamf.cnx)
+      prestage_id = valid_id to_prestage
+      raise Jamf::NoSuchItemError, "No #{self} matching '#{to_prestage}'" unless prestage_id
+
+      # all sns_to_assign must be in DEP
+      not_in_dep = sns_to_assign - Jamf::DeviceEnrollment.device_sns
+      raise Jamf::UnsupportedError, "These SNs are not in any Device Enrollment instance: #{not_in_dep.join ', '}" unless not_in_dep.empty?
+
+      # all sns_to_assign must currently be unassigned.
+      already_assigned = sns_to_assign - unassigned_sns
+      raise Jamf::UnsupportedError, "These SNs are already assigned to a prestage: #{already_assigned.join ', '}" unless already_assigned.empty?
+
+      # upcase all sns
+      sns_to_assign.map!(&:to_s)
+      sns_to_assign.map!(&:upcase)
+
+      # get the prestage name
+      prestage_name = map_all(:id, to: :displayName)[prestage_id]
+
+      scope_rsrc = "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{prestage_id}/#{SCOPE_RSRC}"
+      scope = Jamf::PrestageScope.new cnx.get(scope_rsrc)
+
+      # add the new sns to the existing ones
+      new_scope_sns = scope.assignments.map(&:serialNumber)
+      new_scope_sns += sns_to_assign
+      new_scope_sns.uniq!
+
+      update_scope(prestage_name, scope_rsrc, new_scope_sns, scope.versionLock, cnx)
+    end # self.assign
+
+    # Unassign one or more serialNumber from a prestage
+    # @return [Jamf::PrestageScope] the new scope for the prestage
+    def self.unassign(*sns_to_unassign, from_prestage:, cnx: Jamf.cnx)
+      prestage_id = valid_id from_prestage
+      raise Jamf::NoSuchItemError, "No #{self} matching '#{from_prestage}'" unless prestage_id
+
+      # upcase all sns
+      sns_to_unassign.map!(&:to_s)
+      sns_to_unassign.map!(&:upcase)
+
+      # get the prestage name
+      prestage_name = map_all(:id, to: :displayName)[prestage_id]
+
+      scope_rsrc = "#{self::RSRC_VERSION}/#{self::RSRC_PATH}/#{prestage_id}/#{SCOPE_RSRC}"
+      scope = Jamf::PrestageScope.new cnx.get(scope_rsrc)
+
+      new_scope_sns = scope.assignments.map(&:serialNumber)
+      new_scope_sns -= sns_to_unassign
+
+      update_scope(prestage_name, scope_rsrc, new_scope_sns, scope.versionLock, cnx)
+    end # self.unassign
+
+    # Provate Class Methods
+    #####################################
+
+    # used by assign and unassign
+    def self.update_scope(prestage_name, scope_rsrc, new_scope_sns, vlock, cnx)
+      assignment_data = {
+        serialNumbers: new_scope_sns,
+        versionLock: vlock
+      }
+      Jamf::PrestageScope.new cnx.put(scope_rsrc, assignment_data)
+    rescue Jamf::Connection::APIError => e
+      raise Jamf::VersionLockError, "The #{self} '#{prestage_name}' was modified by another process during this operation. Please try again" if e.status == 409
+
+      raise e
+    end
+    private_class_method :update_scope
+
     # Instance Methods
     #####################################
 
@@ -351,19 +422,24 @@ module Jamf
 
     # Assign
     def assign(*sns_to_assign)
-      sns_to_assign.map!(&:to_s)
-      new_scope_sns = assigned_sns
-      new_scope_sns += sns_to_assign
-      new_scope_sns.uniq!
-      update_scope(new_scope_sns)
+      @scope = self.class.assign(sns_to_assign, to_prestage: @id, cnx: @cnx)
+      @versionLock = @scope.versionLock
+
+      # sns_to_assign.map!(&:to_s)
+      # new_scope_sns = assigned_sns
+      # new_scope_sns += sns_to_assign
+      # new_scope_sns.uniq!
+      # update_scope(new_scope_sns)
     end
     alias add assign
 
     def unassign(*sns_to_unassign)
-      sns_to_unassign.map!(&:to_s)
-      new_scope_sns = assigned_sns
-      new_scope_sns -= sns_to_unassign
-      update_scope(new_scope_sns)
+      @scope = self.class.unassign(sns_to_unassign, from_prestage: @id, cnx: @cnx)
+      @versionLock = @scope.versionLock
+      # sns_to_unassign.map!(&:to_s)
+      # new_scope_sns = assigned_sns
+      # new_scope_sns -= sns_to_unassign
+      # update_scope(new_scope_sns)
     end
     alias remove unassign
 
@@ -382,20 +458,20 @@ module Jamf
       @scope_rsrc ||= "#{self.class::RSRC_VERSION}/#{self.class::RSRC_PATH}/#{@id}/#{SCOPE_RSRC}"
     end
 
-    def update_scope(new_scope_sns)
-      assignment_data = {
-        serialNumbers: new_scope_sns,
-        versionLock: @scope.versionLock
-      }
-      begin
-        @scope = Jamf::PrestageScope.new @cnx.put(scope_rsrc, assignment_data)
-      rescue Jamf::Connection::APIError => e
-        raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again" if e.status == 409
-
-        raise e
-      end # begin
-      @versionLock = @scope.versionLock
-    end
+    # def update_scope(new_scope_sns)
+    #   assignment_data = {
+    #     serialNumbers: new_scope_sns,
+    #     versionLock: @scope.versionLock
+    #   }
+    #   begin
+    #     @scope = Jamf::PrestageScope.new @cnx.put(scope_rsrc, assignment_data)
+    #   rescue Jamf::Connection::APIError => e
+    #     raise Jamf::VersionLockError, "The #{self.class} '#{name}' has been modified since it was fetched. Please refetch and try again" if e.status == 409
+    #
+    #     raise e
+    #   end # begin
+    #   @versionLock = @scope.versionLock
+    # end
 
   end # class
 

data/lib/jamf/api/connection.rb

@@ -77,17 +77,17 @@ module Jamf
     DFT_SSL_VERSION = 'TLSv1_2'.freeze
 
     # refresh token if less than this many seconds until
-    # expiration. Default is 30 minutes if not specified
-    DFT_TOKEN_REFRESH = 60 * 30
+    # expiration. Default is 5 minutes if not specified
+    DFT_TOKEN_REFRESH = 300
 
     # pre-existing tokens must have this many seconds before
     # before they expire
     TOKEN_REUSE_MIN_LIFE = 60
 
-    HTTP_ACCEPT_HEADER = 'Accept'
-    HTTP_CONTENT_TYPE_HEADER = 'Content-Type'
+    HTTP_ACCEPT_HEADER = 'Accept'.freeze
+    HTTP_CONTENT_TYPE_HEADER = 'Content-Type'.freeze
 
-    MIME_JSON = 'application/json'
+    MIME_JSON = 'application/json'.freeze
 
     SLASH = '/'.freeze
 
@@ -316,8 +316,11 @@ module Jamf
     end # connect
 
     def disconnect
-      # reset everything except the name & timeouts
+      # reset everything except the timeouts
+      stop_keep_alive
+
       @connected = false
+      @name = NOT_CONNECTED
       @login_time = nil
       @host = nil
       @port = nil
@@ -327,6 +330,7 @@ module Jamf
       @rest_cnx = nil
       @ssl_options = {}
       @keep_alive = nil
+
       flushcache
     end
 
@@ -342,7 +346,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     # GET a rsrc without doing any JSON parsing, using
@@ -353,7 +357,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     def post(rsrc, data)
@@ -364,7 +368,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     def put(rsrc, data)
@@ -375,7 +379,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     def patch(rsrc, data)
@@ -386,7 +390,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     def delete(rsrc)
@@ -395,7 +399,7 @@ module Jamf
       @last_http_response = resp
       return resp.body if resp.success?
 
-      raise Jamf::Connection::APIError.new(resp)
+      raise Jamf::Connection::APIError, resp
     end
 
     # A useful string about this connection
@@ -403,13 +407,48 @@ module Jamf
     # @return [String]
     #
     def to_s
-      "Jamf::Connection: https://#{@user}@#{@host}:#{@port}"
+      str =
+        if connected?
+          "#{@base_url}, Token expires: #{@token ? @token.expires : '<token missing>'}"
+        else
+          NOT_CONNECTED
+        end
+      "Jamf::Connection '#{@name == NOT_CONNECTED ? object_id : @name}': #{str}"
+    end
+
+    # Reset the name
+    def name=(new_name)
+      @name = new_name.to_s
     end
 
+    # Are we keeping the connection alive?
     def keep_alive?
-      !@keep_alive_thread.nil?
+      @keep_alive_thread&.alive? || false
+    end
+
+    # @return [Jamf::Timestamp, nil]
+    def next_refresh
+      return unless keep_alive?
+
+      @token.expires - @token_refresh
+    end
+
+    # @return [Float, nil]
+    def secs_to_refresh
+      return unless keep_alive?
+
+      next_refresh - Time.now
+    end
+
+    # @return [String, nil] e.g. "1 week 6 days 23 hours 49 minutes 56 seconds"
+    def time_to_refresh
+      return unless keep_alive?
+      return 0 if secs_to_refresh.negative?
+
+      Jamf.humanize_secs secs_to_refresh
     end
 
+    # Turn keepalive on or offs
     def keep_alive=(bool)
       bool ? start_keep_alive : stop_keep_alive
     end
@@ -458,7 +497,6 @@ module Jamf
     ####################################
     private
 
-
     # raise exception if not connected
     def validate_connected
       raise Jamf::InvalidConnectionError, 'Not Connected. Use .connect first.' unless connected?
@@ -619,7 +657,11 @@ module Jamf
       @port = params[:port]
       @port ||= @host.end_with?(JAMFCLOUD_DOMAIN) ? JAMFCLOUD_PORT : ON_PREM_SSL_PORT
       @user = params[:user]
-      @token_refresh = params[:token_refresh] || DFT_TOKEN_REFRESH
+
+      @token_refresh = params[:token_refresh].to_i || DFT_TOKEN_REFRESH
+      # token refresh must be at least DFT_TOKEN_REFRESH
+      @token_refresh = DFT_TOKEN_REFRESH if @token_refresh < DFT_TOKEN_REFRESH
+
       @timeout = params[:timeout] || DFT_TIMEOUT
       @open_timeout = params[:open_timeout] || DFT_TIMEOUT
       @base_url = URI.parse "https://#{@host}:#{@port}/#{RSRC_BASE}"
@@ -702,9 +744,16 @@ module Jamf
         Thread.new do
           loop do
             sleep 60
-            next if @token.secs_remaining > @token_refresh
-
-            @token.keep_alive
+            begin
+              next if @token.secs_remaining > @token_refresh
+
+              @token.refresh
+              # make sure faraday uses the new token
+              @rest_cnx.headers[:authorization] = @token.auth_token
+            rescue
+              # TODO: Some kind of error reporting??
+              next
+            end
           end # loop
         end # thread
     end
@@ -715,9 +764,7 @@ module Jamf
     # @return [void]
     #
     def stop_keep_alive
-      return unless @keep_alive_thread
-
-      @keep_alive_thread.kill
+      @keep_alive_thread&.kill
       @keep_alive_thread = nil
     end
 
@@ -763,4 +810,8 @@ module Jamf
     @active_connection = connection
   end
 
+  def self.disconnect
+    @active_connection&.disconnect
+  end
+
 end # module Jamf

data/lib/jamf/api/connection/token.rb

@@ -119,24 +119,27 @@ module Jamf
 
       # @return [String]
       def api_version
-        token_connection(Jamf::Connection::SLASH, token: @auth_token ).get.body[:version]
+        token_connection(Jamf::Connection::SLASH, token: @auth_token).get.body[:version]
       end
 
       # @return [Boolean]
       def expired?
         return unless @expires
+
         Time.now >= @expires
       end
 
       # @return [Float]
       def secs_remaining
         return unless @expires
+
         @expires - Time.now
       end
 
       # @return [String] e.g. "1 week 6 days 23 hours 49 minutes 56 seconds"
       def time_remaining
         return unless @expires
+
         Jamf.humanize_secs secs_remaining
       end
 
@@ -155,18 +158,20 @@ module Jamf
       # the Jamf::Account object assciated with this token
       def account
         return @account if @account
+
         resp = token_connection(AUTH_RSRC, token: @auth_token).get
         return unless resp.success?
 
-         @account = Jamf::APIAccount.new resp.body
+        @account = Jamf::APIAccount.new resp.body
       end
 
       # Use this token to get a fresh one
+      # TODO: better error reporting
       def refresh
         raise 'Token has expired' if expired?
 
         keep_alive_token_resp = token_connection(KEEP_ALIVE_RSRC, token: @auth_token).post
-        # TODO: better error reporting here
+
         raise 'An error occurred while authenticating' unless keep_alive_token_resp.success?
 
         parse_token_from_response keep_alive_token_resp
@@ -189,8 +194,7 @@ module Jamf
       # acquision & manipulation
       #
       def token_connection(rsrc, token: nil, pw: nil, timeout: nil, ssl_opts: nil)
-
-        Faraday.new("#{@base_url}/#{rsrc}", ssl: ssl_opts ) do |con|
+        Faraday.new("#{@base_url}/#{rsrc}", ssl: ssl_opts) do |con|
           con.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_JSON
           con.response :json, parser_options: { symbolize_names: true }
           con.options[:timeout] = timeout

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

@@ -77,10 +77,13 @@ module Jamf
       # @!attribute deviceEnrollmentProgramInstanceId
       #   @return [Integer]
       deviceEnrollmentProgramInstanceId: {
-        class: :integer
+        class: :integer,
+        aliases: %i[instanceId]
       },
 
       # @!attribute prestageId
+      #   The most recent prestage this device was assigned to, even if
+      #   currently unassigned to any prestage.
       #   @return [Integer]
       prestageId: {
         class: :integer
@@ -135,6 +138,7 @@ module Jamf
       },
 
       # @!attribute deviceAssignedDate
+      #   When Apple assigned this device to this DevEnrollment instance
       #   @return [Jamf::Timestamp]
       deviceAssignedDate: {
         class: Jamf::Timestamp
@@ -146,8 +150,6 @@ module Jamf
     # Class Methods
     #########################################
 
-
-
     # Instance Methods
     #########################################
 

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

@@ -26,7 +26,8 @@
 # The module
 module Jamf
 
-  # A 'location' for a managed object in Jamf Pro
+  # An assignment of a device to a prestage, placing that
+  # device into the prestage's scope
   class PrestageAssignment < Jamf::JSONObject
 
     extend Jamf::Immutable
@@ -48,7 +49,8 @@ module Jamf
       # @!attribute userAssigned
       #   @return [String]
       userAssigned: {
-        class: :string
+        class: :string,
+        aliases: %i[assignedBy]
       }
     }.freeze
 

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

@@ -60,6 +60,8 @@ module Jamf
   #
   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

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

@@ -161,7 +161,7 @@ module Jamf
           enum: SORT_DIRECTIONS
         }
       }.freeze
-
+      parse_object_model
     end # class Orderby
 
     class SeachParams < Jamf::JSONObject
@@ -194,7 +194,7 @@ module Jamf
         }
 
       }.freeze
-
+      parse_object_model
     end # class SearchParams
 
   end # module searchable

data/lib/jamf/api/resources/collection_resources/department.rb

@@ -71,6 +71,7 @@ module Jamf
         required: true
       }
     }.freeze
+
     parse_object_model
 
 

data/lib/jamf/api/resources/collection_resources/device_enrollment.rb

@@ -144,6 +144,8 @@ module Jamf
 
     LATEST_RSRC = 'latest'.freeze
 
+    DISOWN_RSRC = 'disown'.freeze
+
     TYPES = %i[computers mobiledevices].freeze
 
     COMPUTERS_RE = /mac/i.freeze
@@ -152,7 +154,12 @@ module Jamf
     #########################################
 
     # All devices associated by Apple with a given DeviceEnrollment instance
-    # or all defined DeviceEnrollment instances
+    # or all defined DeviceEnrollment instances.
+    #
+    # This data is cached the first time it is read from the API, similarly to
+    # how CollectionResources are cached. To refresh the cache, pass
+    # a truthy value to the refresh: parameter, or use the Connection's
+    # .flushcache method
     #
     # @param instance_ident[Integer, String] the id or name of the
     #   DeviceEnrollment instance for which to list the devices. If omitted,
@@ -161,17 +168,19 @@ module Jamf
     # @param type[Symbol] Either :computers or :mobiledevices, returns both if
     #  not specified.
     #
+    # @param refresh [Boolean] re-read the data from the API?
+    #
     # @param cnx[Jamf::Connection] The API connection to use
     #
     # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices associated with
-    #   the given, or all,  instances
+    #   the given DeviceEnrollment instance, or all instances
     #
-    def self.devices(instance_ident = nil, type: nil, cnx: Jamf.cnx)
+    def self.devices(instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
       if type
         raise ArgumentError, "Type must be one of: :#{TYPES.join ', :'}" unless TYPES.include? type
       end
 
-      devs = fetch_devices(instance_ident, cnx)
+      devs = fetch_devices(instance_ident, refresh, cnx)
       return devs unless type
 
       if type == :computers
@@ -181,23 +190,33 @@ module Jamf
       end
     end
 
+    # The serial numbers assigned bu Apple to one, or all of your
+    # Device Enrollment instances
+    #
     # See .devices
+    #
     # @return [Array<String>] just the serial numbers for the devices
     #
-    def self.device_sns(instance_ident = nil, type: nil, cnx: Jamf.cnx)
-      devices(instance_ident, type: type, cnx: cnx).map(&:serialNumber)
+    def self.device_sns(instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      devices(instance_ident, type: type, refresh: refresh, cnx: cnx).map(&:serialNumber)
     end
 
+    # Is the given serial number in one, or any, or your Device Enrollment
+    # instances?
+    #
     # See .devices
     #
+    # @param sn [String] the serialNumber to look for
+    #
     # @return [Boolean] is the given SN in a given DeviceEnrollment instance
     # or in DEP at all?
     #
-    def self.include?(sn, instance_ident = nil, type: nil, cnx: Jamf.cnx)
-      device_sns(instance_ident, type: type, cnx: cnx).j_ci_include? sn
+    def self.include?(sn, instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
+      device_sns(instance_ident, type: type, refresh: refresh, cnx: cnx).j_ci_include? sn
     end
 
     # See .devices
+    #
     # Returns just those devices with the desired profileStatus, which must be
     # an item in DeviceEnrollmentDevice::PROFILE_STATUSES
     #
@@ -206,14 +225,54 @@ module Jamf
     # @return [Array<Jamf::DeviceEnrollmentDevice>] The devices with the desired
     #   status, associated with the given, or all,  instances
     #
-    def self.devices_with_status(status, instance_ident = nil, type: nil, cnx: Jamf.cnx)
+    def self.devices_with_status(status, instance_ident = nil, type: nil, refresh: false, cnx: Jamf.cnx)
       unless Jamf::DeviceEnrollmentDevice::PROFILE_STATUSES.include? status
         raise ArgumentError, "profileStatus must be one of: '#{Jamf::DeviceEnrollmentDevice::PROFILE_STATUSES.join "', '"}'"
       end
 
-      devices(instance_ident, type: type, cnx: cnx).select { |d| d.profileStatus == status }
+      devices(instance_ident, type: type, refresh: refresh, cnx: cnx).select { |d| d.profileStatus == status }
     end
 
+    # Fetch a single device from any defined DeviceEnrollment instance.
+    # The instance id containing the device is available in its
+    # .deviceEnrollmentProgramInstanceId attribute.
+    #
+    # @pararm sn [String] the serial number of the device
+    #
+    # @param instance_ident [String, Integer] the name or id of the instance
+    # in which to look for the sn. All instances are searched if omitted.
+    #
+    # @param refresh [Boolean] re-read the data from the API?
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Jamf::DeviceEnrollmentDevice] the device as known to DEP
+    #
+    def self.device(sn, instance_ident = nil, refresh: false, cnx: Jamf.cnx)
+      sn.upcase! # SNs from apple are always uppercase
+      devs = devices(instance_ident, refresh: refresh, cnx: cnx)
+      dev = devs.select { |d| d.serialNumber == sn }.first
+      return dev if dev
+
+      searched = instance_ident ? "DeviceEnrollment instance #{instance_ident}" : 'any DeviceEnrollment instance'
+      raise Jamf::NoSuchItemError, "No device with serialNumber '#{sn}' in #{searched}"
+    end
+
+    # The history of sync operations between Apple and a given DeviceEnrollment
+    # instanace, or all instances.
+    #
+    # @param instance_ident[Integer, String] the id or name of the
+    #   DeviceEnrollment instance for which to get the history. If omitted,
+    #   the history for all instances will be returned.
+    #
+    # @param latest [Boolean] show only the latest sync? Only valid when an
+    #   instance_ident is provided.
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [Jamf::DeviceEnrollmentSyncStatus] When latest = true, the latest
+    #   sync status.
+    # @return [Array<Jamf::DeviceEnrollmentSyncStatus>] The known sync statuses.
     #
     def self.sync_history(instance_ident = nil, latest = false, cnx: Jamf.cnx)
       if instance_ident
@@ -232,31 +291,60 @@ module Jamf
       data.map! { |s| Jamf::DeviceEnrollmentSyncStatus.new s }
     end
 
+    # disown one or more serial numbers from a given DeviceEnrollment instance
+    #
+    # @param sns[Array<String>] One or more serial numbers to disown
+    #
+    # @param from_instance [Integer, String] the id or name of the instance
+    #  from which to disown the serial numbers
+    #
+    # @param cnx[Jamf::Connection] The API connection to use
+    #
+    # @return [void]
+    #
+    def self.disown(*sns, from_instance:, cnx: Jamf.cnx)
+      instance_id = valid_id from_instance, cnx: cnx
+      raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance}'" unless instance_id
+
+      sns.flatten!
+      sns.map!(&:to_s)
+      data = { devices: sns }
+      disown_rsrc = "#{self.class::RSRC_VERSION}/#{self.class::RSRC_PATH}/#{instance_id}/#{DISOWN_RSRC}"
+
+      cnx.post(disown_rsrc, data)
+    end
+
     # Private Class Methods
     ###############################################
 
     # Private, used by the .devices class method
-    def self.fetch_devices(instance_ident, cnx)
+    def self.fetch_devices(instance_ident, refresh, cnx)
       if instance_ident
         instance_id = valid_id instance_ident, cnx: cnx
-        raise Jamf::NoSuchItemError "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
+        raise Jamf::NoSuchItemError, "No DeviceEnrollment instance matches '#{instance_ident}'" unless instance_id
 
-        devs = devices_for_instance_id instance_id, cnx
+        devs = devices_for_instance_id instance_id, refresh, cnx
       else
         devs = []
         all_ids.each do |id|
-          devs += devices_for_instance_id id, cnx
+          devs += devices_for_instance_id id, refresh, cnx
         end
       end
       devs
     end
     private_class_method :fetch_devices
 
-    # Private, used by the .devices class method
-    def self.devices_for_instance_id(instance_id, cnx)
+    # Private, used by the .fetch_devices class method
+    def self.devices_for_instance_id(instance_id, refresh, cnx)
+      @device_cache ||= {}
+      @device_cache[cnx] ||= {}
+      @device_cache[cnx][instance_id] = nil if refresh
+      return @device_cache[cnx][instance_id] if @device_cache[cnx][instance_id]
+
       data = cnx.get("#{RSRC_VERSION}/#{RSRC_PATH}/#{instance_id}/#{DEVICES_RSRC}")[:results]
 
-      data.map { |dev| Jamf::DeviceEnrollmentDevice.new dev }
+      data.map! { |dev| Jamf::DeviceEnrollmentDevice.new dev }
+      @device_cache[cnx][instance_id] = data
     end
     private_class_method :devices_for_instance_id
 
@@ -287,6 +375,10 @@ module Jamf
       sync_history :latest
     end
 
+    def disown(*sns)
+      self.class.disown sns, from_instance: @id, cnx: @cnx
+    end
+
   end # class
 
 end # module

data/lib/jamf/api/resources/collection_resources/time_zone.rb

@@ -0,0 +1,119 @@
+# Copyright 2019 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
+
+  # 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
+
+    # Object Model / Attributes
+    # See APIObject class documentation for details
+    # of how the OBJECT_MODEL hash works.
+    #####################################
+    OBJECT_MODEL = {
+
+      # @!attribute [r] zoneId
+      #   @return [String]
+      zoneId: {
+        class: :string,
+        identifier: :primary,
+        aliases: [:id]
+      },
+
+      # @!attribute displayName
+      #   @return [String]
+      displayName: {
+        class: :string,
+        identifier: true,
+        aliases: [:name]
+      },
+
+      # @!attribute [r] region
+      #   @return [String]
+      region: {
+        class: :string
+      }
+    }.freeze
+    parse_object_model
+
+    # The offset from UTC, as a string.
+    #
+    # This is as it would appear at the end of an ISO8601 formatted time,
+    # e.g. -0945 or +1200
+    #
+    # Note that ISO8601 accepts the formats: +/-hh:mm, +/-hhmm, or +/-hh
+    #
+    # @return [Integer] The offset from UTC, as a string
+    #
+    def utc_offset_str
+      return @utc_offset_str if @utc_offset_str
+
+      displayName =~ /\(([+-]\d{4})\)/
+      @utc_offset_str = Regexp.last_match[1]
+    end
+
+    # @return [Integer] The offset from UTC, in seconds
+    #
+    def utc_offset
+      return @utc_offset if @utc_offset
+
+      sign = utc_offset_str[0]
+      secs = utc_offset_str[1..2].to_i * 3600
+      secs += utc_offset_str[3..4].to_i * 60
+      # negate if needed
+      @utc_offset =  sign == '+' ? secs : -secs
+    end
+
+    # Give a Time object, whats the matching local time in this TimeZone?
+    #
+    # @param othertime[Time] a Time or Jamf::Timestamp object
+    #
+    # @return [Time] othertime, in the local time in this time zone
+    #
+    def localtime(othertime)
+      othertime.getlocal utc_offset
+    end
+
+  end # class
+
+end # module

data/lib/jamf/client.rb

@@ -24,7 +24,7 @@
 ###
 
 ###
-module JSS
+module Jamf
 
   # This class represents a Jamf/JSS Client computer, on which
   # this code is running.
@@ -78,10 +78,17 @@ module JSS
     # the path to a users byhost folder from home
     USER_PREFS_BYHOST_FOLDER = 'Library/Preferences/ByHost/'
 
-    # Class Methods
-    #####################################
+    # If some processs C has a parent process P whose command (via ps -o comm)
+    # matches this, then process C is being run by Jamf
+    POLICY_SCRIPT_CMD_RE = %r{sh -c PATH=\$PATH:/usr/local/jamf/bin; '/Library/Application Support/JAMF/tmp/.* >& '/Library/Application Support/JAMF/tmp/\d+.tmp}.freeze
 
+    # If some processs C has a parent process P whose command (via ps -o comm)
+    # matching POLICY_SCRIPT_CMD_RE, and process P has a parent process G that
+    # matches this (C is grandchild of G), then process C is being run by a Jamf policy
+    POLICY_CMD_RE = %r{/bin/jamf policy }.freeze
 
+    # Class Methods
+    #####################################
 
     # Get the current IP address as a String.
     #
@@ -292,6 +299,54 @@ module JSS
       dir ? Pathname.new(dir) : nil
     end
 
+    # Search up the process lineage to see if any ancestor processes indicate
+    # that the current process is being run by a Jamf Policy.
+    #
+    # @return [Boolean] Is the current process being run as a script by a Jamf Policy?
+    #
+    def self.script_running_via_policy?
+      root_ps_lines = `ps -u root -x -o pid -o ppid -o user -o command`.lines
+
+      parent_pid, _parent_user, parent_command = parent_pid_user_and_cmd Process.pid, root_ps_lines
+      return false unless parent_pid
+
+      until parent_command =~ POLICY_SCRIPT_CMD_RE || parent_pid.nil?
+        parent_pid, _parent_user, parent_command = parent_pid_user_and_cmd parent_pid, root_ps_lines
+        return false if parent_pid.zero?
+      end
+      return false if parent_pid.nil?
+
+      # if we're here, our parent is a jamf process, lets confirm that its
+      # a jamf policy
+      until parent_command =~ POLICY_CMD_RE || parent_pid.nil?
+        parent_pid, _parent_user, parent_command = parent_pid_user_and_cmd parent_pid, root_ps_lines
+        return false if parent_pid.zero?
+      end
+      !parent_pid.nil?
+    end
+
+    # given a pid and optionally the output of `ps -o pid -o ppid -o user -o command`
+    # return an array with the pid, user, and command of the pid's parent process
+    #
+    # @param pid [Integer, String] the process id for which we want parent info
+    #
+    # @param ps_lines [Array<String>] the lines of output from
+    #   `ps -o pid -o ppid -o user -o command` possibly with other options.
+    #    If omitted, `ps -a -x -o pid -o ppid -o user -o command` will be used
+    #
+    # @return [Array<Integer, String, String>] the pid, user, and commandline
+    #  of the parent process of the given pid. All will be nil if not found
+    #
+    def self.parent_pid_user_and_cmd(pid, ps_lines = nil)
+      ps_lines ||= `ps -a -x -o pid -o ppid -o user -o command`.lines
+
+      parent_ps_line = ps_lines.select { |l| l =~ /^\s*#{pid}\s/ }.first
+      return [nil, nil, nil] unless parent_ps_line
+
+      parent_ps_line =~ /^\s*\d+\s+(\d+)\s+(\S+)\s+(.*)$/
+      [Regexp.last_match(1).to_i, Regexp.last_match(2), Regexp.last_match(3)]
+    end
+
   end # class Client
 
 end # module

data/lib/jamf/configuration.rb

@@ -159,7 +159,7 @@ module Jamf
     # @return [void]
     #
     def read_global
-      read GLOBAL_CONF_FILE if GLOBAL_CONF_FILE.file? && GLOBAL_CONF_FILE.readable?
+      read GLOBAL_CONF_FILE if GLOBAL_CONF_FILE&.file? && GLOBAL_CONF_FILE.readable?
     end
 
     # (Re)read the user prefs, if it exists.
@@ -167,7 +167,7 @@ module Jamf
     # @return [void]
     #
     def read_user
-      read USER_CONF_FILE if USER_CONF_FILE.file? && USER_CONF_FILE.readable?
+      read USER_CONF_FILE if USER_CONF_FILE&.file? && USER_CONF_FILE.readable?
     end
 
     # Clear the settings and reload the prefs files, or another file if provided

data/lib/jamf/ruby_extensions/array/utils.rb

@@ -40,7 +40,8 @@ module JamfRubyExtensions
       #   nil if it doesn't exist
       #
       def j_ci_fetch(somestring)
-        each { |s| return s if s.is_a?(String) && s.casecmp?(somestring) }
+        # select { |s| s&.casecmp? somestring }.first
+        each { |s| return s if s&.casecmp?(somestring) }
         nil
       end
 
@@ -51,7 +52,7 @@ module JamfRubyExtensions
       # @return [Boolean]
       #
       def j_ci_include?(somestring)
-        any? { |s| s.casecmp? somestring if s.is_a? String }
+        any? { |s| s&.casecmp? somestring }
       end
 
     end # module

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of ruby-jss
-  VERSION = '1.2.4a3'.freeze
+  VERSION = '1.2.4a4'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 1.2.4a3
+  version: 1.2.4a4
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-06 00:00:00.000000000 Z
+date: 2020-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist
@@ -218,6 +218,7 @@ files:
 - lib/jamf/api/resources/collection_resources/mobile_device_prestage.rb
 - lib/jamf/api/resources/collection_resources/script.rb
 - lib/jamf/api/resources/collection_resources/site.rb
+- lib/jamf/api/resources/collection_resources/time_zone.rb
 - lib/jamf/api/resources/singleton_resources/app_store_country_codes.rb
 - lib/jamf/api/resources/singleton_resources/authorization.rb
 - lib/jamf/api/resources/singleton_resources/client_checkin_settings.rb