ruby-jss 1.0.3b3 → 1.0.3b4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e023160e63bd4d2ae22316affa806e28ad38559d17c9cc8e2f6624f8a72e2c09
-  data.tar.gz: 24689091017132fb6a95e5fc6ea6ad36d771d660665df540bd82cd3856f05b3a
+  metadata.gz: 2b0bf5083913e6e9d2cf6588f229109ef8013fe64d5ea522c4a0031cc1ed2c88
+  data.tar.gz: 6cd578111688ad29bba7595e522a2bfd97b298e2c85fb7a3e14a4d92c8c50980
 SHA512:
-  metadata.gz: 4200856d8cfdfa38e1dd3b6a4a86ea1aef995c9fd72e70bc5bf7205c86e817bc1edc9cc3cb06115b0b34ab5d117e73fac27dbc376152054dd9edb21649696a36
-  data.tar.gz: f9dc27ad6c8398b6743c2ea654331ab8efabf1a5ee22747ac555fc598d0276de955a94edbdc8d29802df68abad706e72902b33b47ba3c14e31f4fbd997bbd976
+  metadata.gz: f1d0a5b50436e1c66dff5079ee1a1c1bb72298c527db8682adff99db986cca3c4993e02c01bdf5117e9be5e6c6020788a47d5c4eee4e1b744c7e54a9ea649021
+  data.tar.gz: 3913594f7506a232b29f004790645762a52f47fcae1968c35e3cd17c633cfe165d6d26ec35d8506c93cb5658cbf9c6b70f863de6f6da29d371381789f1f059ed

data/CHANGES.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## \[Unreleased]
 ### Added
+- JSS::Group (and its subclasses) now have a `change_membership` class and instance method for static groups.
+  - The class method allows adding and removing members without fetching an instance of the group.
+  - The instance method adds and/or removes members immediately, without needing to call #update or #save
+
 - LDAPServer.server_for_user and .server_for_group class methods, return the id of the first LDAP server containing the given user or group
 
 - Client.homdir(user) and Client.do_not_disturb?(user)
@@ -22,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (Thanks @christopher.kemp!)
 
 ### Fixed
+- JSS::MobileDevice.update now returns the device's jss id, as advertised.
+
 - default port number choice for on-prem vs. JamfCloud connections
 
 - Client.primary_console_user returns nil when at the loginwindow

data/lib/jss/api_object/group.rb

@@ -37,8 +37,13 @@ module JSS
   # When changing the criteria of a smart group, use the #criteria attribute,
   # which is a {JSS::Criteria} instance.
   #
-  # Subclasses must define the constant MEMBER_CLASS which indicates Ruby class
-  # to which the group members belong (e.g. JSS::MobileDevice)
+  # Subclasses must define these constants:
+  # - MEMBER_CLASS: the ruby-jss class to which the group
+  #   members belong (e.g. JSS::MobileDevice)
+  # - ADD_MEMBERS_ELEMENT: the XML element tag for adding members to the group
+  #   wuth a PUT call to the API, e.g. 'computer_additions'
+  # - REMOVE_MEMBERS_ELEMENT: the XML element tag for removing members from the
+  #   group wuth a PUT call to the API, e.g. 'computer_deletions'
   #
   # @see JSS::APIObject
   #
@@ -62,6 +67,9 @@ module JSS
     # Where is the Site data in the API JSON?
     SITE_SUBSET = :top
 
+    # the 'id' xml element tag
+    ID_XML_TAG = 'id'.freeze
+
     # Class Methods
     #####################################
 
@@ -79,6 +87,103 @@ module JSS
       all(refresh, api: api).select { |g| (g[:is_smart]) }
     end
 
