Class: JSS::User

Inherits:
APIObject show all
Includes:
Creatable, Extendable, Updatable
Defined in:
lib/jss/api_object/user.rb,
lib/jss.rb

Overview

A User in the JSS.

See Also:

Constant Summary collapse

RSRC_BASE =

The base for REST resources of this class

"users"
RSRC_LIST_KEY =

the hash key used for the JSON list output of all objects in the JSS

:users
RSRC_OBJECT_KEY =

The hash key used for the JSON object output. It's also used in various error messages

:user
SEARCH_CLASS =

This class lets us seach for users

JSS::AdvancedUserSearch
EXT_ATTRIB_CLASS =

This is the class for relevant Extension Attributes

JSS::UserExtensionAttribute
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry

53

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ User

See JSS::APIObject#initialize



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/jss/api_object/user.rb', line 163

def initialize (args = {})
  super

  @full_name = @init_data[:full_name]
  @email = @init_data[:email]
  @phone_number = @init_data[:phone_number]
  @position = @init_data[:position]
  @ldap_server = JSS::APIObject.get_name @init_data[:ldap_server]
  @ldap_server_id = @init_data[:ldap_server][:id] unless @init_data[:ldap_server].nil?
  @sites = @init_data[:sites] ? @init_data[:sites]  : []

  if @init_data[:links]
    @computers = @init_data[:links][:computers]
    @peripherals = @init_data[:links][:peripherals]
    @mobile_devices = @init_data[:links][:mobile_devices]
    @vpp_assignments = @init_data[:links][:vpp_assignments]
    @total_vpp_code_count = @init_data[:links][:total_vpp_code_count]
  end

end

Instance Attribute Details

#computers ⇒ Array<Hash> (readonly)

The computers associated with this user

Each Hash has then :id and :name for one computer

Returns:



123
124
125
 
# File 'lib/jss/api_object/user.rb', line 123

def computers
  @computers
end

#email ⇒ String

Returns The user's email address.

Returns:

  • (String) —

    The user's email address



92
93
94
 
# File 'lib/jss/api_object/user.rb', line 92

def email
  @email
end

#extension_attributes ⇒ Array<Hash> (readonly) Originally defined in module Extendable

Returns The extension attribute values for the object.

Returns:

  • (Array<Hash>) —

    The extension attribute values for the object

#full_name ⇒ String

Returns The user's full name.

Returns:

  • (String) —

    The user's full name



89
90
91
 
# File 'lib/jss/api_object/user.rb', line 89

def full_name
  @full_name
end

#ldap_server ⇒ String

Returns The name of the user's LDAP server.

Returns:

  • (String) —

    The name of the user's LDAP server



101
102
103
 
# File 'lib/jss/api_object/user.rb', line 101

def ldap_server
  @ldap_server
end

#ldap_sever_id ⇒ Object (readonly)

Returns the value of attribute ldap_sever_id.



102
103
104
 
# File 'lib/jss/api_object/user.rb', line 102

def ldap_sever_id
  @ldap_sever_id
end

#mobile_devices ⇒ Array<Hash> (readonly)

Note:

This data is currently broken - the JSON output of the API only

The mobile devices associated with this user

Each Hash has then :id and :name for one device

returns one mobile device, and it isn't formatted in a standard way.

Returns:



143
144
145
 
# File 'lib/jss/api_object/user.rb', line 143

def mobile_devices
  @mobile_devices
end

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

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    do we have unsaved changes?

#peripherals ⇒ Array<Hash> (readonly)

The peripherals associated with this user

Each Hash has then :id and :name for one peripheral

Returns:



132
133
134
 
# File 'lib/jss/api_object/user.rb', line 132

def peripherals
  @peripherals
end

#phone_number ⇒ String

Returns The user's phone number.

Returns:

  • (String) —

    The user's phone number



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

def phone_number
  @phone_number
end

#position ⇒ String

Returns The user's position / job title.

Returns:

  • (String) —

    The user's position / job title



98
99
100
 
# File 'lib/jss/api_object/user.rb', line 98

def position
  @position
end

#sites ⇒ Array<Hash> (readonly)

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 the :id and :name for one site

Returns:



114
115
116
 
# File 'lib/jss/api_object/user.rb', line 114

def sites
  @sites
end

#total_vpp_code_count ⇒ Integer (readonly)

Returns the total number of vpp codes assigned to this user.

Returns:

  • (Integer) —

    the total number of vpp codes assigned to this user



154
155
156
 
# File 'lib/jss/api_object/user.rb', line 154

def total_vpp_code_count
  @total_vpp_code_count
end

#vpp_assignments ⇒ Array<Hash> (readonly)

The user-based vpp assignments associated with this user

Each Hash has then :id and :name for one assignment

Returns:



151
152
153
 
# File 'lib/jss/api_object/user.rb', line 151

def vpp_assignments
  @vpp_assignments
end

Instance Method Details

#add_site(site) ⇒ void

This method returns an undefined value.

Add this user to a site

Parameters:

  • site (String) —

    the name of the site

Raises:



232
233
234
235
236
237
 
# File 'lib/jss/api_object/user.rb', line 232

def add_site (site)
  return nil if @sites.map{|s| s[:name]}.include? site
  raise JSS::InvalidDataError, "No site in the JSS named #{site}" unless JSS::Site.all_names(api: @api).include? site
  @sites << {:name => site}
  @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 ⇒ Integer Originally defined in module Creatable

Create a new object in the JSS.

Parameters:

  • api (JSS::APIConnection) —

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

Returns:

  • (Integer) —

    the jss ID of the newly created object

Raises:

#ea_names ⇒ Array<String> Originally defined in module Extendable

Returns the names of all known EAs.

Returns:

#ea_types ⇒ Hash{String => String} Originally defined in module Extendable

Returns EA names => data type (one of 'String', 'Number', or 'Date').

Returns:

  • (Hash{String => String}) —

    EA names => data type (one of 'String', 'Number', or 'Date')

#ext_attr_xml ⇒ REXML::Element Originally defined in module Extendable

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.

TODO: make this (and all XML amending) method take the in-progress XML doc and add (or not) the EA xml to it. See how Sitable#add_site_to_xml works, as called from Computer.rest_xml

Returns:

  • (REXML::Element) —

    An <extension_attribute> element to be included in the rest_xml of objects that mix-in this module.

#ext_attrs ⇒ Object Originally defined in module Extendable

An easier-to-use hash of EA name to EA value. This isn't created until its needed, to speed up instantiation.

#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_ext_attrs ⇒ void Originally defined in module Extendable

This method returns an undefined value.

Populate @extension_attributes (the Array of Hashes that comes from the API) and @ext_attr_names, which is a Hash mapping the EA names to their values. This is called during initialization for all objects that mix in this module

#remove_site(site) ⇒ void

This method returns an undefined value.

Remove this user from a site

Parameters:

  • site (String) —

    the name of the site



246
247
248
249
250
 
# File 'lib/jss/api_object/user.rb', line 246

def remove_site (site)
  return nil unless @sites.map{|s| s[:name]}.include? site
  @sites.reject!{|s| s[:name] == site}
  @need_to_update = true
end

#set_ext_attr(ea_name, value, validate_popup_choice: true, refresh: false) ⇒ void Originally defined in module Extendable

This method returns an undefined value.

Set the value of an extension attribute

The new value is validated based on the data type of the Ext. Attrib:

  • If the ext. attrib. is defined with a data type of Integer/Number, the value must be an Integer.

  • If defined with a data type of Date, the value will be parsed as a timestamp, and parsing may raise an exception. Dates can't be blank.

  • If defined wth data type of String, `to_s` will be called on the value.

