ruby-jss 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 27e1e01930e47278eee17c14081df08c2539ff96
-  data.tar.gz: 47d512909b8cd7ef896df540dc522961bb0f8547
+  metadata.gz: 0fd7571a4225c7255724e6de59c0fb44e6bd595b
+  data.tar.gz: fb5de557c051ae61c7993db97590195b76fa6a30
 SHA512:
-  metadata.gz: 7e8e425f0f20337f85c915e1cc9ac8526325bc2b031f78575985de81ae4573b35fdb2b1aeefd2e2b869e594b0df0238f298693e9ac31aaa9dcca34d22c9e9290
-  data.tar.gz: 854d85d68651dbaf22becbb6b14be2cb3734eb1943b7e1c375fbad2caa19300134490d70673660a380021848021d61ea6ad4645947145d23af4876bb46a8aca6
+  metadata.gz: f8ca00b8718f58bad9529b5742964c8c0c19dcfb145ed97ad30e4b2c9b9ff69fcab44fa09fe32207671c56bafd181e0c3d10d1dbcba30f599b11471ba8a4002a
+  data.tar.gz: 8ee7f5f01cf030dd356210e52f69b5cbcc0e231736412b0678755f6fc2ddc667d7bf47bb4c1694e8b70fa6eb234b3e41bc00a2fd2b92a7128a83396d0a65b79c

data/CHANGES.md

@@ -1,5 +1,25 @@
 # Change History
 
+## v 0.12.0, 2018-04-16
+
+- Simplification: when building .pkg's with JSS::Composer.mk_pkg, only two params are related to Package Signing: 'signing_identity:' the name of the signing identity to use, and and 'signing_options:' a string of all other signing-related CLI options that will be passed to the pkgbuild command, e.g. keychain locations, timestamps, certs, etc. For details, see `man pkgbuild`
+
+- Improvement: Now augmenting ruby Hashes with an embeded 'recursive-open-struct' version of themselves. This simplifies accessing values from deeply-nested Hash structures, e.g. JSS::Computer#hardware instead of `computer_instance.hardware[:storage].first[:partition][:percentage_full]` you can do `computer_instance.hardware.jss_ros.storage.first.partition.percentage_full`.  See http://www.rubydoc.info/gems/ruby-jss/Hash for details. Uses the [recursive-open-struct gem](https://github.com/aetherknight/recursive-open-struct).
+
+- Add: The computerapplications/application endpoint is now implemented as the JSS::Computer.application_installs class method so you can query lists of computers that have certain apps installed.
+
+- Improvement: the JSS::Computer class is now defined in multiple files.  The single computer.rb file was getting far to unwieldy.
+
+- Fix: Setting the first icon of a newly-created JSS::Policy now works. Thanks @christopher.kemp for reporting this one
+
+- Add: JSS::MobileDeviceConfigurationProfile is now more fleshed-out and is Updatable.
+
+- Improvement: JSS::MobileDeviceConfigurationProfile and JSS::OSXConfigurationProfile now share an abstract parent class, JSS::ConfigurationProfile, containing common code.
+
+- Fix: the SelfServable module was mis-handling 'user-removability' data for config profiles.
+
+- Fix: Typo and missing method alias, caught by csfjeff @ github, issue #23
+
 ## v 0.11.0, 2018-03-12
 
 - Fix: NoMethod error when saving JSS::Policy was due to a typo in a method call.
@@ -7,7 +27,7 @@
 - Fix: Initialization of Creatable objects using certain mixins (Extendable, Sitable, Categorizable) either failed, or errored when trying to set their values. Now fixed. Thanks @mylescarrick for reporting this one.
 
 - Improvement: Updated general attributes for computers and mobile devices
-
+s
 - Improvement: Computers and MobileDevices are now Creatable. Use the .make class method to create an unsaved instance, then .create/.save instance method to create the JSS record. Note: Mobile Devices need both a unique serial number and unique udid to be accepted by the API.
 
 - Improvement: Handling of 'site' data is now done via the JSS::Sitable mixin module

