ruby-jss 1.2.4a3 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab1b92079de4a03997ab5fb60cf3463b63b7560cd45e83122ef52b563dec511
-  data.tar.gz: bedaefb57524c8d8abc820f5078d4a4db005436c71b214818e7f1ca3f2acebaf
+  metadata.gz: fa838d9a9f35421383049454edc0add9cac32ce63adffdeeaa968b82a7553ab3
+  data.tar.gz: c26dd00287dbafb8cf573d0a610183e6110032cd5e0726d07290096861330fc8
 SHA512:
-  metadata.gz: dab434c14f91b160305f25bc8284a3e8731ae6edb842e9e600b667b46f53e126fc7a62e89c3875235a156d0b4b5628d143798e539ef196143d8d963bddb9fd1c
-  data.tar.gz: b5ec8b9709cc9d9b32d4b609a39452d2e7d21b425db3fc36ba3140c5b111d7da084c1969ae27d8d96785cd2e958e5c6f803f7624b4d76fdc077149c249c423bb
+  metadata.gz: 17dbb8ba3b2da2d781b9218eb8491f7f6c627e8ed97a275589be3e62a57bd2cbab572af4f3621611c03c10f430312256fdb6faab14dbb61a5ba7e60076caebfa
+  data.tar.gz: 93c6c8bd3c8db99e7de2f40f3234cfeb83a0a517495251bbf99b60f597ef3a6b7b59cbd6ca4997d35b7a1a07a9fdcf3c42b367da28797d44b08467060f4ce6cc

data/CHANGES.md

