ruby-jss 1.2.6 → 1.4.1

data/lib/jss/api_object/vppable.rb

@@ -1,4 +1,4 @@
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -26,9 +26,16 @@
 ###
 module JSS
 
-  # A mix-in module to handle VPP-related data in API objects that can be
+  # A mix-in module to handleVPP-related data in API objects that can be
   # assigned via VPP.
   #
+  # NOTE: For now we are only working with device-based VPP assignments,
+  # which are done via the scope of the VPPable object (macapp, mobdevapp, ebook)
+  #
+  # User-based APP assignments will require the creation of a VPPAssignment class,
+  # and a VPPAssignmentScope class, since those scopes are very limited compared
+  # to ordinary scope.
+  #
   # To use this module, merely `include VPPable` when defining your
   # subclass of JSS::APIObject
   #
@@ -40,6 +47,50 @@ module JSS
     #####################################
     VPPABLE = true
 
+    # Mixed-in Class Methods
+    #
+    # This is a common technique to get class methods mixed in when
+    # you 'include' a module full of instance methods
+    #####################################
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    # Methods in here will become class methods of the
+    # classes that include VPPable
+    module ClassMethods
+
+      # The names and assignment data for all class members that have
+      # VPP licenses that can be assigned by device.
+      # The assignment data is a hash of three keys pointing to integers:
+      #   {
+      #     total: int,
+      #     used: int,
+      #     remaining: int
+      #   }
+      #
+      # WARNING: This must instantiate all objects, so is slow
+      #
+      # @return [Hash{String=>Hash}] The names and assignment data
+      def all_vpp_device_assignable
+        data = {}
+        all_ids.each do |id|
+          obj = fetch id: id
+          next unless obj.vpp_device_based?
+
+          data[obj.name] = {
+            total: obj.vpp_licenses_total,
+            used: obj.vpp_licenses_used,
+            remaining: obj.vpp_licenses_remaining
+          }
+        end
+        data
+      end # all_vpp_device_assignable
+
+    end # module ClassMethods
+
+
     # Mixed-in Attributes
     #####################################
 
@@ -48,6 +99,7 @@ module JSS
 
     # @return [Integer]
     attr_reader :vpp_admin_account_id
+    alias vpp_account_id vpp_admin_account_id
 
     # @return [Boolean]
     attr_reader :assign_vpp_device_based_licenses
@@ -55,8 +107,7 @@ module JSS
 
     # @return [Integer]
     attr_reader :total_vpp_licenses
-    alias vpp_total_licenses total_vpp_licenses
-    alias vpp_license_count total_vpp_licenses
+    alias vpp_licenses_total total_vpp_licenses
 
     # @return [Integer]
     attr_reader :remaining_vpp_licenses
@@ -66,22 +117,126 @@ module JSS
     attr_reader :used_vpp_licenses
     alias vpp_licenses_used used_vpp_licenses
 
