ruby-jss 0.10.2 → 0.11.0a5

data/lib/jss/api_object/self_servable.rb

@@ -61,7 +61,7 @@ module JSS
   #
   #
   # Classes including this module *MUST*:
-  # - call {#add_self_service_xml()} in their #rest_xml method
+  # - call {#add_self_service_xml(xmldoc)} in their #rest_xml method
   #
   # IMPORTANT: Since SelfServable also includes #{JSS::Updatable}, for uploading icons,
   # see that module for its requirements.
@@ -85,6 +85,8 @@ module JSS
     MAKE_AVAILABLE = 'Make Available in Self Service'.freeze
     AUTO_INSTALL = 'Install Automatically'.freeze
     AUTO_INSTALL_OR_PROMPT = 'Install Automatically/Prompt Users to Install'.freeze
+    PATCHPOL_SELF_SERVICE = 'selfservice'.freeze # 'Make Available in Self Service' in the UI
+    PATCHPOL_AUTO = 'prompt'.freeze # 'Install Automatically' in the UI
 
     DEFAULT_INSTALL_BUTTON_TEXT = 'Install'.freeze
 
@@ -98,6 +100,15 @@ module JSS
         can_display_in_categories: true,
         can_feature_in_categories: true
       },
+      JSS::PatchPolicy => {
+        in_self_service_data_path: [:general, :distribution_method],
+        in_self_service: PATCHPOL_SELF_SERVICE,
+        not_in_self_service: PATCHPOL_AUTO,
+        targets: [:macos],
+        payload: :patchpolicy,
+        can_display_in_categories: false,
+        can_feature_in_categories: false
+      },
       JSS::MacApplication => { # TODO: add the correct values when Jamf fixes this bug
         in_self_service_data_path: nil, # [:general, :distribution_method],
         in_self_service: nil, # MAKE_AVAILABLE,
@@ -471,10 +482,10 @@ module JSS
     end
 
     def validate_icon(id)
-      if JSS::DB_CNX.connected?
-        raise JSS::NoSuchItemError, "No icon with id #{new_icon}" unless JSS::Icon.all_ids.include? id
-      end
+      return nil unless JSS::DB_CNX.connected?
+      raise JSS::NoSuchItemError, "No icon with id #{new_icon}" unless JSS::Icon.all_ids.include? id
     end
+
     # Re-read the icon data for this object from the API
     # Generally done after uploading a new icon via {#icon=}
     #

data/lib/jss/api_object/sitable.rb

@@ -0,0 +1,197 @@
+### Copyright 2017 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
+
+  # Module Variables
+  #####################################
+
+  # Module Methods
+  #####################################
+
+  # Classes
+  #####################################
+
+  # A mix-in module that centralizes the code for handling objects which can be
+  # assigned a 'site' in the JSS.
+  #
+  # Objects in the JSS present site data in the top-level :general Hash
+  # in the :site key which is a Hash with a :name and :id key.
+  #
+  # Classes mixing in this module MUST:
+  #
+  # - define the constant SITE_SUBSET as either :top, :general, or whatever
+  #   sub-hash of API data conaints the site info. (most are :general, but
+  #   some, like advanced searches, are at the top level)
+  #
+  # - call {#add_site_to_xml(xmldoc)} from their #rest_xml method if they are
+  #   {Updatable} or {Creatable}
+  #
+  module Sitable
+
+    # Module Constants
+    #####################################
+
+    SITABLE = true
+
+    # When no site has been assigned, this is the 'name' and id used
+    NO_SITE_NAME = 'None'.freeze
+    NO_SITE_ID = -1
+
+    # Setting the site to any of these values will unset the site
+    NON_SITES = [
+      nil,
+      '',
+      0,
+      NO_SITE_NAME,
+      NO_SITE_ID
+    ].freeze
+
+    # Mixed-in Public Instance Methods
+    #####################################
+
+    # The name of the site for this object.
+    # For backward compatibility, this is aliased to just
+    # 'site'
+    #
+    # @return [String] The name of the site for this object.
+    #
+    def site_name
+      @site_name
+    end # cat name
+    alias site site_name
+
+    # The id of the site for this object.
+    #
+    # @return [Integer] The id of the site for this object.
+    #
+    def site_id
+      @site_id
+    end # cat id
+
+    # The JSS::Site instance for this object's site
+    #
+    # @return [JSS::Site] The JSS::Site instance for this object's site
+    #
+    def site_object
+      return nil unless site_assigned?
+      JSS::Site.new id: @site_id
+    end # cat obj
+
+    # Does this object have a site assigned?
+    #
+    # @return [Boolean] Does this object have a site assigned?
+    #
+    def site_assigned?
+      !@site_name.nil?
+    end # cat assigned?
+
+    # Change the site of this object.
+    # Any of the NON_SITES values will
+    # unset the site
+    #
+    # @param new_site[Integer, String] The new site
+    #
+    # @return [void]
+    #
+    def site=(new_site)
+      return nil unless updatable? || creatable?
+
+      # unset the site? Use nil or an empty string
+      if NON_SITES.include? new_site
+        unset_site
+        return
+      end
+
+
+      new_id = JSS::Site.valid_id new_site, api: @api
+      new_name = JSS::Site.map_all_ids_to(:name, api: @api)[new_id]
+      # no change, go home.
+      return nil if new_name == @site_name
+
+      raise JSS::NoSuchItemError, "Site '#{new_site}' is not known to the JSS" unless new_id
+
+      @site_name = new_name
+      @site_id = new_id
+      @need_to_update = true
+    end # site =
+
+    # Set the site to nothing
+    #
+    # @return [void]
+    #
+    def unset_site
+      # no change, go home
+      return nil if @site_name.nil?
+      @site_name = nil
+      @site_id = nil
+      @need_to_update = true
+    end # unset site
+
+    # Mixed-in Private Instance Methods
+    #####################################
+    private
+
+    # Parse the site data from any incoming API data
+    #
+    # @return [void]
+    #
+    def parse_site
+      site_data =
+        if self.class::SITE_SUBSET == :top
+          @init_data[:site]
+        else
+          @init_data[self.class::SITE_SUBSET][:site]
+        end
+
+      raise JSS::MissingDataError, 'No Site data found in API data.' unless site_data
+
+      @site_name = site_data[:name]
+      @site_id = site_data[:id]
+    end # parse site
+
+    # Add the site to the XML for POSTing or PUTting to the API.
+    #
+    # @param xmldoc[REXML::Document] The in-construction XML document
+    #
+    # @return [void]
+    #
+    def add_site_to_xml(xmldoc)
+      root = xmldoc.root
+      site_elem =
+        if self.class::SITE_SUBSET == :top
+          root.add_element 'site'
+        else
+          parent_elem = root.elements[self.class::SITE_SUBSET.to_s]
+          parent_elem ||= root.add_element(self.class::SITE_SUBSET.to_s)
+          parent_elem.add_element 'site'
+        end
+      site_elem.add_element('name').text = @site_name.to_s
+    end # add_site_to_xml
+
+  end # module categorizable
+
+end # module

data/lib/jss/api_object/site.rb

@@ -1,99 +1,68 @@
-### Copyright 2017 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.
-###
-###
-
-###
+# Copyright 2017 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
 
-  #####################################
-  ### Module Variables
-  #####################################
-
-  #####################################
-  ### Module Methods
-  #####################################
+  # Classes
+  ###################################
 
-
-  #####################################
-  ### Classes
-  #####################################
-
-  ###
-  ### A Site in the JSS.
-  ###
-  ### These are simple, in that they only have an ID and a name.
-  ###
-  ### @see JSS::APIObject
-  ###
+  # A Site in the JSS.
+  #
+  # These are simple, in that they only have an ID and a name.
+  #
+  # @see JSS::APIObject
+  #
   class Site < JSS::APIObject
 
-    #####################################
-    ### Mix-Ins
-    #####################################
+    # Mix-Ins
+    ###################################
     include JSS::Creatable
     include JSS::Updatable
 
-    #####################################
-    ### Class Methods
-    #####################################
-
-    #####################################
-    ### Class Constants
-    #####################################
+    # Class Constants
+    ###################################
 
-    ### The base for REST resources of this class
-    RSRC_BASE = "sites"
+    # The base for REST resources of this class
+    RSRC_BASE = 'sites'.freeze
 
-    ### the hash key used for the JSON list output of all objects in the JSS
+    # the hash key used for the JSON list output of all objects in the JSS
     RSRC_LIST_KEY = :sites
 
-    ### The hash key used for the JSON object output.
-    ### It's also used in various error messages
+    # The hash key used for the JSON object output.
+    # It's also used in various error messages
     RSRC_OBJECT_KEY = :site
 
-    ### these keys, as well as :id and :name,  are present in valid API JSON data for this class
-    VALID_DATA_KEYS = []
+    # these keys, as well as :id and :name,  are present in valid API JSON data for this class
+    VALID_DATA_KEYS = [].freeze
 
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}
     OBJECT_HISTORY_OBJECT_TYPE = 44
 