@@ -4,6 +4,184 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## \[1.3.2] - 2020-07-31
+Many thanks to @cybertunnel for adding a huge amount of code to get JSS::Policy fully implimented, as well as other fixes and updates!
+
+### Added
+  - new class JSS::DockItem
+  - new classes JSS::DirectoryBinding and JSS::DirectoryBindingType
+  - new class JSS::Printer
+  - new class JSS::DiskEncryptionConfiguration
+  - JSS::Policy:
+    - getters and setters for `#user_message_start` and `#user_message_end`
+    - `#set_management_account` and `#verify_management_password`
+    - `#add_dock_item` and `#remove_dock_item`
+    - `#directory_bindings`, `#add_directory_binding` and `#remove_directory_binding`
+    - `#add_printer` and `#remove_printer`
+    - `#reissue_key`, `#apply_encryption_configuration`, and `#remove_encryption_configuration`
+
+
+### Changed
+  - JSS::Package:
+    - no longer issues a warning when changing the file_name of a package
+    - Updated the CPU type string from 'x86' to 'Intel/x86'
+    - Methods which used to always use the master distribution point now accept a parameter `dist_point: dp` where dp is the name or id of a fileshare distribution point. If not specified, it still defaults to the Master Distribution Point.  This is needed because if the Cloud Distribution Point is the master, there is no access to it via the Classic API, and any use of DistributionPoint.master_distribution_point will raise an error.
+
+## \[1.3.1] - 2020-06-21
+
+### Changed
+
+  - JSS::MobileDeviceApplication when using PrettyPrint (pp) in irb, no longer shows the base64 data for the ipa file.
+
+  - JSS::DistributionPoint.my_distribution_point and .master_distribution_point now have options for dealing with the Cloud Distribution Point (which is not available in the classic API) being the master.
+
+### Fixed
+
+  - JSS::NetworkSegment.distribution_point=  now takes nil or an empty string to unset the dist point.
+
+## \[1.3.0] - 2020-06-05
+
+### Added
+
+  - JSS::NetworkSegment.network_ranges_as_integers method, Similar to NetworkSegment.network_ranges, but the ranges are of Integers, not IPAddr instances. This makes for *MUCH* faster range calculations, needed to implement improvements to NetworkSegment.network_segment_for_ip
+
+  - JSS::Package.all_filenames_by, returns a Hash of all distribution point filenames for all packages, keyed by either the package id, or the package name. NOTE: as with JSS::Package.all_filenames, this method must instantiate all JSS::Package objects, so it will be slow.
+
+### Changed
+
+  - JSS.expand_min_os now expands to macOS 10.30.x, which should hold us for a while
+
+  - JSS::NetworkSegment.network_segment_for_ip and .my_network_segment are no longer deprecated, but now return an integer NetSeg id (or nil). The plural forms of those methods still return an Array of ids for all the matching network segments.
+
+  - The logic for JSS::NetworkSegment.network_segment_for_ip (and .my_network_segment) now matches how the Jamf server does it:  when you IP address is in more than one Network Segment, Jamf uses the smallest/narrowest one (the one containing fewest IP addresses). If more than one of your Network Segments are that same width, the one with the lowest starting IP address is used.
+
+  - In some networking situations (e.g. Split-tunnel VPN with multiple active network ports) the JSS::APIObject.delete method will raise a 404 NotFound error, seemingly because the object was already deleted but a second http DELETE is sent (I think). We now just rescue and ignore that error, since the fact that it's not found means it was indeed deleted.
+
+### Fixed
+
+  - A copy/paste bug in Jamf::Prestage.serials_for_prestage
+
+## \[1.2.15] - 2020-04-30
+
+### Fixed
+
+  - USER_CONF_FILE is always a pathname, never nil
+
+  - issues with Array#j_ci_* methods related to removing safe navigation
+
+## \[1.2.13] - 2020-04-29
+
+### Fixed
+
+  - Ruby 2.6 needs parens in more places than 2.3, apparently
+
+## \[1.2.12] - 2020-04-29
+
+### Added
+
+  - Backport of `#dig` for Arrays, Hashes and OpenStructs, for compatibiliy with older rubiesd (for a while longer anyway). Gratefully borrowed from https://github.com/Invoca/ruby_dig
+
+### Changed
+
+  - Removed all safe navigation operators (`&.`) for compatibility with older rubies (for a while longer anyway)
+
+
+## \[1.2.11] - 2020-04-26
+
+### Fixed
+
+  - Bug in Package#install that prevented installs from 'alt_download_url'.
+
+## \[1.2.10] - 2020-04-25
+
+### Added
+
+  - Computer#reported_ip_address. This value is collected in newer versions of Jamf Pro. While the #ip_address is the client's IP address from the Jamf Server's perspective, the #reported_ip_address is the IP from the client's perspective, which may be different on a NATted network like a home network.
+
+### Fixed
+
+  - MobileDevice#upload now works like Computer#upload
+
+### Changed
+
+  - Validation of Ext. Attribute values is improved, namely for EAs with integer values, integer-strings like "12" are accepted and converted to real integers as needed.
+
+## \[1.2.9] - 2020-04-13
+
+### Fixed
+
+  - Fixed a bug where passing a frozen string into some setters, e.g. `JSS::Computer.asset_tag=`, would cause an error when it tried to `#strip!` the string.
+
+## \[1.2.8] - 2020-04-12
+
+### Added
+
+  - MobileDevice#update now takes the `no_mdm_rename:` boolean parameter. Prevents an MDM rename command being sent when changing the name of a supervised device with enforced names. Useful when the MDM command fails, as when there's already a pending rename command.
+
+  - `String#jss_float?` and `String#j_float?` predicate methods.
+
+### Changed
+
+  - Jamf Pro API endpoints that have paging options have an undocumented max page size of 2000. The `CollectionResource#all*` methods now account for this.
+
+  - `String#jss_integer?` and `String#j_integer?` now recognize negative integers
+
+  - Ext. Attributes defined to have interger values will now accept integer strings, e.g. `'12345'`  as well as integers e.g. `12345`
+
+  - Ext. Attributes defined to have date values will once again accept blanks (i.e. empty strings)
+
+## \[1.2.7] - 2020-04-01
+
+### Changed
+
+  - Jamf Pro API endpoints that have paging options have an undocumented max page size of 2000. The `CollectionResource#all*` methods now account for this.
+
+
+## \[1.2.6] - 2020-04-01
+
+### Fixed
+
+- Classic API (JSS module)
+  - Sitable objects now recognize the string "None" as meaning no site is assigned. Thanks @cybertunnel for this fix!
+
+  - Scopable::Scope now deals with some bugs in the API regarding Jamf & LDAP users & user groups in targets, limitations, & exclusions. Please see the documentation/comments for the class in the file or the online documentation. Thanks @cybertunnel again!
+
+  - Criteriable::Criteria can now be empty - containing no criterion objects. When criteriable objects are created (such as Advanced Searches) the default JSS::Criteriable::Criteria object has no criteria.  To remove all criteria, use `criteria.clear`, `criteria = nil`, or `criteria = JSS::Criteriable::Criteria.new` and then save. Once again, thanks to @cybertunnel for finding this.
+
+- Jamf Pro API (Jamf module)
+  - More fixes for various JamfPro API (Jamf module) methods that accept a passed-in Jamf::Connection instance.
+
+
+## \[1.2.5] - 2020-03-30
+
+### Fixed
+
+- Classic API (JSS module)
+  - The Classic API now requires JSS::User objects to be passed back to the API with the `ldap_server` specified by id, name-only won't work.
+
+- Jamf Pro API (Jamf module)
+  - Fixes for various JamfPro API (Jamf module) methods that accept a passed-in Jamf::Connection instance.
+
+## \[1.2.4] - 2020-03-16
+
+### Added
+
+- **'Beta' Jamf Pro API support in ruby-jss!**
+
+The Jamf Pro API, formerly known as the 'Universal' API, aims to be a far more robust, modern, and standardized way to programmatically access a Jamf Pro server.  While its been in development for a while, it is finally starting to settle in to some standards, to the point that its worth releasing some early ruby-jss code to access it.
+
+Because the JP-API is so fundamentally different from the Classic API, it's being implemented as a totally separate ruby module 'Jamf', and many of the underlying standards of ruby-jss's JSS module are being re-thought and modernized, much like the JP-API itself. Classic API access using the JSS module is unchanged, and will continue to get fixes and other updates as needed. However many things in the Jamf module will behave differently from the JSS module, at least in detail if not concept.
+
+For requirements and details of using the Jamf module to access the Jamf Pro API, see [lib/jamf/README-JP-API.md](lib/jamf/README-JP-API.md).
+
+**IMPORTANT:** As with the JP-API, The Jamf module is an early work-in-progress, and things might change drastically at any point. Please mention 'ruby-jss' in MacAdmins Slack channels #jamf-api or #ruby, or email ruby-jss@pixar.com, or open an issue on github if you have questions or want to contribute.
+
+### Changed
+
+- The `last_mdm_contact` class and instance method from the MDM mixin module (as used in Computer and MobileDevice classes) now returns the time of the most recent _completed_ or _failed_ mdm command. This is more accurate than just the completed commands, since a failed command still implies contact between the client and Jamf Pro.
+
+- JSS::MobileDevice instances now have three predicate methods: `tv?` (aliased as `apple_tv?`), `ipad?` and `iphone?`
+
 ## \[1.2.3] - 2019-10-31
 ### Added
 - the ManagementHistory mixin module used by the Computer and MobileDevice classes, now has a `last_mdm_contact` class and instance method, which returns a Time object for the timestamp of the most recent completed MDM command. This is useful for MobileDevices, which don't have anything like the `last_checkin` value for comptuers, indicating real communication between the device and Jamf Pro.
