ruby-jss 0.10.0 → 0.10.1a2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 769cbc0fa921b444480b1c3b588664c3c3937aa7
-  data.tar.gz: 4a4d8ab91135e180d49e52e2be783019cb42e978
+  metadata.gz: cbc35fe360debd8ec27b382a0bacb3437a2a2bdd
+  data.tar.gz: '08e688dae6471d1075b582e544635dc0710f7b2c'
 SHA512:
-  metadata.gz: '069697c8db875ece53b7490a7ec095d695d2852dd1c6d20acc4a6d4a0acdcc4a59f7e978b8408f03796b52f9713991c2345f716aef964bf08bcfea364b384887'
-  data.tar.gz: 7de60430c90c5ce3f7f92afdb75307e1a8798d22ba75868dd6702970d829c81143943da96fc759612cf9d477e0fc6535e77bb793865ffe22b94efdf6f95d9ffc
+  metadata.gz: b2875e1733f3c187248d4a0e17e6ca3fe795231d2391b7764f60d627c9f7fafe2a9c44d4b38e941633eab9cf604db8b7d36cb89ef4ce13af2c69976345405be5
+  data.tar.gz: 9e7d9a29bfe5c6e88ea1c79674d5dc8fa8588a5f6c5793fb733e9a30c1f3105bc5c98da4b16c3f457715dd7b31cfaf26db1fb662edb6357470a7e9e8c3ab4aba

data/lib/jss/api_object.rb

@@ -524,6 +524,11 @@ module JSS
       name: { rsrc_key: :name, list: :all_names }
     }.freeze
 
+    # This table holds the object history for JSS objects.
+    # Object history is not available via the API,
+    # only MySQL.
+    OBJECT_HISTORY_TABLE = 'object_history'.freeze
+
     # Attributes
     #####################################
 
@@ -726,10 +731,107 @@ module JSS
       vars
     end
 
