Class: JSS::ExtensionAttribute

Inherits:
APIObject show all
Includes:
Creatable, Updatable
Defined in:
lib/jss-api/api_object/extension_attribute.rb,
lib/jss-api.rb

Overview

The parent class of ExtensionAttribute objects in the JSS.

The API extension attribute objects work with the definitions of extension attributes, not the resulting values stored in the JSS with the inventory reports.

This superclass, however, uses the AdvancedSearch subclasses to provide access to the reported values in two ways:

  • A list of target objects with a certain value for the ExtensionAttribute instance. See the #all_with_result method for details

  • A list of the most recent value for this ExtensionAttribute in all targets in the JSS

The ComputerExtensionAttribute subclass offers a ComputerExtensionAttribute#history method providing the history of values for the EA for one computer. This requires MySQL access to the JSS database since that history isn’t available via the API.

Subclasses of ExtensionAttribute must define these constants:

See Also:

Constant Summary collapse

DATA_TYPES =

What kinds of data can be created by EAs? Note, Dates must be in the format “YYYY-MM-DD hh:mm:ss”

["String", "Date", "Integer"]
DEFAULT_DATA_TYPE = 
"String"
INPUT_TYPES =

Where does the data come from?

[ "Text Field", "Pop-up Menu", "script", "LDAP Attribute Mapping"]
DEFAULT_INPUT_TYPE = 
"Text Field"
EDITABLE_INPUT_TYPES =

These input types can be modified, the others cannot.

["Text Field", "Pop-up Menu"]
WEB_DISPLAY_CHOICES =

Where can it be displayed in the WebApp? subclasses can add to this list

[
  "General",
  "Operating System",
  "Hardware",
  "User and Location",
  "Purchasing",
  "Extension Attributes"
]
DEFAULT_WEB_DISPLAY_CHOICE = 
"Extension Attributes"

Constants included from Updatable

Updatable::UPDATABLE

Constants included from Creatable

Creatable::CREATABLE

Constants inherited from APIObject

APIObject::DEFAULT_LOOKUP_KEYS, APIObject::REQUIRED_DATA_KEYS

Instance Attribute Summary collapse

Attributes included from Updatable

#need_to_update

Attributes inherited from APIObject

#id, #in_jss, #name, #rest_rsrc

Instance Method Summary collapse

Methods included from Updatable

#name=

Methods inherited from APIObject

all, all_ids, all_names, get_name, map_all_ids_to, #save, xml_list

Constructor Details

#initialize(args = {}) ⇒ ExtensionAttribute

Returns a new instance of ExtensionAttribute.

See Also:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 144

def initialize(args = {})

  super args

  ### @init_data now has the raw data
  ### so fill in our attributes or set defaults

  @description = @init_data[:description]
  @data_type = @init_data[:data_type] || DEFAULT_DATA_TYPE
  @web_display = @init_data[:inventory_display] || DEFAULT_WEB_DISPLAY_CHOICE

  
  if @init_data[:input_type]
    @input_type = @init_data[:input_type][:type] || DEFAULT_INPUT_TYPE
    @popup_choices = @init_data[:input_type][:popup_choices]
  else
    @input_type = DEFAULT_INPUT_TYPE
  end

  ### the name of the EA might have spaces and caps, which the will come to us as symbols with the spaces
  ### as underscores, like this.
  @symbolized_name = @name.gsub(' ','_').to_sym

end

Instance Attribute Details

#data_type ⇒ String

Returns the type of data created by the EA. Must be one of DATA_TYPES.

Returns:

  • (String) —

    the type of data created by the EA. Must be one of DATA_TYPES



124
125
126
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 124

def data_type
  @data_type
end

#description ⇒ String Also known as: desc

Returns description of the ext attrib.

Returns:

  • (String) —

    description of the ext attrib



121
122
123
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 121

def description
  @description
end

#input_type ⇒ String

Returns where does this data come from? Must be one of the INPUT_TYPES.

Returns:

  • (String) —

    where does this data come from? Must be one of the INPUT_TYPES.



127
128
129
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 127

def input_type
  @input_type
end

#popup_choices ⇒ Array<String>

Returns the choices available in the UI when the @input_type is “Pop-up Menu”.

Returns:

  • (Array<String>) —

    the choices available in the UI when the @input_type is “Pop-up Menu”



130
131
132
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 130

def popup_choices
  @popup_choices
end

#web_display ⇒ String

Returns In which part of the web UI does the data appear?.

Returns:

  • (String) —

    In which part of the web UI does the data appear?



133
134
135
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 133

def web_display
  @web_display
end

Instance Method Details

#all_with_result(search_type, desired_value) ⇒ Array<Hash{:id=>Integer,:name=>String,:value=>String,Integer,Time}>

Get an Array of Hashes for all inventory objects with a desired result in their latest report for this EA.

Each Hash is one inventory object (computer, mobile device, user), with these keys:

:id - the computer id
:name - the computer name
:value - the matching ext attr value for the objects latest report.

This is done by creating a temprary AdvancedSearch for objects with matching values in the EA field, then getting the #search_results hash from it.

The AdvancedSearch is then deleted.

must be a member of JSS::Criterion::SEARCH_TYPES

Parameters:

  • search_type (String) —

    how are we comparing the stored value with the desired value.

  • desired_value (String) —

    the value to compare with the stored value to determine a match.

Returns:

Raises:



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 324

def all_with_result(search_type, desired_value)
  raise JSS::NoSuchItemError, "EA Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY}." unless @in_jss
  raise JSS::InvalidDataError, "Invalid search_type, see JSS::Criteriable::Criterion::SEARCH_TYPES" unless JSS::Criteriable::Criterion::SEARCH_TYPES.include? search_type.to_s
  begin

    search_class = self.class::TARGET_CLASS::SEARCH_CLASS
    acs = search_class.new :id => :new, :name => "JSSgem-EA-#{Time.now.to_jss_epoch}-result-search"
    acs.display_fields = [@name]
    crit_list = [JSS::Criteriable::Criterion.new(:and_or => "and", :name => @name, :search_type => search_type.to_s, :value => desired_value)]
    acs.criteria = JSS::Criteriable::Criteria.new crit_list

    acs.create :get_results

    results = []

    acs.search_results.each{ |i|
      value = case @data_type
        when "Date" then JSS.parse_datetime i[@symbolized_name]
        when "Integer" then i[@symbolized_name].to_i
        else i[@symbolized_name]
      end # case
      results << {:id => i[:id], :name => i[:name], :value => value}
    }

  ensure
    acs.delete
  end
  results
end

#create ⇒ Object

See Also:



176
177
178
179
180
181
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 176

def create
  if @input_type == "Pop-up Menu"
      raise MissingDataError, "No popup_choices set for Pop-up Menu input_type." unless @popup_choices.kind_of? Array and (not @popup_choices.empty?)
  end
  super
end

#delete ⇒ Object

See Also:



197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 197

def delete
  orig_open_timeout = JSS::API.cnx.options[:open_timeout]
  orig_timeout = JSS::API.cnx.options[:timeout]
  JSS::API.timeout = orig_timeout + 1800
  JSS::API.open_timeout = orig_open_timeout + 1800
  begin
    super
  ensure
    JSS::API.timeout = orig_timeout
    JSS::API.open_timeout = orig_open_timeout
  end
end

#latest_values ⇒ Array<Hash{:id=>Integer,:name=>String,:value=>String,Integer,Time}>

Return an Array of Hashes showing the most recent value for this EA on all inventory objects in the JSS.

Each Hash is one inventory object (computer, mobile device, user), with these keys:

:id - the jss id
:name - the object name
:value - the most recent ext attr value for the object.

This is done by creating a temporary AdvancedSearch for all objects, with the EA as a display field. The #search_result then contains the desired data.

The AdvancedSearch is then deleted.

Returns:

Raises:

See Also:



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 381

def latest_values
  raise JSS::NoSuchItemError, "EA Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY}." unless @in_jss
  tmp_advsrch = "JSSgem-EA-#{Time.now.to_jss_epoch}-latest-search"
  
  begin
    search_class = self.class::TARGET_CLASS::SEARCH_CLASS
    acs = search_class.new :id => :new, :name => tmp_advsrch
    acs.display_fields = [@name]

    # search for 'Username like "" ' because all searchable object classes have a "Username" value
    #crit_list = [JSS::Criteriable::Criterion.new(:and_or => "and", :name => "Username", :search_type => "like", :value => '')]

    acs.criteria = JSS::Criteriable::Criteria.new [ self.class::ALL_TARGETS_CRITERION]
    acs.create :get_results

    results = []

    acs.search_results.each{ |i|
      value = case @data_type
        when "Date" then JSS.parse_datetime i[@symbolized_name]
        when "Integer" then i[@symbolized_name].to_i
        else i[@symbolized_name]
      end # case
      results << {:id => i[:id], :name => i[:name], :value => value}
    }

  ensure
    acs.delete
    self.class::TARGET_CLASS::SEARCH_CLASS.new(:name => tmp_advsrch).delete if self.class::TARGET_CLASS::SEARCH_CLASS.all_names(:refresh).include? tmp_advsrch
  end

  results

end

#update ⇒ Object

See Also:



186
187
188
189
190
191
 
# File 'lib/jss-api/api_object/extension_attribute.rb', line 186

def update
  if @input_type == "Pop-up Menu"
      raise MissingDataError, "No popup_choices set for Pop-up Menu input_type." unless @popup_choices.kind_of? Array and (not @popup_choices.empty?)
  end
  super
end