+    # Immediatly add and/or remove members in a static group without
+    # instantiating it first. Uses the <x_additions> and <x_deletions>
+    # XML elements available when sending a PUT request to the API.
+    #
+    # @param group [String, Integer] The name or id of the group being changed
+    #
+    # @param add_members [String, Integer, Array<String, Integer>] valid
+    #   identifier(s) for members to add
+    #
+    # @param remove_members [String, Integer, Array<String, Integer>] valid
+    #   identifier(s) for members to remove
+    #
+    # @param api [JSS::APIConnection] The API connetion to use, uses the default
+    #   connection if not specified
+    #
+    # @return [void]
+    #
+    def self.change_membership(group, add_members: [], remove_members: [], api: JSS.api)
+      raise JSS::NoSuchItemError, "No #{self} matching '#{ident}'" unless (group_id = valid_id group, api: api)
+      raise JSS::UnsupportedError, "Not a static group, can't change membership directly" if map_all_ids_to(:is_smart, api: api)[group_id]
+
+      add_members = [add_members].flatten
+      remove_members = [remove_members].flatten
+      return if add_members.empty? && remove_members.empty?
+
+      # we must know the current group membership, because the API
+      # will raise a conflict error if we try to remove a member
+      # that isn't in the group (which is kinda lame - it should just
+      # ignore this, like it does when we add a member that's already
+      # in the group.)
+      current_member_ids = fetch(id: group_id).member_ids
+
+      # nil if no changes to be made
+      xml_doc = change_membership_xml add_members, remove_members, current_member_ids
+      return unless xml_doc
+
+      api.put_rsrc "#{self::RSRC_BASE}/id/#{group_id}", xml_doc.to_s
+    end
+
+    # return [REXML::Document, nil]
+    #
+    def self.change_membership_xml(add_members, remove_members, current_member_ids)
+      # these are nil if there are no changes to make
+      addx = member_additions_xml(add_members, current_member_ids)
+      remx = member_removals_xml(remove_members, current_member_ids)
+      return nil unless addx || remx
+
+      doc = REXML::Document.new JSS::APIConnection::XML_HEADER
+      groupelem = doc.add_element self::RSRC_OBJECT_KEY.to_s
+      groupelem << addx if addx
+      groupelem << remx if remx
+      doc
+    end
+    private_class_method :change_membership_xml
+
+    # @return [REXML::Element, nil]
+    #
+    def self.member_additions_xml(add_members, current_member_ids)
+      return nil if add_members.empty?
+
+      additions = REXML::Element.new self::ADD_MEMBERS_ELEMENT
+      member_added = false
+      add_members.each do |am|
+        am_id = self::MEMBER_CLASS.valid_id am
+        raise JSS::NoSuchItemError, "No #{self::MEMBER_CLASS} matching '#{am}'" unless am_id
+        next if current_member_ids.include? am_id
+
+        xam = additions.add_element self::MEMBER_CLASS::RSRC_OBJECT_KEY.to_s
+        xam.add_element(ID_XML_TAG).text = am_id.to_s
+        member_added = true
+      end # each
+
+      member_added ? additions : nil
+    end
+    private_class_method :member_additions_xml
+
+    # @return [REXML::Element, nil]
+    #
+    def self.member_removals_xml(remove_members, current_member_ids)
+      return nil if remove_members.empty?
+
+      removals = REXML::Element.new self::REMOVE_MEMBERS_ELEMENT
+      member_removed = false
+      remove_members.each do |rm|
+        rm_id = self::MEMBER_CLASS.valid_id rm
+        next unless rm_id && current_member_ids.include?(rm_id)
+
+        xrm = removals.add_element self::MEMBER_CLASS::RSRC_OBJECT_KEY.to_s
+        xrm.add_element(ID_XML_TAG).text = rm_id.to_s
+        member_removed = true
+      end # each
+
+      member_removed ? removals : nil
+    end
+    private_class_method :member_removals_xml
+
+
     # Attributes
     #####################################
 
@@ -100,8 +205,6 @@ module JSS
     # @return [Boolean] does this group send notifications when it changes?
     attr_reader :notify_on_change
 
-    # @return [String] the :name of the site for this group
-    attr_reader :site
 
     # Constructor
     #####################################