+    # Make an entry in this object's Object History.
+    # For this to work, the APIObject subclass must define
+    # OBJECT_HISTORY_OBJECT_TYPE, an integer indicating the
+    # object type in the OBJECT_HISTORY_TABLE in the database
+    # (e.g. for computers, the object type is 1)
+    #
+    # NOTE: Object history is not available via the API,
+    #   so access is only available through direct MySQL
+    #   connections
+    #
+    # Also: the 'details' column in the table shows up in the
+    #   'notes' column of the Web UI.  and the 'object_description'
+    #   column of the table shows up in the 'details' column of
+    #   the UI, under the 'details' button.
+    #
+    #   The params below reflect the UI, not the table.
+    #
+    # @param user[String] the username creating the entry.
+    #
+    # @param notes[String] A string that appears as a 'note' in the history
+    #
+    # @param details[String] A string that appears as the 'details' in the history
+    #
+    # @return [void]
+    #
+    def add_object_history_entry(user: nil, notes: nil, details: nil)
+      validate_object_history_available
+
+      raise JSS::MissingDataError, 'A user: must be provided to make the entry' unless user
+
+      raise JSS::MissingDataError, 'Either notes: must be provided to make the entry' unless notes
+
+      user = "'#{Mysql.quote user.to_s}'"
+      notes =  "'#{Mysql.quote notes.to_s}'"
+      obj_type = self.class::OBJECT_HISTORY_OBJECT_TYPE
+
+      field_list = 'object_type, object_id, username, details, timestamp_epoch'
+      value_list = "#{obj_type}, #{@id}, #{user}, #{notes}, #{Time.now.to_jss_epoch}"
+
+      if details
+        field_list << ', object_description'
+        value_list << ", '#{Mysql.quote details.to_s}'"
+      end # if details
+
+      q = "INSERT INTO #{OBJECT_HISTORY_TABLE}
+        (#{field_list})
+      VALUES
+        (#{value_list})"
+
+      JSS::DB_CNX.db.query q
+    end
+
+    # the object history for this object, an array of hashes
+    # one per history entry, in order of creation.
+    # Each hash contains:
+    #   user: String, the username that created the entry
+    #   notes:  String, the notes for the entry
+    #   date: Time, the timestamp for the entry
+    #   details: String or nil, any details provided for the entry
+    #
+    # @return [Array<Hash>] the object history
+    #
+    def object_history
+      validate_object_history_available
+
+      q = "SELECT username, details, timestamp_epoch, object_description
+      FROM #{OBJECT_HISTORY_TABLE}
+      WHERE object_type = #{self.class::OBJECT_HISTORY_OBJECT_TYPE}
+      AND object_id = #{@id}
+      ORDER BY object_history_id ASC"
+
+      result = JSS::DB_CNX.db.query q
+      history = []
+      result.each do |entry|
+        history << {
+          user: entry[0],
+          notes: entry[1],
+          date: JSS.epoch_to_time(entry[2]),
+          details: entry[3]
+        }
+      end # each do entry
+      history
+    end
+
     # Private Instance Methods
     #####################################
     private
 
+    # Raise an exception if object history is not
+    # available for this object
+    #
+    # @return [void]
+    #
+    def validate_object_history_available
+      raise JSS::NoSuchItemError, 'Object not yet created' unless @id && @in_jss
+
+      raise JSS::InvalidConnectionError, 'Not connected to MySQL' unless JSS::DB_CNX.connected?
+
+      raise JSS::UnsupportedError, "Object History access is not supported for #{self.class} objects at this time" unless defined? self.class::OBJECT_HISTORY_OBJECT_TYPE
+    end
+
     # If we were passed pre-lookedup API data, validate it,
     # raising exceptions if not valid.
     #

data/lib/jss/api_object/advanced_search/advanced_computer_search.rb

@@ -75,6 +75,10 @@ module JSS
     # for each computer?
     RESULT_ID_FIELDS = [:id, :name, :udid].freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 70
 
     # Attributes
     #####################################

data/lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb

@@ -69,6 +69,11 @@ module JSS
     # for each mobiledevices?
     RESULT_ID_FIELDS = [:id, :name, :udid].freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 71
+
     # Attributes
     #####################################
 

data/lib/jss/api_object/advanced_search/advanced_user_search.rb

@@ -69,6 +69,11 @@ module JSS
     # for each user?
     RESULT_ID_FIELDS = [:id, :name].freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 55
+
     # Attributes
     #####################################
 

data/lib/jss/api_object/building.rb

@@ -66,6 +66,11 @@ module JSS
     # these keys, as well as :id and :name,  are present in valid API JSON data for this class
     VALID_DATA_KEYS = [].freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 41
+
     # Attributes
     #####################################
 

data/lib/jss/api_object/category.rb

@@ -85,6 +85,11 @@ module JSS
     # The Default Priority
     DEFAULT_PRIORITY = 5
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 72
+
     # Attributes
     #####################################
 

data/lib/jss/api_object/computer.rb

@@ -331,6 +331,12 @@ module JSS
 
     POLICY_STATUS_PENDING = 'Pending'.freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 1
+
+
     # Class Methods
     #####################################
 
@@ -808,8 +814,7 @@ module JSS
     # @return [Hash, nil] The hardware[:storage] hash of the boot drive
     #
     def boot_drive
-      drives.each { |d| return d if d[:partition][:type] == 'boot' }
-      nil
+      drives.select { |d| d[:partition] && d[:partition][:type] == 'boot' }.first
     end
 
     # @return [Array<Hash>]  each printer on this computer

data/lib/jss/api_object/computer_invitation.rb

@@ -83,6 +83,11 @@ module JSS
       invitation: {rsrc_key: :invitation, list: :all_invitations}
     }.freeze
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 84
+
     # Attributes
     #####################################
 

data/lib/jss/api_object/department.rb

@@ -1,31 +1,31 @@
 ### Copyright 2017 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 JSS
-  
+
   #####################################
   ### Module Variables
   #####################################
@@ -33,25 +33,25 @@ module JSS
   #####################################
   ### Module Methods
   #####################################
-  
+
   #####################################
   ### Classes
   #####################################
 
-  ### 
+  ###
   ### A department in the JSS.
   ### These are simple, in that they only have an ID and a name
   ###
   ### @see JSS::APIObject
   ###
   class Department < JSS::APIObject
-    
+
     #####################################
     ### Mix-Ins
     #####################################
     include JSS::Creatable
     include JSS::Updatable
-    
+
     #####################################
     ### Class Methods
     #####################################
@@ -59,28 +59,33 @@ module JSS
     #####################################
     ### Class Constants
     #####################################
-    
+
     ### The base for REST resources of this class
     RSRC_BASE = "departments"
-    
+
     ### the hash key used for the JSON list output of all objects in the JSS
     RSRC_LIST_KEY = :departments
-    
+
     ### The hash key used for the JSON object output.
     ### It's also used in various error messages
     RSRC_OBJECT_KEY = :department
-    
+
     ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
     VALID_DATA_KEYS = []
-    
+
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 42
+
     #####################################
     ### Attributes
     #####################################
-    
+
     #####################################
-    ### Constructor 
+    ### Constructor
     #####################################
-    
+
     ###
     ### See JSS::APIObject#initialize
     ###
@@ -88,7 +93,7 @@ module JSS
     #####################################
     ### Public Instance Methods
     #####################################
-    
+
   end # class department
-  
+
 end # module

data/lib/jss/api_object/distribution_point.rb

@@ -85,6 +85,11 @@ module JSS
 
     DEFAULT_MOUNTPOINT_PREFIX = "CasperDistribution-id"
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 76
+
     ### Class Methods
     #####################################
 

data/lib/jss/api_object/ebook.rb

@@ -16,6 +16,11 @@ module JSS
     ### It's also used in various error messages
     RSRC_OBJECT_KEY = :ebook
 
+    # the object type for this object in
+    # the object history table.
+    # See {APIObject#add_object_history_entry}
+    OBJECT_HISTORY_OBJECT_TYPE = 24
+
   end
 
 end

data/lib/jss/api_object/extendable.rb

@@ -1,119 +1,97 @@
-### Copyright 2017 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.
-###
-###
-
-###
+# Copyright 2017 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 JSS
 
-  #####################################
-  ### Module Variables
-  #####################################
-
-  #####################################
-  ### Module Methods
-  #####################################
-
-  #####################################
-  ### Sub-Modules
-  #####################################
-
-  ### A mix-in module for handling extension attribute data for objects in the JSS.
-  ###
-  ### This module provides standardized ways to deal with Extension Attribute data
-  ### in objects that gather that data  ({JSS::Computer}s, {JSS::MobileDevice}s,
-  ### and {JSS::User}s). For working with the Extension Attributes themselves, see
-  ### {JSS::ExtensionAttribute} and its subclasses.
-  ###
-  ### API objects that have Extension Attribute data return it in an Array of Hashes,
-  ### one for each defined ExtensionAttribute for the class;
-  ### i.e. a {JSS::Computer}'s Array has one Hash for each {JSS::ComputerExtensionAttribute}
-  ### defined in the JSS.
-  ###
-  ### The Hash keys are:
-  ### * :id => the ExtAttr id
-  ### * :name => the ExtAttr name
-  ### * :type => the data type of the ExtAttr value
-  ### * :value => the value for the ExtAttr for this object as of the last report.
-  ###
-  ### Classes including this module must define the constant EXT_ATTRIB_CLASS
-  ### specifying which {JSS::ExtensionAttribute} subclass defines the relevant extension attributes.
-  ### For Example, {JSS::Computer} sets this:
-  ###   EXT_ATTRIB_CLASS = JSS::ComputerExtensionAttribute
-  ###
-  ###
-  ### Parsing also populates @ext_attrs which is a Hash of name => value for each EA.
-  ###
-  ### When updating or creating, those classes must add the REXML output of {#ext_attr_xml} to their
-  ### rest_xml output.
-  ###
+  # Sub-Modules
+  ###################################
+
+  # A mix-in module for handling extension attribute data for objects in the JSS.
+  #
+  # This module provides standardized ways to deal with Extension Attribute data
+  # in objects that gather that data  ({JSS::Computer}s, {JSS::MobileDevice}s,
+  # and {JSS::User}s). For working with the Extension Attributes themselves, see
+  # {JSS::ExtensionAttribute} and its subclasses.
+  #
+  # API objects that have Extension Attribute data return it in an Array of Hashes,
+  # one for each defined ExtensionAttribute for the class;
+  # i.e. a {JSS::Computer}'s Array has one Hash for each {JSS::ComputerExtensionAttribute}
+  # defined in the JSS.
+  #
+  # The Hash keys are:
+  # * :id => the ExtAttr id
+  # * :name => the ExtAttr name
+  # * :type => the data type of the ExtAttr value
+  # * :value => the value for the ExtAttr for this object as of the last report.
+  #
+  # Classes including this module must define the constant EXT_ATTRIB_CLASS
+  # specifying which {JSS::ExtensionAttribute} subclass defines the relevant extension attributes.
+  # For Example, {JSS::Computer} sets this:
+  #   EXT_ATTRIB_CLASS = JSS::ComputerExtensionAttribute
+  #
+  #
+  # Parsing also populates @ext_attrs which is a Hash of name => value for each EA.
+  #
+  # When updating or creating, those classes must add the REXML output of {#ext_attr_xml} to their
+  # rest_xml output.
+  #
   module Extendable
 
-    #####################################
-    ###  Constants
-    #####################################
+    #  Constants
+    ###################################
 
-    ###
     EXTENDABLE = true
 
+    # ExtensionAttributes refer to the numeric data type as "Integer"
+    # but the ext. attr values that come with extendable objects refer to
+    # that data type as "Number".  Here's an array with both, so we can
+    # work with ether more easily.
+    NUMERIC_TYPES = %w[Number Integer].freeze
 
-    ### ExtensionAttributes refer to the numeric data type as "Integer"
-    ### but the ext. attr values that come with extendable objects refer to
-    ### that data type as "Number".  Here's an array with both, so we can
-    ### work with ether more easily.
-    NUMERIC_TYPES = ["Number", "Integer"]
+    #  Attribtues
+    ###################################
 
-    #####################################
-    ###  Variables
-    #####################################
-
-    #####################################
-    ###  Attribtues
-    #####################################
-
-    ### @return [Array<Hash>] The extension attribute values for the object
+    # @return [Array<Hash>] The extension attribute values for the object
     attr_reader :extension_attributes
 
-    ### @return [Hash] A mapping of Ext Attrib names to their values
+    # @return [Hash] A mapping of Ext Attrib names to their values
     attr_reader :ext_attrs
 
-    #####################################
-    ###  Mixed-in Instance Methods
-    #####################################
-
-
-
-    ###
-    ### Populate @extension_attributes (the Array of Hashes that comes from the API)
-    ### and @ext_attr_names, which is a Hash mapping the EA names to their
-    ### index in the @extension_attributes Array.
-    ###
-    ### Classes including this module should call this in #initialize
-    ###
-    ### @return [void]
-    ###
+    #  Mixed-in Instance Methods
+    ###################################
+
+    # Populate @extension_attributes (the Array of Hashes that comes from the API)
+    # and @ext_attr_names, which is a Hash mapping the EA names to their
+    # index in the @extension_attributes Array.
+    #
+    # Classes including this module should call this in #initialize
+    #
+    # @return [void]
+    #
     def parse_ext_attrs
-
       unless @init_data[:extension_attributes]
         @extension_attributes = []
         @ext_attrs = {}
@@ -126,83 +104,79 @@ module JSS
       @extension_attributes.each do |ea|
         case ea[:type]
 
-          when "Date"
-            begin # if there's random non-date data, the parse will fail
-              ea[:value] = JSS.parse_datetime ea[:value]
-            rescue
-            end
+        when 'Date'
+          begin # if there's random non-date data, the parse will fail
+            ea[:value] = JSS.parse_datetime ea[:value]
+          rescue
+          end
 
-          when *NUMERIC_TYPES
-            ea[:value] = ea[:value].to_i unless ea[:value].to_s.empty?
+        when *NUMERIC_TYPES
+          ea[:value] = ea[:value].to_i unless ea[:value].to_s.empty?
         end # case
 
         @ext_attrs[ea[:name]] = ea[:value]
-
       end # each do ea
 
       # remember changes as they happen so
       # we only send changes back to the server.
       @changed_eas = []
-
     end
 
-    ###
-    ### Set the value of an extension attribute
-    ###
-    ### If the extension attribute is defined as a popup menu, the value must be one of the
-    ### defined popup choices.
-    ###
-    ### If the ext. attrib. is defined with a data type of Integer, the value must be an Integer.
-    ###
-    ### If the ext. attrib. is defined with a data type of Date, the value will be converted to a Time
-    ###
-    ### @param name[String] the name of the extension attribute to set
-    ###
-    ### @param value[String,Time,Time,Integer] the new value for the extension attribute for this user
-    ###
-    ### @return [void]
-    ###
+    # Set the value of an extension attribute
+    #
+    # If the extension attribute is defined as a popup menu, the value must be one of the
+    # defined popup choices, or an empty string
+    #
+    # If the ext. attrib. is defined with a data type of Integer, the value must be an Integer.
+    #
+    # If the ext. attrib. is defined with a data type of Date, the value will be converted to a Time
+    #
+    # Note that while the Jamf Pro Web interface does not allow editing the values of
+    # Extension Attributes populated by Scripts or LDAP,  the API does allow it.
+    # Bear in mind however that those values will be reset again at the next recon.
+    #
+    # @param name[String] the name of the extension attribute to set
+    #
+    # @param value[String,Time,Time,Integer] the new value for the extension attribute for this user
+    #
+    # @return [void]
+    #
     def set_ext_attr(name, value)
-
       # if we don't currently have any need to update(cuz we have recently), reset the list of changes to push
       @changed_eas = [] unless @need_to_update
 
       # this will raise an exception if the name doesn't exist
-      ea_def = self.class::EXT_ATTRIB_CLASS.new :name => name
+      ea_def = self.class::EXT_ATTRIB_CLASS.new name: name
 
-      unless JSS::ExtensionAttribute::EDITABLE_INPUT_TYPES.include? ea_def.input_type
-        raise JSS::UnsupportedError, "The value for #{name} cannot be modified. It is gathered during inventory updates."
-      end
-
-      if ea_def.input_type == "Pop-up Menu" and (not ea_def.popup_choices.include? value.to_s)
+      if ea_def.input_type == 'Pop-up Menu' && (!ea_def.popup_choices.include? value.to_s)
         raise JSS::UnsupportedError, "The value for #{name} must be one of: '#{ea_def.popup_choices.join("' '")}'"
       end
 
-      case ea_def.data_type
-        when "Date"
-
+      unless value == JSS::BLANK
+        case ea_def.data_type
+        when 'Date'
           value = JSS.parse_datetime value
 
         when *NUMERIC_TYPES
-          raise  JSS::InvalidDataError, "The value for #{name} must be an integer" unless value.kind_of? Integer
+          raise JSS::InvalidDataError, "The value for #{name} must be an integer" unless value.is_a? Integer
 
-      end #case
+        end # case
+      end # unless blank
 
       @extension_attributes.each do |ea|
         ea[:value] = value if ea[:name] == name
       end
+
       @ext_attrs[name] = value
       @changed_eas << name
       @need_to_update = true
-
     end
 
-    ###
-    ### @api private
-    ###
-    ### @return [REXML::Element] An <extension_attribute> element to be
-    ###  included in the rest_xml of objects that mix-in this module.
-    ###
+    # @api private
+    #
+    # @return [REXML::Element] An <extension_attribute> element to be
+    #  included in the rest_xml of objects that mix-in this module.
+    #
     def ext_attr_xml
       @changed_eas ||= []
       eaxml = REXML::Element.new('extension_attributes')
@@ -211,7 +185,7 @@ module JSS
         ea_el = eaxml.add_element('extension_attribute')
         ea_el.add_element('name').text = ea[:name]
 
-        if ea[:type] == "Date"
+        if ea[:type] == 'Date'
           begin
             ea_el.add_element('value').text = ea[:value].to_jss_date
           rescue
@@ -222,8 +196,9 @@ module JSS
         end # if
       end # each do ea
 
-      return eaxml
+      eaxml
     end
 
   end # module Purchasable
+
 end # module JSS