+    #### How to assign VPP content & view assignments
+    #
+    # When doing device-based assignments, they are made via the
+    # Scope of the VPPable Object.
+    #
+    # There is no indication in the device's API data that an app/book was
+    # installed/licensed via VPP, it just shows up in the
+    # list of installed apps like any other.
+    #
+    # When doing user-based assignments, they are made via the (limited)
+    # scope of a 'Volume Assignment' object in Users -> Volume Assignement
+    # These objects are sort of like policies or config profiles in that they have
+    # payloads, and can assign multiple things at once (iosapps, macapps, ebooks)
+    # These are available as vppassignment objects in the API.
+    #
+    # User-based assignments show up in the User's Jamf record
+    # Users -> username -> (vpp acct name)
+    # There you'll see the names of objects assigned to the user, and the
+    # devices on which they've accepted the VPP invitation. In the User's
+    # API data, there isaa 'vpp_assignments' arry of hash's like this:
+    #    [{:id=>13733, :uid=>"258_13733"}]
+    # However, that 'id' is not the id of any known vppassignment object, and
+    # the uid is... ??  The object model at Developer.jamf.com says those
+    # values should be an id and a name, probably pointing to a vppassignment
+    # object, but that isn't the case.
+    #
+    #
+    #### Figuring out how many, and where VPP lic. are used....
+    #
+    # IF dev. based assignement is turned on, then
+    # the VPPable object (app, ebook) in the API will show the total numbers
+    # of both user and device based assignments:
+    #
+    #  "vpp": {
+    #   "assign_vpp_device_based_licenses": true,
+    #   "vpp_admin_account_id": 1,
+    #   "total_vpp_licenses": 2,
+    #   "remaining_vpp_licenses": 0,
+    #   "used_vpp_licenses": 2
+    # }
+    #
+    # However, if assign_vpp_device_based_licenses is false, meaning
+    # all assignments are user-based, then no other info is shown in the API.
+    #
+    # In that case, in the UI, you can see the total assignments in a table
+    # in Settings -> Global Mgmt -> Volume Purch -> Content -> (ios/mac)
+    # The numbers shown there indicate all assignments, whether user- or
+    # deviced-based, just like the numbers in the API data for the VPPable
+    # object, if they are there.
+    # But there's no equivalent for that table data directly in the API when
+    # device-based is false.
+    #
+    # Also in the UI you can see the intividual computers, mobiledevs, and users
+    # to whom an object is assigned, no matter how it was assigned. Go to
+    # Users -> Volume Assignments -> [any assigment object] -> Apps/Books -> ios/mac
+    # and click on the number in the rightmost 'in use' column, and you'll
+    # see a page with 3 tabs, showing the individual computers, mobdevs, or users
+    # with the app/ebook assigned. EXCEPT this doesn't seem to expand
+    # scoped groups - when I added a static computer group with one computer to
+    # the scope of a MacApp, the total in-use count went up from 6 to 7, but the
+    # list of computers two which it was assigned still showed only 6. :-(
+    #
+    # You can also get to the same page via: Users->SeachVolumeContent
+    # then perform a simple search, and in the results page, click on the in-use
+    # number. If you click on the VolumeAssignments number you'll see a
+    # breakdown of the device assignments (from the app itself) and user assignments
+    # and their scopes, but the scopes will not expand any groups, just list them.
+    #
+    # So 2 questions:
+    # 1) How to see the total/used/remaining licenses for a VPPable object in the
+    #   API, regardless of how it's deployed
+    #
+    # - first look at the VPPable object, and if the data is there, yer done.
+    # - If not, then the object is only assigned to users, so we can loop thru
+    #   the vppassignment objects and count things up.
+    #
+    # 2) How to learn where the VPPable object is actually assigned - i.e.
+    #   a list of users and/or devices. Note: this isn't a list of where it's
+    #   installed, but to whom/where it is assigned.
+    #
+    # - TLDR: no scopable object in Jamf gives you such a list, so we probably
+    #   don't need it.
+    #
+    # In the UI, the page you get when clicking the 'in use' column of various
+    # 'volume content' lists (see above) gets you the individually assigned
+    # hardware or users, but doesn't show those via groups.
+    # In the API - there doesn't seem to be any access at all, other than the
+    # scopes of the VPPable Object itself, and any vppassignments that contain it.
+    # Scanning through them is probably the only option, but could be slow once
+    # there are many - and expanding those scopes into an actual list of users
+    # and devices would be a pain to write
+    #
+
+    # Mixed-in Instance Methods
+    #####################################
 
     # Set whether or not the VPP licenses should be assigned
-    # by device rather than by user
+    # by device as well as (or.. instead of?) by user
     #
     # @param new_val[Boolean] The new value
     #
     # @return [void]
     #
     def assign_vpp_device_based_licenses=(new_val)
-      return nil if new_val == @assign_vpp_device_based_licenses
-      raise JSS::InvalidDataError, 'New value must be true or false' unless new_val.jss_boolean?
-      @assign_vpp_device_based_licenses = new_val
+      return if new_val == @assign_vpp_device_based_licenses
+
+      @assign_vpp_device_based_licenses = JSS::Validate.boolean new_val
       @need_to_update = true
     end
     alias vpp_device_based= assign_vpp_device_based_licenses=
 
+    # @return [String] The name of the vpp admin acct for this object
+    #
+    def vpp_admin_account_name
+      return unless @vpp_admin_account_id.is_a? Integer
+
+      JSS::VPPAccount.map_all_ids_to(:name)[@vpp_admin_account_id]
+    end
+    alias vpp_account_name vpp_admin_account_name
+
     # Mixed-in Private Instance Methods
     #####################################
     private
@@ -92,11 +247,12 @@ module JSS
     #
     def parse_vpp
       @vpp_codes = @init_data[:vpp_codes]
-      @vpp_admin_account_id = @init_data[:vpp][:vpp_admin_account_id]
-      @assign_vpp_device_based_licenses = @init_data[:vpp][:assign_vpp_device_based_licenses]
-      @total_vpp_licenses = @init_data[:vpp][:total_vpp_licenses]
-      @remaining_vpp_licenses = @init_data[:vpp][:remaining_vpp_licenses]
-      @used_vpp_licenses = @init_data[:vpp][:used_vpp_licenses]
+      vpp_data = @init_data[:vpp]
+      @vpp_admin_account_id = vpp_data[:vpp_admin_account_id]
+      @assign_vpp_device_based_licenses = vpp_data[:assign_vpp_device_based_licenses]
+      @total_vpp_licenses = vpp_data[:total_vpp_licenses]
+      @remaining_vpp_licenses = vpp_data[:remaining_vpp_licenses]
+      @used_vpp_licenses = vpp_data[:used_vpp_licenses]
     end
 
     # Insert an appropriate vpp element into the XML for sending changes
@@ -109,7 +265,7 @@ module JSS
     def add_vpp_xml(xdoc)
       doc_root = xdoc.root
       vpp = doc_root.add_element 'vpp'