data/lib/jss.rb

@@ -53,13 +53,14 @@ module JSS
   require 'yaml'
   require 'open3'
   require 'English'
+  require 'json'
 
   ###################
   ### Gems
   require 'rest-client'
-  require 'json'
   require 'plist'
   require 'immutable-struct'
+  require 'recursive-open-struct'
 
   ### Constants
   #####################################
@@ -100,8 +101,6 @@ module JSS
 
   module Composer; end
 
-
-
   ### Mix-in Sub Modules with Classes
 
   module Criteriable
@@ -117,11 +116,12 @@ module JSS
 
   class APIObject; end
   class APIConnection; end
-  class Client; end
   class DBConnection; end
   class Server; end
   class Icon; end
   class Preferences; end
+  class Client; end
+
 
   ### SubClasses
   #####################################
@@ -143,6 +143,10 @@ module JSS
   class MobileDeviceGroup < JSS::Group; end
   class UserGroup < JSS::Group; end
 
+  class ConfigurationProfile < JSS::APIObject; end
+  class OSXConfigurationProfile < JSS::ConfigurationProfile; end
+  class MobileDeviceConfigurationProfile < JSS::ConfigurationProfile; end
+
   ### APIObject Classes without SubClasses
 
   class Account < JSS::APIObject; end
@@ -155,11 +159,9 @@ module JSS
   class LDAPServer < JSS::APIObject; end
   class MacApplication < JSS::APIObject; end
   class MobileDevice < JSS::APIObject; end
-  class MobileDeviceConfigurationProfile < JSS::APIObject; end
   class MobileDeviceApplication < JSS::APIObject; end
   class NetBootServer < JSS::APIObject; end
   class NetworkSegment < JSS::APIObject; end
-  class OSXConfigurationProfile < JSS::APIObject; end
   class Package < JSS::APIObject; end
   class Patch < JSS::APIObject; end
   class PatchPolicy < JSS::APIObject; end

data/lib/jss/api_object.rb

@@ -1142,6 +1142,7 @@ require 'jss/api_object/scopable'
 
 ### APIObject SubClasses with SubClasses
 require 'jss/api_object/advanced_search'
+require 'jss/api_object/configuration_profile'
 require 'jss/api_object/extension_attribute'
 require 'jss/api_object/group'
 
@@ -1158,10 +1159,8 @@ require 'jss/api_object/ldap_server'
 require 'jss/api_object/mac_application'
 require 'jss/api_object/mobile_device'
 require 'jss/api_object/mobile_device_application'
-require 'jss/api_object/mobile_device_configuration_profile'
 require 'jss/api_object/netboot_server'
 require 'jss/api_object/network_segment'
-require 'jss/api_object/osx_configuration_profile'
 require 'jss/api_object/package'
 require 'jss/api_object/patch'
 require 'jss/api_object/patch_policy'

data/lib/jss/api_object/computer.rb

@@ -482,7 +482,7 @@ module JSS
     # A subset of management data for a given computer.
     # This private method is called by self.management_data, q.v.
     #
-    def self.management_data_subset(id, subset: nil, only: nil,  api: JSS.api)
+    def self.management_data_subset(id, subset: nil, only: nil, api: JSS.api)
       raise "Subset must be one of :#{MGMT_DATA_SUBSETS.join ', :'}" unless MGMT_DATA_SUBSETS.include? subset
       subset_rsrc = MGMT_DATA_RSRC + "/id/#{id}/subset/#{subset}"
       subset_data = api.get_rsrc(subset_rsrc)[MGMT_DATA_KEY]
@@ -497,7 +497,6 @@ module JSS
     # identifiers
     ################
 
-
     # @return [String] the secondary mac address
     attr_reader :alt_mac_address
 
@@ -505,7 +504,7 @@ module JSS
     attr_reader :asset_tag
 
     # @return [String] the barcodes
-    attr_reader :barcode_1, :barcode_2
+    attr_reader :barcode1, :barcode2
 
     # @return [String] The name of the distribution point for this computer
     attr_reader :distribution_point