By default, the full EA definition object is fetched to see if the EA's input type is 'popup menu', and if so, the new value must be one of the defined popup choices, or blank.

The EA definitions used for popup validation are cached, so we don't have to reach out to the server every time. If you expect the definition to have changed since it was cached, provide a truthy value to the refresh: parameter

To bypass popup validation complepletely, provide a falsey value to the validate_popup_choice: parameter. WARNING: beware that your value is the correct type and format, or you might get errors when saving back to the API.

Note that while the Jamf Pro Web interface does not allow editing the values of Extension Attributes populated by Scripts or LDAP, the API does allow it. Bear in mind however that those values will be reset again at the next recon.

Parameters:

  • name (String) —

    the name of the extension attribute to set

  • value (String, Time, Integer) —

    the new value for the extension attribute for this user

  • validate_popup_choice (Boolean) (defaults to: true) —

    validate the new value against the E.A. definition. Defaults to true.

  • refresh (Boolean) (defaults to: false) —

    Re-read the ext. attrib definition from the API, for popup validation.

Raises:

  • (ArgumentError)

#unsaved_eas? ⇒ Boolean Originally defined in module Extendable

are there any changes in the EAs needing to be saved?

Returns:

  • (Boolean)

#update ⇒ Boolean Originally defined in module Updatable

Save changes to the JSS

Returns:

  • (Boolean) —

    success

Raises:

#user_groups(refresh = false) ⇒ Array<Hash>

Workaround for the recurring Jamf Classic API Bug where JSON is missing data that should come in an array of hashes, but only comes as a hash with a single hash inside, with data for only the last item in the XML array.

When needed, we fetch and parse the XML, which has the desired data. Use any truthy parameter to re-fetch the XML data, otherwise the data last fetched is used.

In this case, the user group data is fetched as XML and returned as an Array of Hashes, one per group the user is a member of. Each hash containing three Symbol keys:

id: Integer, the group id
name: String, the group name
is_smart: Boolean, is it a smart group or a static group?

Parameters:

  • refresh (Boolean) (defaults to: false) —

    Re-fetch the group data from the API

Returns:

  • (Array<Hash>) —

    The groups the user is a member of.



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/jss/api_object/user.rb', line 273

def user_groups(refresh = false)
  @grp_array = nil if refresh
  return @grp_array if @grp_array

  @grp_array = []
  raw_xml = @api.get_rsrc "/users/id/#{@id}", :xml
  xmlroot = REXML::Document.new(raw_xml).root
  xml_grps = xmlroot.elements['user_groups']

  xml_grps.each do |xml_grp|
    next if xml_grp.name == 'size'

    gid = xml_grp.elements['id'].text.to_i
    gname = xml_grp.elements['name'].text
    smart = xml_grp.elements['is_smart'].text == 'true'
    @grp_array << { id: gid, name: gname, is_smart: smart }
  end # groups.each

  @grp_array
end

#validate_ea_value(ea_name, value, validate_popup_choice, refresh) ⇒ Object Originally defined in module Extendable

is the value being passed to set_ext_attr valid? Converts values as needed (e.g. strings to integers or Times)

If the EA is defined to hold a string, any value is accepted and converted with #to_s

Note: All EAs can be blank

Parameters:

  • name (String) —

    the name of the extension attribute to set

  • value (String, Time, Integer) —

    the new value for the extension attribute for this user

  • validate_popup_choice (Boolean) —

    validate the new value against the E.A. definition. Defaults to true.

  • refresh (Boolean) —

    Re-read the ext. attrib definition from the API, for popup validation.

Returns:

  • (Object) —

    the possibly modified valid value

#validate_integer_ea_value(ea_name, value) ⇒ Object Originally defined in module Extendable

raise error if the value isn't an integer

#validate_popup_value(ea_name, value, refresh) ⇒ Object Originally defined in module Extendable

Raise an error if the named EA has a popup menu, but the provided value isn't one of the menu items

Raises: