class Jamf::ComputerExtensionAttribute

The definition of a Computer extension attribute in the JSS

@see Jamf::ExtensionAttribute

@see Jamf::APIObject

Constants

ALL_TARGETS_CRITERION

A criterion that will return all members of the TARGET_CLASS

DEFAULT_RECON_DISPLAY_CHOICE
LANGUAGE_BAT
LANGUAGE_PSH
LANGUAGE_VBS

When the platform is Windows, what languages can be user?

OBJECT_HISTORY_OBJECT_TYPE

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

PLATFORMS
PLATFORM_MAC

When the intput type is script, what platforms can they run on?

PLATFORM_WINDOWS
RECON_DISPLAY_CHOICES

Where can it be displayed in the Recon App?

RSRC_BASE

The base for REST resources of this class

RSRC_LIST_KEY

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

RSRC_OBJECT_KEY

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

TARGET_CLASS

This class represents a Computer in the JSS.

Adding Computers to the JSS

At the moment, this class cannot be used to add new Computers to the JSS. Please use other methods (like the Recon App or QuickAdd package)

Editing values

Any data that arrives in the JSS via an “inventory update” (a.k.a. ‘recon’) cannot be modified through this class, or the API.

Data that can be modified are:

  • Management Account (see set_management_to)

  • asset_tag

  • barcodes 1 and 2

  • ip_address

  • udid

  • mac_address & alt_mac_address

  • serial_number Note: Even tho the webUI doesn’t allow editing the serial_number, the API does, and it can be useful for dealing with duplicates that arise when a logic-board swap causes a new computer record. to be created.

  • location data via the Locatable module

  • purchasing data via the Purchasable module

  • Extension Attribute values via the Extendable module Note: as with other ‘recon’ generated values, Ext. Attrs. populated by scripts cannot be modified via the API. (the change would be overwritten the next time the machine did a recon)

After making any changes, you must call update to send those changes to the server.

MDM Commands

See the {Jamf::MDM} mixin module for Class and Instance methods for sending MDM commands to computers.

To send MDM commands without fetching Computer instances, use the class methods, which can take multiple computer identifiers at once.

NOTE: the poorly named ‘UnmanageDevice’ mdm command is implemented as {#remove_mdm_profile} (which is its name in the webUI) as well as {#unmanage_device}. Calling that method will NOT fully unmanage a computer from the JSS’s point of view, it will just remove the mdm management profile from the machine and all configuration profiles that were installed via the JSS. Those profiles may be re-installed automatically later if the computer is still in scope for them

To properly unmanage a computer, use the {#make_unmanaged} Instance method which removes the mdm profile, but also makes the machine unmanged by the JSS, setting the management acct to nil, and requring re-enrollment.

Management History & Logs

Computer Management History and logs can now be retrieved both from a Computer instance, and directly via class methods without fetching an instance. This is handled by the mixed-in {Jamf::ManagementHistory} module, Q.V. for details.

Appication Usage History

Computer Instances now have access to their Application Usage history via the {#application_usage} method. Call the method with a start-date value (either a String or a Time object) and an optional end-date value. If you omite the end-date, the start-date is used and you’ll see usage for just that day.

See {#application_usage} for details about the data returned.

NOTE: your JSS must be gathering Appication Usage data in order for any data to be returned, and the usage history will only go back as far as your setting for flushing of Application Usage Logs.

Management Data

The computers ‘manamgement data’, as presented on the ‘Management’ tab of the computer’s detail page in the JSS web UI, is available from the {#management_data} method. That method may return a large dataset, unless a subset is requested.

Subsets of management data have their own methods, which are faster and only retrieve the subset requested. See {#smart_groups}, {#static_groups}, {#policies}, {#configuration_profiles}, {#ebooks}, {#app_store_apps}, {#restricted_software}, and {#patch_titles}

The subset methods can take an ‘only:’ parameter, which is a symbol specifying the value you care to see. For example {#smart_groups} returns an array of hashes, one for each smart_group the computer is in. Those hashes have two keys, :name, and :id. However if you only want an array of names, you can call ‘smart_groups only: :name`

When any of the manamgement data methods are used the first time, the data is read from the API and cached internally, the cache is then used for all future calls. To re-read the data from the API and re-cache it, provide ‘refresh: true` to any of the manamgement data methods.

Other Methods

  • {#set_management_to} change the management acct and passwd for this computer, aliased to make_managed

    • requires calling update to push changes to the server

  • {#make_unmanaged} an shortcut method for {#set_management_to}(nil)

    • requires calling update to push changes to the server

  • {#apps} a shortcut to {#software} [:applications]

  • {#licensed_sw} a shortcut to {#software} [:licensed_software]

  • {#computer_groups} a shortcut to {#groups_accounts} [:computer_group_memberships]

  • {#local_accounts} a shortcut to {#groups_accounts} [:local_accounts]

  • {#drives} a shortcut to {#hardware} [:storage]

  • {#printers} a shortcut to {#hardware} [:mapped_printers]

@see APIObject @see Locatable @see Purchasable @see Matchable @see FileUpload

WINDOWS_SCRIPTING_LANGUAGES

Attributes

code[R]

@return [String] the script code that will be executed when the @input_type is “script”,

enabled[R]

@return [Boolean] if the input type is ‘script’, is this EA enabled?

enabled?[R]

@return [Boolean] if the input type is ‘script’, is this EA enabled?

platform[R]

When the @input_type is “script”, The platform on which a script will run.

NOTE: The web app seems to let you have both Mac and Windows scripts defined when the type is “script”, however the API will only return the Mac script info if both are defined. DEPRECATED: windows EAs are no longer supported

@return [String]

recon_display[R]

DEPRECATED: this is no longer separate from the web_display. @return [String] In which part of the Recon App does the data appear?

script[R]

@return [String] the script code that will be executed when the @input_type is “script”,

scripting_language[R]

The scripting language of the @script when @input_type is “script”, and the @platform is “Windows”

DEPRECATED: windows EAs are no longer supported @return [String]

Public Instance Methods

code=(new_val)
Alias for: script=
disable() click to toggle source

disable this script ea

@return [void]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
143 def disable
144   return unless enabled?
145 
146   @enabled = false
147   @need_to_update = true
148 end
enable() click to toggle source

enable this script ea

@return [void]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
132 def enable
133   return if enabled?
134 
135   @enabled = true
136   @need_to_update = true
137 end
history(computer) click to toggle source

Return an Array of Hashes showing the history of reported values for this EA on one computer.

Each hash contains these 2 keys:

  • :value - String, Integer, or Time, depending on @data_type

  • :timestamp - Time

This method requires a MySQL database connection established via Jamf::DB_CNX.connect

@see Jamf::DBConnection

@param computer the id or name of the Computer.

@return [Array<Hash{:timestamp=>Time,:value=>String,Integer,Time}>]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
222     def history(computer)
223       raise Jamf::NoSuchItemError, "EA Not In JSS! Use #create to create this #{RSRC_OBJECT_KEY}." unless @in_jss
224       raise Jamf::InvalidConnectionError, "Database connection required for 'history' query." unless Jamf::DB_CNX.connected?
225 
226       computer_id = Jamf::Computer.valid_id computer, cnx: @cnx
227       raise Jamf::NoSuchItemError, "No computer found matching '#{computer}'" unless computer_id
228 
229       the_query = <<-END_Q
230       SELECT eav.value_on_client AS value, r.date_entered_epoch AS timestamp_epoch
231       FROM extension_attribute_values eav JOIN reports r ON eav.report_id = r.report_id
232       WHERE r.computer_id = #{computer_id}
233         AND eav.extension_attribute_id = #{@id}
234       ORDER BY timestamp_epoch
235       END_Q
236 
237       qrez = Jamf::DB_CNX.db.query the_query
238       history = []
239 
240       qrez.each_hash do |entry|
241         value =
242           case @data_type
243           when 'String' then entry['value']
244           when 'Integer' then entry['value'].to_i
245           when 'Date' then Jamf.parse_time(entry['value'])
246           end # case
247         newhash = { value: value, timestamp: JSS.epoch_to_time(entry['timestamp_epoch']) }
248         history << newhash
249       end # each hash
250 
251       history
252     end
platform=(new_val) click to toggle source

DEPRECATED: windows EAs are no longer supported

Change the platform of this EA. Setting this automatically sets input_type to script

@param new_val the new value, which must be a member of PLATFORMS

@return [void]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
177 def platform=(new_val)
178   return if @platform == new_val
179   raise Jamf::InvalidDataError, "platform must be a string, one of: #{PLATFORMS.join(', ')}" unless PLATFORMS.include? new_val
180 
181   self.input_type = INPUT_TYPE_SCRIPT
182   @platform = new_val
183   @need_to_update = true
184 end
recon_display=(new_val) click to toggle source

Change the recon_display of this EA DEPRECATED, no longer separate from web_display in jamf pro.

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
120 def recon_display=(new_val)
121   return if @recon_display == new_val
122   raise Jamf::InvalidDataError, "recon_display must be a string, one of: #{RECON_DISPLAY_CHOICES.join(', ')}" unless RECON_DISPLAY_CHOICES.include? new_val
123 
124   @recon_display = new_val
125   @need_to_update = true
126 end
script=(new_val) click to toggle source

Change the script of this EA. Setting this automatically sets input_type to script

@param new_val the new value

@return [void]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
157 def script=(new_val)
158   return if @script == new_val
159 
160   Jamf::Validate.non_empty_string new_val
161 
162   self.input_type = INPUT_TYPE_SCRIPT
163   @script = new_val
164   @need_to_update = true
165 end
Also aliased as: code=
scripting_language=(new_val) click to toggle source

Change the scripting_language of this EA. Setting this automatically sets input_type to ‘script’ and the platform to “Windows”

DEPRECATED: windows EAs are no longer supported

@param new_val the new value, which must be one of {WINDOWS_SCRIPTING_LANGUAGES}

@return [void]

    # File lib/jamf/api/classic/api_objects/computer_extension_attribute.rb
196 def scripting_language=(new_val)
197   return if @scripting_language == new_val
198   unless WINDOWS_SCRIPTING_LANGUAGES.include? new_val
199     raise Jamf::InvalidDataError, "Scripting language must be a string, one of: #{WINDOWS_SCRIPTING_LANGUAGES.join(', ')}"
200   end
201 
202   self.input_type = INPUT_TYPE_SCRIPT
203   self.platform = 'Windows'
204   @scripting_language = new_val
205   @need_to_update = true
206 end