@@ -736,10 +735,19 @@ module JSS
     def initialize(args = {})
       super args
       if @in_jss
+
+        # mutable stuff
         @alt_mac_address = @init_data[:general][:alt_mac_address]
         @asset_tag = @init_data[:general][:asset_tag]
-        @barcode_1 = @init_data[:general][:barcode_1]
-        @barcode_2 = @init_data[:general][:barcode_2]
+        @barcode1 = @init_data[:general][:barcode_1]
+        @barcode2 = @init_data[:general][:barcode_2]
+        @mac_address = @init_data[:general][:mac_address]
+        @managed = @init_data[:general][:remote_management][:managed]
+        @management_username = @init_data[:general][:remote_management][:management_username]
+        @serial_number = @init_data[:general][:serial_number]
+        @udid = @init_data[:general][:udid]
+
+        # immutable single-values
         @distribution_point = @init_data[:general][:distribution_point]
         @initial_entry_date = JSS.epoch_to_time @init_data[:general][:initial_entry_date_epoch]
         @last_enrolled = JSS.epoch_to_time @init_data[:general][:last_enrolled_date_epoch]
@@ -747,18 +755,12 @@ module JSS
         @itunes_store_account_is_active = @init_data[:general][:itunes_store_account_is_active]
         @jamf_version = @init_data[:general][:jamf_version]
         @last_contact_time = JSS.epoch_to_time @init_data[:general][:last_contact_time_epoch]
-        @mac_address = @init_data[:general][:mac_address]
-        @managed = @init_data[:general][:remote_management][:managed]
-        @management_username = @init_data[:general][:remote_management][:management_username]
         @mdm_capable = @init_data[:general][:mdm_capable]
         @mdm_capable_users = @init_data[:general][:mdm_capable_users].values
         @netboot_server = @init_data[:general][:netboot_server]
         @platform = @init_data[:general][:platform]
         @report_date = JSS.epoch_to_time @init_data[:general][:report_date_epoch]
-        @serial_number = @init_data[:general][:serial_number]
-        @site = JSS::APIObject.get_name(@init_data[:general][:site])
         @sus = @init_data[:general][:sus]
-        @udid = @init_data[:general][:udid]
 
         @configuration_profiles = @init_data[:configuration_profiles]
         @certificates = @init_data[:certificates]
@@ -767,6 +769,16 @@ module JSS
         @peripherals = @init_data[:peripherals]
         @software = @init_data[:software]
 
+        # Freeze immutable things.
+        # These are updated via recon, and aren't sent
+        # with #update, so changing them here is meaningless anyway.
+        @configuration_profiles.freeze
+        @certificates.freeze
+        @groups_accounts.freeze
+        @hardware.freeze
+        @peripherals.freeze
+        @software.freeze
+
         @management_password = nil
       else
         @udid = args[:udid]
@@ -774,8 +786,8 @@ module JSS
         @asset_tag = args[:asset_tag]
         @mac_address = args[:mac_address]
         @alt_mac_address = args[:alt_mac_address]
-        @barcode_1 = args[:barcode_1]
-        @barcode_2 = args[:barcode_2]
+        @barcode1 = args[:barcode_1]
+        @barcode2 = args[:barcode_2]
       end
     end # initialize
 
@@ -953,18 +965,18 @@ module JSS
     end
 
     #
-    def barcode_1=(new_val)
-      return nil if @barcode_1 == new_val
+    def barcode1=(new_val)
+      return nil if @barcode1 == new_val
       new_val.strip!
-      @barcode_1 = new_val
+      @barcode1 = new_val
       @need_to_update = true
     end
 
     #
-    def barcode_2=(new_val)
-      return nil if @barcode_2 == new_val
+    def barcode2=(new_val)
+      return nil if @barcode2 == new_val
       new_val.strip!
-      @barcode_2 = new_val
+      @barcode2 = new_val
       @need_to_update = true
     end
 
