ruby-jss 1.3.3 → 1.4.1

data/lib/jss/api_object/self_servable.rb

@@ -51,12 +51,12 @@ module JSS
   # - :security
   #
   # Additionally, items that apper in macOS Slf Svc have these keys:
-  # - :self_service_display_name
+  # - :self_service_display_name (but not JSS::MacApplication)
   # - :install_button_text
-  # - :reinstall_button_text
+  # - :reinstall_button_text (but not JSS::MacApplication)
   # - :force_users_to_view_description
   # - :notification
-  # - :notification_location # PENDING API FIX
+  # - :notification_location # PENDING API FIX, and also, not JSS::MacApplication
   # - :notification_subject
   # - :notification_message
   #
@@ -178,15 +178,14 @@ module JSS
         notification_reminders: true
       },
       JSS::MacApplication => {
-        # in_self_service_data_path was finally implemnted in JamfPro 10.9
-        # Jamf Product Issue [PI-003773]
-        in_self_service_data_path: [:general, :deployment_type],
+        in_self_service_data_path: %i[general deployment_type],
         in_self_service: MAKE_AVAILABLE,
         not_in_self_service: AUTO_INSTALL_OR_PROMPT,
         targets: [:macos],
         payload: :app,
         can_display_in_categories: true,
         can_feature_in_categories: true,
+        notifications_supported: :ssvc_and_nctr,
         url_entity: 'app'
         # OTHER BUG: no notification options seem to be changable via the API
       },
@@ -329,6 +328,7 @@ module JSS
     #
     def self_service_view_url
       return nil unless @self_service_data_config[:url_entity]
+
       "#{USER_URL_BASE}#{@self_service_data_config[:url_entity]}&id=#{id}&action=#{USER_URL_VIEW_ACTION}"
     end
 
@@ -336,6 +336,7 @@ module JSS
     #
     def self_service_execute_url
       return nil unless @self_service_data_config[:url_entity]
+
       "#{USER_URL_BASE}#{@self_service_data_config[:url_entity]}&id=#{id}&action=#{USER_URL_EXEC_ACTION}"
     end
 
@@ -349,6 +350,7 @@ module JSS
     def self_service_description=(new_val)
       new_val = new_val.strip
       return if @self_service_description == new_val
+
       @self_service_description = new_val
       @need_to_update = true
     end
@@ -820,7 +822,7 @@ module JSS
       # ssvc subset...
       add_in_self_service_xml doc_root
 
-      subset_key = @self_service_data_config[:self_service_subset] ? @self_service_data_config[:self_service_subset] : :self_service
+      subset_key = @self_service_data_config[:self_service_subset] || :self_service
 
       ssvc = doc_root.add_element subset_key.to_s
 
@@ -857,6 +859,7 @@ module JSS
     # add the xml specific to profiles
     def add_self_service_profile_xml(ssvc, doc_root)
       return unless self_service_payload == :profile
+
       if self_service_targets.include? :ios
         sec = ssvc.add_element('security')
         sec.add_element('removal_disallowed').text = PROFILE_REMOVAL_BY_USER[@self_service_user_removable]
@@ -871,6 +874,7 @@ module JSS
     def add_self_service_category_xml(ssvc)
       cats = ssvc.add_element('self_service_categories')
       return if self_service_categories.empty?
+
       self_service_categories.each do |cat|
         catelem = cats.add_element('category')
         catelem.add_element('name').text = cat[:name]
@@ -882,10 +886,14 @@ module JSS
     # set macOS settings in ssvc xml
     def add_self_service_macos_xml(ssvc)
       return unless self_service_targets.include? :macos
-      ssvc.add_element('self_service_display_name').text = self_service_display_name if self_service_display_name
+
       ssvc.add_element('install_button_text').text = self_service_install_button_text if self_service_install_button_text
-      ssvc.add_element('reinstall_button_text').text = self_service_reinstall_button_text if self_service_reinstall_button_text
       ssvc.add_element('force_users_to_view_description').text = self_service_force_users_to_view_description.to_s