@@ -11,7 +189,8 @@ Note that the `last_inventory_update` value does NOT indicate such communication
 
 - All APIObject Subclasses (Policy, Computer, MobileDevice, ComputerGroup, etc..) now have `get_raw`, `post_raw` & `put_raw` class methods, which are simpler wrappers for APIConnection#get_rsrc, #post_rsrc, and #put_rsrc.
   - `get_raw`  takes an object's id, and returns the 'raw' JSON (parsed into a ruby Hash with symbolized keys) or a REXML::Document (from which you'll probably want to use the `root` element). If you pass `as_string: true` you'll get the un-parsed JSON or XML string directly from the API
-  This can be useful when you need to retrieve the full object, to get some data not available in the summary-list, but instantiating the full ruby class is too slow.
+  This can be useful when you need to retrieve the full object, to get some data not available in the summary-list, but instantiating the full ruby class is too slow
+
   - `post_raw` & `put_raw` can send raw XML to the API without instantiating objects. In some cases, where you're making simple changes to simple XML, this can be faster than fetching a full instance and the re-saving it.
   WARNING You must create or acquire the XML to be sent, and no validation will be performed on it. It must be a String of XML, or something that returns such a string with #to_s, such as a REXML::Document, or a REXML::Element.
 

data/README.md

@@ -45,6 +45,8 @@ Hopefully others will find it useful, and add more to it as well.
 
 [Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
 
+NOTE: ruby-jss 1.2.4 will introduce beta-level support for the Jamf Pro API in a ruby module called 'Jamf', See  README-JP-API.md in /lib/jamf, or in the 'Files' section of the YARD docs file for details.
+
 ## SYNOPSIS
 
 Here are some simple examples of using ruby-jss
@@ -346,7 +348,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.
 
@@ -417,6 +419,6 @@ There's a [wiki on the github page](https://github.com/PixarAnimationStudios/rub
 
 ## LICENSE
 
-Copyright 2019 Pixar
+Copyright 2020 Pixar
 
 Licensed under the Apache License, Version 2.0 (the "Apache License") with modifications. See LICENSE.txt for details

data/bin/cgrouper

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/bin/jamfHelperBackgrounder

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/bin/netseg-update

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/data/ruby-jss.conf.example

@@ -1,4 +1,4 @@
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jamf.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -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/advanced_search.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")

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

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -100,15 +100,27 @@ 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
 
-      raw = cnx.get rsrc_path
-      cnx.collection_cache[self] =
-        if raw.is_a?(Hash) && raw[:results]
-          raw[:results]
-        else
-          raw
-        end
+        return cnx.collection_cache[self].map { |m| new m }
+      end
+
+      # TODO:  make sure all collection resources use this format
+      # for paging. Also -ask Jamf about a  url that returns
+      # ALL objects in one query, regardless of number.
+      page = 0
+      raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
+      results = raw[:results]
+
+      until results.size >= raw[:totalCount]
+        page += 1
+        raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
+        results += raw[:results]
+      end
+
+
+      cnx.collection_cache[self] = results
 
       return cnx.collection_cache[self] unless instantiate
 
@@ -135,9 +147,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 +159,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 +180,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.
     #
-    # If you know the value is a certain identifier, e.g. a serial_number
-    # then you can specify the identifier, for a faster search:
+    # Return nil if there's no match for the given value.
     #
-    #   valid_id serial_number: 'AB12DE34' # => Int or nil
+    # 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 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 +207,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)
@@ -209,7 +228,7 @@ module Jamf
       val_is_str = value.is_a? String
 
       idents.each do |ident|
-        match = all(cnx: cnx).select do |m|
+        match = all(refresh, cnx: cnx).select do |m|
           val_is_str ? m[ident].to_s.casecmp?(value) : m[ident] == value
         end.first
         return match[:id] if match
@@ -230,13 +249,20 @@ module Jamf
     end
 
     # Make a new thing to be added to the API
-    def self.create(params, cnx: Jamf.cnx)
-      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless self.creatable?
-
+    def self.create(**params)
       validate_not_abstract
+      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless creatable?
+
+      cnx = params.delete :cnx
+      cnx ||= Jamf.cnx
+
       params.delete :id # no such animal when .creating
 
-      validate_create_params(params, cnx)
+      params.keys.each do |param|
+        raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
+
+        params[param] = validate_attr param, params[param], cnx: cnx
+      end
 
       params[:creating_from_create] = true
       new params, cnx: cnx
@@ -266,16 +292,17 @@ module Jamf
     #
     def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
       validate_not_abstract
+
       id =
         if ident_value == :random
           all_ids.sample
         elsif ident_value
-          valid_id ident_value
+          valid_id ident_value, cnx: cnx
         elsif ident_hash.empty?
           nil
         else
           ident, lookup_value = ident_hash.first
-          valid_id ident => lookup_value
+          valid_id ident => lookup_value, cnx: cnx
         end
 
       raise Jamf::NoSuchItemError, "No matching #{self}" unless id
@@ -351,17 +378,6 @@ module Jamf
     end # create_list_methods
     private_class_method :create_list_methods
 
-    # validate that our .create data is OK
-    #
-    def self.validate_create_params(params, cnx)
-      params.keys.each do |param|
-        raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
-
-        params[param] = validate_attr param, params[param], cnx: cnx
-      end
-    end
-    private_class_method :validate_create_params
-
     # Given an indentier attr. key, and a value,
     # return the id where that ident has that value, or nil
     #
@@ -375,7 +391,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