-    #####################################
-    ### Attributes
-    #####################################
-
-    #####################################
-    ### Constructor
-    #####################################
-
-
-    #####################################
-    ### Public Instance Methods
-    #####################################
-
-
   end # class site
 
 end # module

data/lib/jss/api_object/user.rb

@@ -106,9 +106,13 @@ module JSS
 
     ### @return [Array<Hash>]
     ###
-    ### The sites associated with this user
+    ### Unlike every other Sitable object, Users
+    ### can be in multiple sites, so we don't use
+    ### the Sitable mixin module. Instead we'll
+    ### we'll store them in this Array, as they come
+    ### from the API.
     ###
-    ### Each Hash has then :id and :name for one site
+    ### Each Hash has the :id and :name for one site
     ###
     attr_reader :sites
 
@@ -267,7 +271,7 @@ module JSS
 
       user << JSS::Site.xml_list(@sites)
 
-      user << ext_attr_xml if @changed_eas && !@changed_eas.empty?
+      user << ext_attr_xml if unsaved_eas?
 
       return doc.to_s
     end

data/lib/jss/api_object.rb

@@ -483,6 +483,47 @@ module JSS
       new args
     end
 
+
+    # Delete one or more API objects by jss_id without instantiating them.
+    # Non-existent id's are skipped and an array of skipped ids is returned.
+    #
+    # If an Array is provided, it is passed through #uniq! before being processed.
+    #
+    # @param victims[Integer,Array<Integer>] An object id or an array of them
+    #   to be deleted
+    #
+    # @param api[JSS::APIConnection] the API connection to use.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
+    # @return [Array<Integer>] The id's that didn't exist when we tried to
+    #   delete them.
+    #
+    def self.delete(victims, api: JSS.api)
+      raise JSS::UnsupportedError, '.delete can only be called on subclasses of JSS::APIObject' if self == JSS::APIObject
+      raise JSS::InvalidDataError, 'Parameter must be an Integer ID or an Array of them' unless victims.is_a?(Integer) || victims.is_a?(Array)
+
+      case victims
+      when Integer
+        victims = [victims]
+      when Fixnum
+        victims = [victims]
+      when Array
+        victims.uniq!
+      end
+
+      skipped = []
+      current_ids = all_ids :refresh, api: api
+      victims.each do |vid|
+        if current_ids.include? vid
+          api.delete_rsrc "#{self::RSRC_BASE}/id/#{vid}"
+        else
+          skipped << vid
+        end # if current_ids include v
+      end # each victim
+
+      skipped
+    end # self.delete
+
     ### Class Constants
     #####################################
 