@@ -126,8 +229,6 @@ module JSS
         else
           []
         end
-
-      @site = JSS::APIObject.get_name(@init_data[:site])
     end # init
 
     # Public Instance Methods
@@ -149,7 +250,7 @@ module JSS
     def update
       super
       refresh_members
-      true
+      @id
     end
 
     # @see APIObject#delete
@@ -253,24 +354,33 @@ module JSS
       @need_to_update = true
     end
 
-    # Refresh the membership from the API
+    # Immediatly add and/or remove members in this static group
     #
-    # @return [Array<Hash>] the refresh membership
+    # IMPORTANT: This method changes the group in the JSS immediately,
+    #   there is no need to call #update/#save
     #
-    def refresh_members
-      @members = @api.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY]
-    end
-
-    # Change the site for this group
+    # @param add_members [String, Integer, Array<String, Integer>] valid
+    #   identifier(s) for members to add
+    #
+    # @param remove_members [String, Integer, Array<String, Integer>] valid
+    #   identifier(s) for members to remove
     #
-    # @param new_val[String] the name of the new site
+    # @param api [JSS::APIConnection] The API connetion to use, uses the default
+    #   connection if not specified
     #
     # @return [void]
     #
-    def site=(new_val)
-      raise JSS::NoSuchItemError, "No site named #{new_val} in the JSS" unless JSS::Site.all_names(api: @api).include? new_val
-      @site = new_val
-      @need_to_update = true
+    def change_membership(add_members: [], remove_members: [])
+      self.class.change_membership(@id, add_members: add_members, remove_members: remove_members, api: @api)
+      refresh_members
+    end
+
+    # Refresh the membership from the API
+    #
+    # @return [Array<Hash>] the refresh membership
+    #
+    def refresh_members
+      @members = @api.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY]
     end
 
     # aliases

data/lib/jss/api_object/group/computer_group.rb

@@ -82,6 +82,12 @@ module JSS
     ### this allows the parent Group class to do things right
     MEMBER_CLASS = JSS::Computer
 
+    # the XML element for immediate member additions via PUT
+    ADD_MEMBERS_ELEMENT = 'computer_additions'.freeze
+
+    # the XML element for immediate member removals via PUT
+    REMOVE_MEMBERS_ELEMENT = 'computer_deletions'.freeze
+
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}

data/lib/jss/api_object/group/mobile_device_group.rb

@@ -78,6 +78,12 @@ module JSS
     ### this allows the parent Group class to do things right
     MEMBER_CLASS = JSS::MobileDevice
 
+    # the XML element for immediate member additions via PUT
+    ADD_MEMBERS_ELEMENT = 'mobile_device_additions'.freeze
+
+    # the XML element for immediate member removals via PUT
+    REMOVE_MEMBERS_ELEMENT = 'mobile_device_deletions'.freeze
+
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}

data/lib/jss/api_object/group/user_group.rb

@@ -78,6 +78,12 @@ module JSS
     ### this allows the parent Group class to do things right
     MEMBER_CLASS = JSS::User
 
+    # the XML element for immediate member additions via PUT
+    ADD_MEMBERS_ELEMENT = 'user_additions'.freeze
+
+    # the XML element for immediate member removals via PUT
+    REMOVE_MEMBERS_ELEMENT = 'user_deletions'.freeze
+
     # the object type for this object in
     # the object history table.
     # See {APIObject#add_object_history_entry}

data/lib/jss/api_object/mobile_device.rb

@@ -523,9 +523,10 @@ module JSS
     #
     def update
       super
-      return unless @needs_mdm_name_change
+      return @id unless @needs_mdm_name_change
       set_device_name @name if managed? && supervised?
       @needs_mdm_name_change = false
+      @id
     end
 
     # private methods

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '1.0.3b3'.freeze
+  VERSION = '1.0.3b4'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 1.0.3b3
+  version: 1.0.3b4
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-15 00:00:00.000000000 Z
+date: 2019-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist