Class: JSS::Group
- Includes:
- Creatable, Criteriable, Sitable, Updatable
- Defined in:
- lib/jss/api_object/group.rb,
lib/jss.rb
Overview
This is the parent class of the smart/static group objects in the JSS namely, ComputerGroup, MobileDeviceGroup, and UserGroup
It provides methods for working with the membership of static groups and, by including Criteriable, the criteria for smart groups.
When changing the criteria of a smart group, use the #criteria attribute, which is a Criteria instance.
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’
Direct Known Subclasses
Constant Summary collapse
- GROUP_TYPES =
the types of groups allowed for creation
%i[smart static].freeze
- SITE_SUBSET =
Where is the Site data in the API JSON?
:top
- ID_XML_TAG =
the ‘id’ xml element tag
'id'.freeze
Instance Attribute Summary collapse
-
#criteria ⇒ JSS::Criteriable::Criteria
included
from Criteriable
The criteria for the instance into which we’re mixed.
-
#is_smart ⇒ Boolean
(also: #smart?)
readonly
Is this a smart group.
-
#members ⇒ Array<Hash>
Each hash contains the identifiers for a member of the group, those being: - :id, :name, and possibly :udid, :serial_number, :mac_address, :alt_mac_address, and :wifi_mac_address.
-
#need_to_update ⇒ Boolean
included
from Updatable
readonly
Do we have unsaved changes?.
-
#notify_on_change ⇒ Boolean
(also: #notify_on_change?, #notify?)
readonly
Does this group send notifications when it changes?.
Class Method Summary collapse
-
.all_smart(refresh = false, api: JSS.api) ⇒ Object
Returns an Array of all the smart groups.
-
.all_static(refresh = false, api: JSS.api) ⇒ Object
Returns an Array of all the static groups.
-
.change_membership(group, add_members: [], remove_members: [], api: JSS.api) ⇒ void
Immediatly add and/or remove members in a static group without instantiating it first.
Instance Method Summary collapse
-
#add_member(mem) ⇒ void
Add a member, by name or id.
-
#change_membership(add_members: [], remove_members: []) ⇒ void
Immediatly add and/or remove members in this static group.
-
#clear ⇒ void
Remove all members.
-
#clone(new_name, api: nil) ⇒ APIObject
included
from Creatable
make a clone of this API object, with a new name.
- #create(calculate_members: true, retries: 10) ⇒ Object
-
#criteria=(new_criteria) ⇒ Object
Apply a new set of criteria to a smart group.
- #delete ⇒ Object
-
#initialize(args = {}) ⇒ Group
constructor
When creating a new group in the JSS, you must call .make with a :type key and a value of :smart or :static, as well as a :name.
-
#member_ids ⇒ Array<Integer>
The ids of the group members.
-
#member_names ⇒ Array<String>
The names of the group members.
-
#name=(newname) ⇒ void
included
from Updatable
Change the name of this item Remember to #update to push changes to the server.
-
#parse_criteria ⇒ void
included
from Criteriable
During initialization, convert the @init_data Hash into a JSS::Criteriable::Criteria instance stored in @criteria.
-
#refresh_members ⇒ Array<Hash>
Refresh the membership from the API.
-
#remove_member(mem) ⇒ void
Remove a member by id, or name.
-
#save(**params) ⇒ Object
Wrapper/alias for both create and update.
-
#should_update ⇒ void
included
from Criteriable
private
Allow our Criteria to tell us when there’s been a change that needs to be updated.
-
#site=(new_site) ⇒ void
included
from Sitable
Change the site of this object.
-
#site_assigned? ⇒ Boolean
included
from Sitable
Does this object have a site assigned?.
-
#site_id ⇒ Integer
included
from Sitable
The id of the site for this object.
-
#site_name ⇒ String
(also: #site)
included
from Sitable
The name of the site for this object.
-
#site_object ⇒ JSS::Site
included
from Sitable
The JSS::Site instance for this object’s site.
-
#size ⇒ Integer
(also: #count)
How many members of the group?.
-
#unset_site ⇒ void
included
from Sitable
Set the site to nothing.
- #update(refresh: true) ⇒ Object
Constructor Details
#initialize(args = {}) ⇒ Group
When creating a new group in the JSS, you must call .make with a :type key and a value of :smart or :static, as well as a :name
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 |
# File 'lib/jss/api_object/group.rb', line 217 def initialize(args = {}) if args[:id] == :new raise JSS::InvalidDataError, 'New group creation must specify a :type of :smart or :static' unless GROUP_TYPES.include? args[:type] end super args @is_smart = @init_data[:is_smart] || (args[:type] == :smart) @members = if @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY] @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY] else [] end end |
Instance Attribute Details
#criteria ⇒ JSS::Criteriable::Criteria Originally defined in module Criteriable
Returns the criteria for the instance into which we’re mixed.
#is_smart ⇒ Boolean (readonly) Also known as: smart?
Returns is this a smart group.
203 204 205 |
# File 'lib/jss/api_object/group.rb', line 203 def is_smart @is_smart end |
#members ⇒ Array<Hash>
Each hash contains the identifiers for a member of the group, those being:
-
:id, :name, and possibly :udid, :serial_number, :mac_address, :alt_mac_address, and :wifi_mac_address
200 201 202 |
# File 'lib/jss/api_object/group.rb', line 200 def members @members end |
#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable
Returns do we have unsaved changes?.
#notify_on_change ⇒ Boolean (readonly) Also known as: notify_on_change?, notify?
Returns does this group send notifications when it changes?.
206 207 208 |
# File 'lib/jss/api_object/group.rb', line 206 def notify_on_change @notify_on_change end |
Class Method Details
.all_smart(refresh = false, api: JSS.api) ⇒ Object
Returns an Array of all the smart groups.
79 80 81 |
# File 'lib/jss/api_object/group.rb', line 79 def self.all_smart(refresh = false, api: JSS.api) all(refresh, api: api).select { |g| g[:is_smart] } end |
.all_static(refresh = false, api: JSS.api) ⇒ Object
Returns an Array of all the static groups.
86 87 88 |
# File 'lib/jss/api_object/group.rb', line 86 def self.all_static(refresh = false, api: JSS.api) all(refresh, api: api).reject { |g| g[:is_smart] } end |
.change_membership(group, add_members: [], remove_members: [], api: JSS.api) ⇒ void
This method returns an undefined value.
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.
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 |
# File 'lib/jss/api_object/group.rb', line 107 def self.change_membership(group, add_members: [], remove_members: [], api: JSS.api) raise JSS::NoSuchItemError, "No #{self} matching '#{group}'" 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 |
Instance Method Details
#add_member(mem) ⇒ void
This method returns an undefined value.
Add a member, by name or id
366 367 368 369 370 |
# File 'lib/jss/api_object/group.rb', line 366 def add_member(mem) raise UnsupportedError, "Smart group members can't be changed." if @is_smart @members << check_member(mem) @need_to_update = true end |
#change_membership(add_members: [], remove_members: []) ⇒ void
This method returns an undefined value.
Immediatly add and/or remove members in this static group
IMPORTANT: This method changes the group in the JSS immediately,
there is no need to call #update/#save
412 413 414 415 |
# File 'lib/jss/api_object/group.rb', line 412 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 |
#clear ⇒ void
This method returns an undefined value.
Remove all members
389 390 391 392 393 394 |
# File 'lib/jss/api_object/group.rb', line 389 def clear raise InvalidDataError, "Smart group members can't be changed." if @is_smart return if @members.empty? @members.clear @need_to_update = true end |
#clone(new_name, api: nil) ⇒ APIObject Originally defined in module Creatable
make a clone of this API object, with a new name. The class must be creatable
#create(calculate_members: true, retries: 10) ⇒ Object
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 |
# File 'lib/jss/api_object/group.rb', line 247 def create(calculate_members: true, retries: 10) if @is_smart raise JSS::MissingDataError, 'No criteria specified for smart group' unless @criteria end super() if calculate_members tries = 0 while tries < retries begin refresh_members break rescue RestClient::NotFound sleep 1 tries += 1 end # begin end # while end # if calc members @id end |
#criteria=(new_criteria) ⇒ Object
Apply a new set of criteria to a smart group
308 309 310 311 312 |
# File 'lib/jss/api_object/group.rb', line 308 def criteria=(new_criteria) raise InvalidDataError, 'Only smart groups have criteria.' unless @is_smart super end |
#delete ⇒ Object
296 297 298 299 300 301 302 |
# File 'lib/jss/api_object/group.rb', line 296 def delete super @is_smart = nil @criteria = nil @site = nil @members = [] end |
#member_ids ⇒ Array<Integer>
Returns the ids of the group members.
330 331 332 |
# File 'lib/jss/api_object/group.rb', line 330 def member_ids @members.map { |m| m[:id] } end |
#member_names ⇒ Array<String>
Returns the names of the group members.
324 325 326 |
# File 'lib/jss/api_object/group.rb', line 324 def member_names @members.map { |m| m[:name] } end |
#name=(newname) ⇒ void Originally defined in module Updatable
This method returns an undefined value.
Change the name of this item Remember to #update to push changes to the server.
#parse_criteria ⇒ void Originally defined in module Criteriable
This method returns an undefined value.
During initialization, convert the @init_data Hash into a JSS::Criteriable::Criteria instance stored in @criteria
Classes mixing in this module must call this in #initialize
#refresh_members ⇒ Array<Hash>
Refresh the membership from the API
421 422 423 |
# File 'lib/jss/api_object/group.rb', line 421 def refresh_members @members = @api.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY] end |
#remove_member(mem) ⇒ void
This method returns an undefined value.
Remove a member by id, or name
378 379 380 381 382 383 |
# File 'lib/jss/api_object/group.rb', line 378 def remove_member(mem) raise InvalidDataError, "Smart group members can't be changed." if @is_smart raise InvalidDataError, "Can't remove nil" if mem.nil? removed = @members.reject! { |mm| [mm[:id], mm[:name], mm[:username]].include? mem } @need_to_update = true if removed end |
#save(**params) ⇒ Object
Wrapper/alias for both create and update
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 |
# File 'lib/jss/api_object/group.rb', line 278 def save(**params) params[:calculate_members] = true if params[:calculate_members].nil? params[:retries] = 10 if params[:retries].nil? params[:refresh] = true if params[:refresh].nil? if @in_jss raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable? update refresh: params[:refresh] else raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable? create calculate_members: params[:calculate_members], retries: params[:retries] end end |
#should_update ⇒ void Originally defined in module Criteriable
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
This method returns an undefined value.
Allow our Criteria to tell us when there’s been a change that needs to be updated.
#site=(new_site) ⇒ void Originally defined in module Sitable
This method returns an undefined value.
Change the site of this object. Any of the NON_SITES values will unset the site
#site_assigned? ⇒ Boolean Originally defined in module Sitable
Does this object have a site assigned?
#site_id ⇒ Integer Originally defined in module Sitable
The id of the site for this object.
#site_name ⇒ String Also known as: site Originally defined in module Sitable
The name of the site for this object. For backward compatibility, this is aliased to just ‘site’
#site_object ⇒ JSS::Site Originally defined in module Sitable
The JSS::Site instance for this object’s site
#size ⇒ Integer Also known as: count
How many members of the group?
318 319 320 |
# File 'lib/jss/api_object/group.rb', line 318 def size @members.count end |
#unset_site ⇒ void Originally defined in module Sitable
This method returns an undefined value.
Set the site to nothing
#update(refresh: true) ⇒ Object
271 272 273 274 275 |
# File 'lib/jss/api_object/group.rb', line 271 def update(refresh: true) super() refresh_members if refresh @id end |