Class: JSS::Group

Inherits:
APIObject show all
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’

See Also:

Direct Known Subclasses

ComputerGroup, MobileDeviceGroup, UserGroup

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

Class Method Summary collapse

Instance Method Summary collapse

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

See Also:



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

#is_smart ⇒ Boolean (readonly) Also known as: smart? 



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

See Also:



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

#notify_on_change ⇒ Boolean (readonly) Also known as: notify_on_change?, notify? 



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.

Raises:



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

Raises:



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

Raises:



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

Raises:

#create(calculate_members: true, retries: 10) ⇒ Object

See Also:



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

Raises:



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

See Also:



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> 



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> 



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.

Raises:

#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

Raises:



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

Raises:

#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

See Also:



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