ruby-jss 1.2.4a4 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 745114754cc7073bbf494e8eb54f48962c9cafff99da985108c90b5bc7ccc62c
-  data.tar.gz: 6455a7c53abc89c47a03b1bd9538bc0bd3375eab1776ca9c5a15425595ed2ed3
+  metadata.gz: ee61895968b4dc50815f33bdd50cd54c1a1fcad700243f4be3cded694c11f745
+  data.tar.gz: a7a3ce9847874fa7c26c859f6fa26e5a8802b60f42c300f347e2c40b5c38d949
 SHA512:
-  metadata.gz: 10cd851d966cc1e966dec194b27a4f282bba25b80177886dc03d44429206c8bc8bb223f141c9da27547f096a439937c6db3ae0d7e6498d2d6570b5bca164f716
-  data.tar.gz: a194cd0e76b6264afc1deef0b2567169a83c7fba9aaad796f050171783df202d1fd3ccf04f5eb11606ea387badce68920822c698aab819bfb46a2fd2549a919f
+  metadata.gz: f95b9d7f49983c9899a18b7e1edb6130250e402a5284e65a9ae64829176d2c3f5fe3d35584cf6dcee85b7486e1a037c8a5ae3ef58b72d169f4ac05cebb5d8858
+  data.tar.gz: 1b5131ec5bec8b940c4daf1403f9595a4749b0b5d36cfc7bf07a2aca0adbee2446ff44dfe078e8e1651f5fa25ed6725d763ec0f5798d06ec16d70b57ea466b86

data/CHANGES.md

@@ -4,6 +4,189 @@ 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.3] - 2020-08-07
+
+### Fixed
+  - Regression where JSS::Package#required_processor= wouldn't take 'x86'
+
+## \[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 +194,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
@@ -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")

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")
@@ -106,13 +106,21 @@ module Jamf
         return cnx.collection_cache[self].map { |m| new m }
       end
 
-      raw = cnx.get rsrc_path
-      cnx.collection_cache[self] =
-        if raw.is_a?(Hash) && raw[:results]
-          raw[:results]
-        else
-          raw
-        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
 
@@ -220,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
@@ -241,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
@@ -277,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
@@ -362,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
     #

data/lib/jamf/api/abstract_classes/generic_reference.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/json_object.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in
@@ -482,7 +482,7 @@ module Jamf
     # have an alias without the 'is' so :isManaged will have
     # getters isManaged? and managed?
     #
-    PREDICATE_RE = /^is([A-Z]\w*)$/.freeze
+    PREDICATE_RE = /^is([A-Z]\w+)$/.freeze
 
     # Public Class Methods
     #####################################
@@ -524,7 +524,7 @@ module Jamf
     #
     def self.attr_key_for_alias(als)
       validate_not_abstract
-      self::OBJECT_MODEL.each { |k, deets| return k if k == als || deets[:aliases]&.include?(als) }
+      self::OBJECT_MODEL.each { |k, deets| return k if k == als || deets[:aliases].to_a.include?(als) }
       nil
     end
 
@@ -575,10 +575,11 @@ module Jamf
       else
         define_method(attr_name) { instance_variable_get("@#{attr_name}") }
 
-        # all booleans get a predicate alias
-        alias_method("#{attr_name}?", attr_name) if attr_def[:class] == :boolean
       end
 
+      # all booleans get predicate aliases
+      define_predicates(attr_name) if attr_def[:class] == :boolean
+
       return unless attr_def[:aliases]
 
       # aliases
@@ -586,6 +587,15 @@ module Jamf
     end # create getters
     private_class_method :create_getters
 
+    # create the default aliases for booleans
+    ##############################
+    def self.define_predicates(attr_name)
+      alias_method("#{attr_name}?", attr_name)
+      return unless attr_name.to_s =~ PREDICATE_RE
+
+      alias_method("#{Regexp.last_match(1).downcase}?", attr_name)
+    end
+
     # create setter(s) for an attribute, and any aliases needed
     ##############################
     def self.create_setters(attr_name, attr_def)

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

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -235,7 +235,7 @@ module Jamf
     #
     def self.serials_for_prestage(prestage_ident, refresh = false, cnx: Jamf.cnx)
       id = valid_id prestage_ident, cnx: cnx
-      raise Jamf::NoSuchItemError, "No #{self} matching '#{ident}'" unless id
+      raise Jamf::NoSuchItemError, "No #{self} matching '#{prestage_ident}'" unless id
 
       serials_by_prestage_id(refresh, cnx: cnx).select { |_sn, psid| id == psid }.keys
     end