@@ -1021,8 +1033,8 @@ module JSS
       super
       @alt_mac_address = nil
       @asset_tag = nil
-      @barcode_1 = nil
-      @barcode_2 = nil
+      @barcode1 = nil
+      @barcode2 = nil
       @distribution_point = nil
       @initial_entry_date = nil
       @ip_address = nil
@@ -1060,8 +1072,14 @@ module JSS
 
     # aliases
     alias alt_macaddress alt_mac_address
-    alias bar_code_1 barcode_1
-    alias bar_code_2 barcode_2
+    alias bar_code_1 barcode1
+    alias bar_code_2 barcode2
+    alias barcode_1 barcode1
+    alias barcode_2 barcode2
+    alias bar_code_1= barcode1=
+    alias bar_code_2= barcode2=
+    alias barcode_1= barcode1=
+    alias barcode_2= barcode2=
     alias managed? managed
     alias mdm? mdm_capable
     alias last_recon report_date
@@ -1090,8 +1108,8 @@ module JSS
       general.add_element('name').text = @name
       general.add_element('alt_mac_address').text = @alt_mac_address
       general.add_element('asset_tag').text = @asset_tag
-      general.add_element('barcode_1').text = @barcode_1
-      general.add_element('barcode_2').text = @barcode_2
+      general.add_element('barcode_1').text = @barcode1
+      general.add_element('barcode_2').text = @barcode2
       general.add_element('ip_address').text = @ip_address
       general.add_element('mac_address').text = @mac_address
       general.add_element('udid').text = @udid
@@ -1116,3 +1134,5 @@ module JSS
   end # class Computer
 
 end # module
+
+require 'jss/api_object/computer/application_installs'

data/lib/jss/api_object/computer/application_installs.rb

@@ -0,0 +1,119 @@
+# Copyright 2018 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
+
+  # This file implements the 'computerapplications' API endpoint, used
+  # for searching for computers with certain applications installed.
+  #
+  # All the methods defined here are class methods on JSS::Computer
+  # since they all return lists of computers and apps.
+  #
+  # The apps installed on a JSS::Computer instance are available via the
+  # #apps instance method (a shortcut that looks into the 'software' subset)
+  #
+
+  #
+  class Computer < JSS::APIObject
+
+    COMPUTER_APPLICATIONS_RSRC = 'computerapplications/application'.freeze
+
+    # Query the JSS for computers with some app installed. An app name is required
+    # as the first parameter.
+    #
+    # If no other parameters are given, returns a Hash, one key per version of the
+    # app. For each version there is an array of Hashes, one Hash for each
+    # computer with that version. The sub hashes contain keys for the computer's
+    # identifiers, i.e. :name, :id, :udid, :serial_number, :mac_address.
+    #
+    # If one or more inventory fields are provided in the 'fields' parameter,
+    # each computer's hash also has keys and values for those fields if they
+    # exist in the JSS. These fields are those available in the display options
+    # for Advanced Computer Searches (including extention attribute names) and
+    # their names are case-sensitive, so 'Username', not 'username'
+    #
+    # If a specific version is provided in the 'version' parameter, only computers
+    # containing that version of the app are returned as an Array of Hashes.
+    #
+    # If the ids_only parameter is truthy, an Array of JSS id numbers for
+    # computers with this app is returned. In this case the 'fields' parameter
+    # is ignored, however the 'version' parameters is still valid and will
+    # restrict the list to those computer ids with that version installed.
+    #
+    # This method implements the 'computerapplications' API endpoint.
+    #
+    # NOTE: To see all the apps installed on a specific computer, fetch the
+    # JSS::Computer instance and call its {JSS::Computer#apps} method.
+    #
+    # @param appname [String] The name of the app to look for, e.g. 'Transmogrifier.app'
+    #
+    # @param fields [String,Array<String>] Additional 'inventory fields' to return
+    #    with each computer's data
+    #
+    # @param version [String] Limit search to a specific version of the app
+    #
+    # @param ids_only [Boolean] Just return an array of the id's of computers
+    #  found with this query. Defaults to false
+    #
+    # @param api [JSS::APIConnection] The API connection to use for the query.
+    #   default: JSS.api
+    #
+    # @return [Array<Integer>] When ids_only == true, the ids of computers with
+    #   the app installed (possibly limited to version)
+    #
+    # @return [Array<Hash>] When version is provided, An Array of Hashes, one
+    #   for each computer, with keys for identifiers plus any requested fields.
+    #
+    # @return [Hash{String => Array<Hash>}] When no version is provided, a Hash
+    #   with keys for each version, pointing to an array of Hashes, one for
+    #   each computer with that version. Each computer's Hash has keys for
+    #   identifiers plus any requested fields.
+    #
+    #
+    def self.application_installs(appname, fields: [], version: nil, ids_only: false, api: JSS.api)
+      fields = [fields] unless fields.is_a? Array
+
+      rsrc = "#{COMPUTER_APPLICATIONS_RSRC}/#{appname}"
+      rsrc << "/version/#{version}" if version
+      rsrc << "/inventory/#{fields.join ','}" unless ids_only || fields.empty?
+
+      # get_rsrc will URI.encode the rsrc
+      result = api.get_rsrc(rsrc)[:computer_applications]
+
+      return result[:unique_computers].map { |c| c[:id] } if ids_only
+
+      if version.nil?
+        hash_by_version = {}
+        result[:versions].each { |v| hash_by_version[v[:number]] = v[:computers] }
+        return hash_by_version
+      end
+
+      result[:versions].first[:computers]
+    end # self.application_search
+
+  end # Computer
+
+end # JSS