-      vpp.add_element('assign_vpp_device_based_licenses').text = @assign_vpp_device_based_licenses
+      vpp.add_element('assign_vpp_device_based_licenses').text = @assign_vpp_device_based_licenses.to_s
     end
 
   end # VPPable

data/lib/jss/api_object/webhook.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

data/lib/jss/client.rb

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

data/lib/jss/client/jamf_binary.rb

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

data/lib/jss/client/jamf_helper.rb

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

data/lib/jss/client/management_action.rb

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

data/lib/jss/compatibility.rb

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

data/lib/jss/composer.rb

@@ -1,4 +1,4 @@
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -147,7 +147,7 @@ module JSS
 
       ### now build the pkg
       begin
-        it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}' "
+        it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}'"
 
         raise 'There was an error building the .pkg' unless it_built
       ensure

data/lib/jss/configuration.rb

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

data/lib/jss/db_connection.rb

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

data/lib/jss/exceptions.rb

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

data/lib/jss/ruby_extensions.rb

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

data/lib/jss/ruby_extensions/array.rb

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

data/lib/jss/ruby_extensions/filetest.rb

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

data/lib/jss/ruby_extensions/hash.rb

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

data/lib/jss/ruby_extensions/ipaddr.rb

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

data/lib/jss/ruby_extensions/pathname.rb

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

data/lib/jss/ruby_extensions/string.rb

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

data/lib/jss/ruby_extensions/string/backports.rb

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

data/lib/jss/ruby_extensions/string/conversions.rb

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

data/lib/jss/ruby_extensions/string/predicates.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -29,10 +29,11 @@ module JSSRubyExtensions
 
     module Predicates
 
-      INTEGER_RE = /\A[0-9]+\Z/.freeze
+      INTEGER_RE = /\A-?[0-9]+\Z/.freeze
+      FLOAT_RE = /\A-?[0-9]+\.[0-9]+\Z/.freeze
 
-      # Is this string also a positive integer?
-      # (i.e. it consists only of numberic digits)
+      # Is this string also an integer?
+      # (i.e. it consists only of numberic digits, maybe with a dash in front)
       #
       # @return [Boolean]
       #
@@ -40,6 +41,15 @@ module JSSRubyExtensions
         self =~ INTEGER_RE ? true : false
       end
 
+      # Is this string also a floar?
+      # (i.e. it consists only of numberic digits)
+      #
+      # @return [Boolean]
+      #
+      def jss_float?
+        self =~ FLOAT_RE ? true : false
+      end
+
     end # module
 
   end # module

data/lib/jss/ruby_extensions/time.rb

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

data/lib/jss/server.rb

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

data/lib/jss/utility.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -32,7 +32,7 @@ module JSS
 
   # Converts an OS Version into an Array of higher OS versions.
   #
-  # It's unlikely that this library will still be in use as-is by the release of OS X 10.19.15.
+  # It's unlikely that this library will still be in use as-is by the release of OS X 10.30.
   # Hopefully well before then JAMF will implement a "minimum OS" in the JSS itself.
   #
   # @param min_os [String] the mimimum OS version to expand, e.g. ">=10.6.7"  or "10.6.7"
@@ -43,26 +43,12 @@ module JSS
   #   JSS.expand_min_os ">=10.6.7" # => returns this array
   #    # ["10.6.7",
   #    #  "10.6.8",
-  #    #  "10.6.9",
-  #    #  "10.6.10",
-  #    #  "10.6.11",
-  #    #  "10.6.12",
-  #    #  "10.6.13",
-  #    #  "10.6.14",
-  #    #  "10.6.15",
+  #    #  ...
+  #    #  "10.6.25",
   #    #  "10.7.x",
   #    #  "10.8.x",
-  #    #  "10.9.x",
-  #    #  "10.10.x",
-  #    #  "10.11.x",
-  #    #  "10.12.x",
-  #    #  "10.13.x",
-  #    #  "10.14.x",
-  #    #  "10.15.x",
-  #    #  "10.16.x",
-  #    #  "10.17.x",
-  #    #  "10.18.x",
-  #    #  "10.19.x"]
+  #    #  ...
+  #    #  "10.30.x"]
   #
   #
   def self.expand_min_os(min_os)
@@ -80,14 +66,14 @@ module JSS
     # (and hope apple doesn't do more than 15 maint releases for an OS)
     else
       ok_oses = []
-      (maint.to_i..15).each do |m|
+      (maint.to_i..25).each do |m|
         ok_oses << maj + '.' + min + '.' + m.to_s
       end # each m
     end
 
     # now account for all OS X versions starting with 10.
-    # up to at least 10.19.x
-    ((min.to_i + 1)..19).each do |v|
+    # up to 10.30.x
+    ((min.to_i + 1)..30).each do |v|
       ok_oses << maj + '.' + v.to_s + '.x'
     end # each v
     ok_oses