+
+      return if self.class == JSS::MacApplication
+
+      ssvc.add_element('self_service_display_name').text = self_service_display_name if self_service_display_name
+      ssvc.add_element('reinstall_button_text').text = self_service_reinstall_button_text if self_service_reinstall_button_text
     end
 
 

data/lib/jss/api_object/uploadable.rb

@@ -103,7 +103,7 @@ module JSS
     #  Methods
     #####################################
 
-    #
+
     # Upload a file to the JSS via the REST Resource of the
     # object to which this module is mixed in.
     #

data/lib/jss/api_object/user.rb

@@ -144,7 +144,7 @@ module JSS
 
     ### @return [Array<Hash>]
     ###
-    ### The vpp assignments associated with this user
+    ### The user-based vpp assignments associated with this user
     ###
     ### Each Hash has then :id and :name for one assignment
     ###
@@ -249,6 +249,47 @@ module JSS
       @need_to_update = true
     end
 
+    # Workaround for the recurring Jamf Classic API Bug where
+    # JSON is missing data that should come in an array of hashes, but
+    # only comes as a hash with a single hash inside, with data for only
+    # the last item in the XML array.
+    #
+    # When needed, we fetch and parse the XML, which has the desired data.
+    # Use any truthy parameter to re-fetch the XML data, otherwise the
+    # data last fetched is used.
+    #
+    # In this case, the user group data is fetched as XML and returned as
+    # an Array of Hashes, one per group the user is a member of. Each hash
+    # containing three Symbol keys:
+    #
+    #   id: Integer, the group id
+    #   name: String, the group name
+    #   is_smart: Boolean, is it a smart group or a static group?
+    #
+    # @param refresh[Boolean] Re-fetch the group data from the API
+    #
+    # @return [Array<Hash>] The groups the user is a member of.
+    #
+    def user_groups(refresh = false)
+      @grp_array = nil if refresh
+      return @grp_array if @grp_array
+
+      @grp_array = []
+      raw_xml = @api.get_rsrc "/users/id/#{@id}", :xml
+      xmlroot = REXML::Document.new(raw_xml).root
+      xml_grps = xmlroot.elements['user_groups']
+
+      xml_grps.each do |xml_grp|
+        next if xml_grp.name == 'size'
+
+        gid = xml_grp.elements['id'].text.to_i
+        gname = xml_grp.elements['name'].text
+        smart = xml_grp.elements['is_smart'].text == 'true'
+        @grp_array << { id: gid, name: gname, is_smart: smart }
+      end # groups.each
+
+      @grp_array
+    end # user_groups
 
     #####################################
     ### Private Instance Methods

data/lib/jss/api_object/vpp_account.rb

@@ -0,0 +1,209 @@
+### 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
+###    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
+
+  # A VPP account defined in the JSS
+  #
+  class VPPAccount < JSS::APIObject
+
+    # Mix-Ins
+    #####################################
+    include JSS::Updatable
+    include JSS::Sitable
+
+    # Class Constants
+    #####################################
+
+    ### The base for REST resources of this class
+    RSRC_BASE = 'vppaccounts'.freeze
+
+    ### the hash key used for the JSON list output of all objects in the JSS
+    RSRC_LIST_KEY = :vpp_accounts
+
+    ### The hash key used for the JSON object output.
+    ### It's also used in various error messages
+    RSRC_OBJECT_KEY = :vpp_account
+
+    SITE_SUBSET = :top
+
+    # Attributes
+    #####################################
+
+    # @return [String] The full name of the local contact person for the acct
+    attr_reader :contact
+
+    # @return [String] The service token for connecting to the account at Apple.
+    #   Currently not visible, appears as '***************'
+    attr_reader :service_token
+
+    # @return [String] The name of the company associated with the Acct/Token
+    attr_reader :account_name
+
+    # @return [Time] The expiration date of the Acct/Token
+    attr_reader :expiration_date
+
+    # @return [String] The location associated with the Acct/Token
+    attr_reader :location_name
+    alias location location_name
+
+    # @return [String] The Country Code associated with the acct
+    attr_reader :country
+
+    # @return [String] The AppleID associated with the acct
+    attr_reader :apple_id
+
+    # @return [Boolean] Automatically populate purchased content from Apple
+    #   School Manager or Apple Business Manager in Jamf Pro
+    attr_reader :populate_catalog_from_vpp_content
+
+    # @return [Boolean] Display a notification to users on their mobile devices
+    #   when a volume purchased app in a user-based volume assignment is no
+    #   longer assigned to them
+    attr_reader :notify_disassociation
+
+    # @return [Boolean] Automatically register users that have Managed Apple IDs
+    #   so they do not receive an invitation and are not prompted to register
+    #   with volume purchasing
+    attr_reader :auto_register_managed_users
+
+    # Constructor
+    #####################################
+
+    # See JSS::APIObject#initialize
+    #
+    def initialize(args = {})
+      super
+      @contact = @init_data[:contact]
+      @service_token = @init_data[:service_token]
+      @account_name = @init_data[:account_name]
+      @expiration_date = @init_data[:expiration_date].to_s.empty? ? nil : Time.parse(@init_data[:expiration_date])
+      @location_name = @init_data[:location_name]
+      @country = @init_data[:country]
+      @apple_id = @init_data[:apple_id]
+      @populate_catalog_from_vpp_content = @init_data[:populate_catalog_from_vpp_content]
+      @notify_disassociation = @init_data[:notify_disassociation]
+      @auto_register_managed_users = @init_data[:auto_register_managed_users]
+    end
+
+    # Public Instance Methods
+    #####################################
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def contact=(new_val = @contact)
+      return if new_val == @contact
+
+      @contact = JSS::Validate.non_empty_string new_val, 'Contact must be a non-empty String'
+      @need_to_update = true
+    end
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def country=(new_val = @country)
+      return if new_val == @country
+
+      @country = JSS::Validate.app_store_country_code new_val
+      @need_to_update = true
+    end
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def apple_id=(new_val = @apple_id)
+      return if new_val == @apple_id
+
+      @apple_id = JSS::Validate.email_address new_val
+      @need_to_update = true
+    end
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def populate_catalog_from_vpp_content=(new_val = @populate_catalog_from_vpp_content)
+      return if new_val == @populate_catalog_from_vpp_content
+
+      @populate_catalog_from_vpp_content = JSS::Validate.boolean new_val
+      @need_to_update = true
+    end
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def notify_disassociation=(new_val = @notify_disassociation)
+      return if new_val == @notify_disassociation
+
+      @notify_disassociation = JSS::Validate.boolean new_val
+      @need_to_update = true
+    end
+
+    # @param new_val[String] the value
+    #
+    # @return [void]
+    #
+    def auto_register_managed_users=(new_val = @auto_register_managed_users)
+      return if new_val == @auto_register_managed_users
+
+      @auto_register_managed_users = JSS::Validate.boolean new_val
+      @need_to_update = true
+    end
+
+    # Private Instance Methods
+    #####################################
+    private
+
+    # Return a String with the XML Resource
+    # for submitting creation or changes to the JSS via
+    # the API via the Creatable or Updatable modules
+    #
+    # Most classes will redefine this method.
+    #
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      tmpl = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
+      tmpl.add_element('name').text = @name
+      tmpl.add_element('contact').text = @contact
+      tmpl.add_element('country').text = @country
+      tmpl.add_element('apple_id').text = @apple_id
+      tmpl.add_element('populate_catalog_from_vpp_content').text = @populate_catalog_from_vpp_content.to_s
+      tmpl.add_element('notify_disassociation').text = @notify_disassociation.to_s
+      tmpl.add_element('auto_register_managed_users').text = @auto_register_managed_users.to_s
+
+      add_site_to_xml doc
+
+      doc.to_s
+    end
+
+  end # VPPAccount
+
+end # JSS

data/lib/jss/api_object/vppable.rb

@@ -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