data/lib/jss/api_object/{osx_configuration_profile.rb → configuration_profile.rb}

@@ -29,17 +29,18 @@ module JSS
   # Classes
   ###################################
 
-  # An OS X Configuration Profile in the JSS.
+  # The parent class of OSXConfigurationProfile and MobileDeviceConfigurationProfile
   #
   # Note that the profile payloads and the profile UUID cannot be edited or updated with this via this class.
   # Use the web UI.
   #
   # @see JSS::APIObject
   #
-  class OSXConfigurationProfile < JSS::APIObject
+  class ConfigurationProfile < JSS::APIObject
 
     # Mix-Ins
     ###################################
+
     include JSS::Updatable
     include JSS::Scopable
     include JSS::SelfServable
@@ -49,40 +50,14 @@ module JSS
     # Class Constants
     ###################################
 
-    # The base for REST resources of this class
-    RSRC_BASE = 'osxconfigurationprofiles'.freeze
-
-    # the hash key used for the JSON list output of all objects in the JSS
-    RSRC_LIST_KEY = :os_x_configuration_profiles
-
-    # The hash key used for the JSON object output.
-    # It's also used in various error messages
-    RSRC_OBJECT_KEY = :os_x_configuration_profile
-
-    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = %i[distribution_method scope redeploy_on_update].freeze
-
-    # Our scopes deal with computers
-    SCOPE_TARGET_KEY = :computers
-
-    # Our SelfService happens on OSX
-    SELF_SERVICE_TARGET = :osx
-
-    # Our SelfService deploys profiles
-    SELF_SERVICE_PAYLOAD = :profile
-
-    # The possible values for the :distribution_method
+    # The possible values for the distribution_method/deployment_method
     DISTRIBUTION_METHODS = ['Install Automatically', 'Make Available in Self Service'].freeze
 
+    # which DISTRIBUTION_METHODS means we're in self service?
     SELF_SERVICE_DIST_METHOD = 'Make Available in Self Service'.freeze
 
-    # The possible values for :level
-    LEVELS = %w[user computer].freeze
-
-    # the object type for this object in
-    # the object history table.
-    # See {APIObject#add_object_history_entry}
-    OBJECT_HISTORY_OBJECT_TYPE = 4
+    # Our SelfService deploys profiles
+    SELF_SERVICE_PAYLOAD = :profile
 
     # Where is the Site data in the API JSON?
     SITE_SUBSET = :general
@@ -93,15 +68,6 @@ module JSS
     # @return [String] the description of this profile
     attr_reader :description
 
-    # @return [String] the distribution_method of this profile
-    attr_reader :distribution_method
-
-    # @return [Boolean] can the user remove this profile
-    attr_reader :user_removable
-
-    # @return [String] the level (user/computer) of this profile
-    attr_reader :level
-
     # @return [String] the uuid of this profile. NOT Updatable
     attr_reader :uuid
 
@@ -118,11 +84,7 @@ module JSS
     #
     def initialize(args = {})
       super
-
       @description = @main_subset[:description]
-      @distribution_method = @main_subset[:distribution_method]
-      @user_removable = @main_subset[:user_removable]
-      @level = @main_subset[:level]
       @uuid = @main_subset[:uuid]
       @redeploy_on_update = @main_subset[:redeploy_on_update]
       @payloads = @main_subset[:payloads]
@@ -141,50 +103,9 @@ module JSS
       @need_to_update = true
     end # @param new_val[String] how should this be distributed to clients?
 
+    # The @payloads Plist, parsed into a Ruby object
     #
-    # @return [void]
-    #
-    def distribution_method=(new_val)
-      return nil if @distribution_method == new_val
-      raise JSS::InvalidDataError, "New value must be one of '#{DISTRIBUTION_METHODS.join("' '")}'" unless DISTRIBUTION_METHODS.include? new_val
-      @distribution_method = new_val
-      @need_to_update = true
-    end
-
-    # @param new_val[Boolean] should the user be able to remove this?
-    #
-    # @return [void]
-    #
-    def user_removable=(new_val)
-      return nil if @self_service_feature_on_main_page == new_val
-      raise JSS::InvalidDataError, "Distribution method must be '#{SELF_SERVICE_DIST_METHOD}' to let the user remove it." unless in_self_service?
-      raise JSS::InvalidDataError, 'New value must be true or false' unless JSS::TRUE_FALSE.include? new_val
-      @user_removable = new_val
-      @need_to_update = true
-    end
-
-    # @param new_val[String] the new level for this profile (user/computer)
-    #
-    # @return [void]
-    #
-    def level=(new_val)
-      return nil if @level == new_val
-      raise JSS::InvalidDataError, "New value must be one of '#{LEVELS.join("' '")}'" unless LEVELS.include? new_val
-      @level = new_val
-      @need_to_update = true
-    end # @return [Boolean] is this profile available in Self Service?
-
-    #
-    def in_self_service?
-      @distribution_method == SELF_SERVICE_DIST_METHOD
-    end # @return [Boolean] is this profile removable by the user?
-
-    #
-    def user_removable?
-      @user_removable
-    end # @return [Hash] The payload plist parsed into a Ruby hash
-
-    #
+    # @return [Hash] the parsed payloads plist.
     def parsed_payloads
       Plist.parse_xml @payloads
     end
@@ -201,7 +122,6 @@ module JSS
       payload_content.map { |p| p['PayloadType'] }
     end
 
-    ###################################
     # Private Instance Methods
     ###################################
     private
@@ -209,21 +129,21 @@ module JSS
     def rest_xml
       doc = REXML::Document.new
 
-      obj = doc.add_element RSRC_OBJECT_KEY.to_s
+      obj = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
       gen = obj.add_element('general')
       gen.add_element('description').text = @description
-      gen.add_element('distribution_method').text = @distribution_method
-      gen.add_element('user_removable').text = @user_removable
-      gen.add_element('level').text = @level
       gen.add_element('redeploy_on_update').text = @redeploy_on_update
 
       obj << @scope.scope_xml
       add_self_service_xml doc
       add_category_to_xml doc
       add_site_to_xml doc
-      doc.to_s
+      doc
     end
 
   end # class OSXConfigurationProfile
 
 end # module
+
+require 'jss/api_object/configuration_profile/osx_configuration_profile'
+require 'jss/api_object/configuration_profile/mobile_device_configuration_profile'