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 the constant MEMBER_CLASS which indicates Ruby class to which the group members belong (e.g. JSS::MobileDevice)

See Also:

Direct Known Subclasses

ComputerGroup, MobileDeviceGroup, UserGroup

Constant Summary collapse

GROUP_TYPES =

the types of groups allowed for creation

[:smart, :static]
SITE_SUBSET =

Where is the Site data in the API JSON?

:top

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 .new with a :type key and a value of :smart or :static, as well as a :name and the :id => :new

See Also:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/jss/api_object/group.rb', line 144

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

  @site = JSS::APIObject.get_name(@init_data[:site])

end

Instance Attribute Details

#criteria ⇒ JSS::Criteriable::Criteria Originally defined in module Criteriable

Returns the criteria for the instance into which we’re mixed.

Returns:

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

Returns is this a smart group.

Returns:

  • (Boolean) —

    is this a smart group



124
125
126
 
# File 'lib/jss/api_object/group.rb', line 124

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

Returns:

See Also:



121
122
123
 
# File 'lib/jss/api_object/group.rb', line 121

def members
  @members
end

#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    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?.

Returns:

  • (Boolean) —

    does this group send notifications when it changes?



127
128
129
 
# File 'lib/jss/api_object/group.rb', line 127

def notify_on_change
  @notify_on_change
end

#site ⇒ String

Returns the :name of the site for this group.

Returns:

  • (String) —

    the :name of the site for this group



131
132
133
 
# File 'lib/jss/api_object/group.rb', line 131

def site
  @site
end

Class Method Details

.all_smart(refresh = false, api: JSS.api) ⇒ Object

Returns an Array of all the smart groups.



95
96
97
 
# File 'lib/jss/api_object/group.rb', line 95

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.



103
104
105
 
# File 'lib/jss/api_object/group.rb', line 103

def self.all_static(refresh = false, api: JSS.api)
  all(refresh, api: api).select{|g| not g[:is_smart] }
end

Instance Method Details

#add_member(m) ⇒ void

This method returns an undefined value.

Add a member, by name or id

Parameters:

  • m (Integer, String) —

    the id or name of the member to add

Raises:



270
271
272
273
274
 
# File 'lib/jss/api_object/group.rb', line 270

def add_member(m)
  raise UnsupportedError, "Smart group members can't be changed." if @is_smart
  @members << check_member(m)
  @need_to_update = true
end

#clear ⇒ void

This method returns an undefined value.

Remove all members

Raises:



298
299
300
301
302
303
 
# File 'lib/jss/api_object/group.rb', line 298

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

Parameters:

  • name (String) —

    the name for the new object

  • api (JSS::APIConnection) (defaults to: nil) —

    the API in which to create the object Defaults to the API used to instantiate this object

Returns:

  • (APIObject) —

    An uncreated clone of this APIObject with the given name

Raises:

#create ⇒ Object

See Also:



171
172
173
174
175
176
177
178
 
# File 'lib/jss/api_object/group.rb', line 171

def create
  if @is_smart
    raise JSS::MissingDataError, "No criteria specified for smart group" unless @criteria
  end
  super
  refresh_members
  return @id
end

#criteria=(new_criteria) ⇒ Object

Apply a new set of criteria to a smart group

Parameters:

  • new_criteria (JSS::Criteria) —

    the new criteria for the smart group

Raises:



206
207
208
209
 
# File 'lib/jss/api_object/group.rb', line 206

def criteria= (new_criteria)
  raise InvalidDataError, "Only smart groups have criteria." unless @is_smart
  super
end

#delete ⇒ Object

See Also:



193
194
195
196
197
198
199
 
# File 'lib/jss/api_object/group.rb', line 193

def delete
  super
  @is_smart = nil
  @criteria = nil
  @site = nil
  @members = []
end

#member_ids ⇒ Array<Integer>

Returns the ids of the group members.

Returns:

  • (Array<Integer>) —

    the ids of the group members



231
232
233
 
# File 'lib/jss/api_object/group.rb', line 231

def member_ids
  @members.map{|m| m[:id]}
end

#member_names ⇒ Array<String>

Returns the names of the group members.

Returns:



224
225
226
 
# File 'lib/jss/api_object/group.rb', line 224

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.

Parameters:

  • newname (String) —

    the new name

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

Returns:



310
311
312
 
# File 'lib/jss/api_object/group.rb', line 310

def refresh_members
  @members = @api.get_rsrc(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY]
end

#remove_member(m) ⇒ void

This method returns an undefined value.

Remove a member by id, or name

Parameters:

  • m (Integer, String) —

    the id or name of the member to remove

Raises:



283
284
285
286
287
288
289
290
291
 
# File 'lib/jss/api_object/group.rb', line 283

def remove_member(m)
  raise InvalidDataError, "Smart group members can't be changed." if @is_smart

  if @members.reject!{ |mm|  [mm[:id], mm[:name], mm[:username]].include? m  }
    @need_to_update = true
  else
    raise JSS::NoSuchItemError, "No member matches '#{m}'"
  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_assigned? ⇒ Boolean Originally defined in module Sitable

Does this object have a site assigned?

Returns:

  • (Boolean) —

    Does this object have a site assigned?

#site_id ⇒ Integer Originally defined in module Sitable

The id of the site for this object.

Returns:

  • (Integer) —

    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’

Returns:

  • (String) —

    The name of the site for this object.

#site_object ⇒ JSS::Site Originally defined in module Sitable

The JSS::Site instance for this object’s site

Returns:

  • (JSS::Site) —

    The JSS::Site instance for this object’s site

#size ⇒ Integer Also known as: count

How many members of the group?

Returns:

  • (Integer) —

    the number of members of the group



216
217
218
 
# File 'lib/jss/api_object/group.rb', line 216

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 ⇒ Object

See Also:



184
185
186
187
188
 
# File 'lib/jss/api_object/group.rb', line 184

def update
  super
  refresh_members
  true
end