@@ -654,11 +695,16 @@ module JSS
       defined? self.class::SELF_SERVABLE
     end
 
-    # @return [Boolean] See {JSS::criteriable}
+    # @return [Boolean] See {JSS::Criteriable}
     def criterable?
       defined? self.class::CRITERIABLE
     end
 
+    # @return [Boolean] See {JSS::Sitable}
+    def sitable?
+      defined? self.class::SITABLE
+    end
+
     # @return [Boolean] See {JSS::extendable}
     def extendable?
       defined? self.class::EXTENDABLE
@@ -691,8 +737,8 @@ module JSS
 
     # Delete this item from the JSS.
     #
-    # TODO: Make a class method for mass deletion
-    # without instantiating, then call it from this method.
+    # @seealso {APIObject.delete} for deleting
+    # one or more objects by id without needing to instantiate
     #
     # Subclasses may want to redefine this method,
     # first calling super, then setting other attributes to
@@ -815,6 +861,17 @@ module JSS
       history
     end
 
+    # Print the rest_xml value of the object to stdout,
+    # with indentation. Useful for debugging.
+    #
+    # @return [void]
+    #
+    def ppx
+      return nil unless creatable? || updatable?
+      REXML::Document.new(rest_xml).write $stdout, 2
+      puts
+    end
+
     # Private Instance Methods
     #####################################
     private
@@ -920,10 +977,11 @@ module JSS
       # many things have  a :site
       # TODO: Implement a Sitable mixin module
       #
-      @site = JSS::APIObject.get_name(@main_subset[:site]) if @main_subset[:site]
+      # @site = JSS::APIObject.get_name(@main_subset[:site]) if @main_subset[:site]
 
       ##### Handle Mix-ins
       initialize_category
+      initialize_site
       initialize_location
       initialize_purchasing
       initialize_scope
@@ -959,6 +1017,14 @@ module JSS
       parse_category if categorizable?
     end
 
+    # parse site data during initialization
+    #
+    # @return [void]
+    #
+    def initialize_site
+      parse_site if sitable?
+    end
+
     # parse location data during initialization
     #
     # @return [void]
@@ -1063,6 +1129,9 @@ require 'jss/api_object/extendable'
 require 'jss/api_object/self_servable'
 require 'jss/api_object/categorizable'
 require 'jss/api_object/vppable'
+require 'jss/api_object/sitable'
+require 'jss/api_object/mdm'
+require 'jss/api_object/management_history'
 
 ### Mix-in Sub Modules with Classes
 require 'jss/api_object/criteriable'
@@ -1091,6 +1160,8 @@ 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'
 require 'jss/api_object/peripheral_type'
 require 'jss/api_object/peripheral'
 require 'jss/api_object/policy'

data/lib/jss/utility.rb

@@ -558,4 +558,25 @@ module JSS
     pw
   end
 
+  # un/set devmode mode.
+  # Useful when coding - methods can call JSS.devmode? and then
+  # e.g. spit out something instead of performing some action.
+  #
+  # @param [Symbol] Set devmode :on or :off
+  #
+  # @return [Boolean] The new state of devmode
+  #
+  def self.devmode(setting)
+    @devmode = setting == :on ? true : false
+  end
+
+
+  # is devmode currently on?
+  #
+  # @return [Boolean]
+  #
+  def self.devmode?
+    @devmode
+  end
+
 end # module

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '0.10.2'.freeze
+  VERSION = '0.11.0a5'.freeze
 
 end # module

data/lib/jss.rb

@@ -59,6 +59,7 @@ module JSS
   require 'rest-client'
   require 'json'
   require 'plist'
+  require 'immutable-struct'
 
   ### Constants
   #####################################
@@ -160,6 +161,8 @@ module JSS
   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
   class PeripheralType < JSS::APIObject; end
   class Peripheral < JSS::APIObject; end
   class Policy < JSS::APIObject; end
@@ -183,6 +186,9 @@ module JSS
   module SelfServable; end
   module Categorizable; end
   module VPPable; end
+  module Sitable; end
+  module MDM; end
+  module ManagementHistory; end
 
 end # module JSS