class Jamf::Computer

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:

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

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

Constants

APPLICATION_USAGE_DATE_FMT

The date format for retrieving usage data

APPLICATION_USAGE_KEY

The top-level hash key of the raw app usage data

APPLICATION_USAGE_RSRC

The API resource for app usage

BOOT_FLAG

Boot partitions are noted with the string “(Boot Partition)” at the end

CHECKIN_KEY

The top-level hash key for the checkin settings

CHECKIN_RSRC

The API Resource for the computer checkin settings

COMPUTER_APPLICATIONS_RSRC
EXT_ATTRIB_CLASS

This is the class for relevant Extension Attributes

INV_COLLECTION_KEY

The top-level hash key for the inventory collection settings

INV_COLLECTION_RSRC

The API Resource for the computer inventory collection settings

JPAPI_INVENTORY_DETAIL_RSRC

The resource for getting all inventory data for a computer at once

JPAPI_INVENTORY_RSRC

The base resource for computer data in the JPAPI

LIST_RSRC

The (temporary?) list-resource

MDM_COMMAND_TARGET

Tell the MDM module what kind of MDM commands we use.

MGMT_DATA_KEY

The top-level hash key of the computer_management data

MGMT_DATA_RSRC

The API resource for computer_management data

MGMT_DATA_SUBSETS

Thes are both the subset names in the resrouce URLS (when converted to strings) and the second-level hash key of the returned subset data.

NON_UNIQUE_NAMES
OBJECT_HISTORY_OBJECT_TYPE

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

OTHER_LOOKUP_KEYS

these keys, as well as :id and :name, can be used to look up objects of this class in the JSS

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

SEARCH_CLASS

An AdvancedComputerSearch in the JSS

@see Jamf::AdvancedSearch

@see Jamf::APIObject

SITE_SUBSET

Where is the Site data in the API JSON?

UPLOAD_TYPES

file uploads can send attachments to the JSS using :computers as the sub-resource.

Attributes

alt_mac_address[R]

@return [String] the secondary mac address

alt_macaddress[R]

@return [String] the secondary mac address

asset_tag[R]

@return [String] the asset tag

bar_code_1[R]

@return [String] the barcodes

bar_code_2[R]

@return [String] the barcodes

barcode1[R]

@return [String] the barcodes

barcode2[R]

@return [String] the barcodes

barcode_1[R]

@return [String] the barcodes

barcode_2[R]

@return [String] the barcodes

certificates[R]

@return [Array<Hash>]

A Hash for each Certificate on the computer

The Hash keys are:

  • :common_name [String] the name of the cert

  • :identity [Boolean] Is this an identiry cert?

  • :expires [Time] the certificate expiration time

  • :name Display name for the certificate, if any

configuration_profiles[R]

@return [Array<Hash>]

A Hash for each ConfigurationProfile on the computer

The Hash keys are:

distribution_point[R]

@return [String] The name of the distribution point for this computer

enrolled_via_ade[R]

@return [Boolean] was the last enrollment via ADE/DEP

enrolled_via_ade?[R]

@return [Boolean] was the last enrollment via ADE/DEP

enrolled_via_dep[R]

@return [Boolean] was the last enrollment via ADE/DEP

enrolled_via_dep?[R]

@return [Boolean] was the last enrollment via ADE/DEP

groups_accounts[R]

@return [Hash]

Info about the local accts and ComputerGroups to which this machine beloings

The Hash keys are:

  • :computer_group_memberships => An Array of names of ComputerGroups to which this computer belongs

  • :local_accounts => An Array of Hashes for each local user acct on this computer. Each hash has these keys:

    • :name => String, the login name of the acct

    • :realname => the real name of the acct

    • :uid => String, the uid of the acct

    • :home => String, the path to the home folder

    • :home_size => String, the size of the homedir as a string like “53245MB”

    • :home_size_mb => Integer, the size of the homedir as an integer like 53245

    • :administrator => Boolean

    • :filevault_enabled => Boolean

hardware[R]

@return [Hash]

A Hash with info about the hardware of this cmoputer.

These are the keys & sample data

  • :number_processors=>2,

  • :processor_speed_mhz=>2530,

  • :make=>“Apple”,

  • :cache_size=>3072,

  • :processor_type=>“Intel Core i5”,

  • :total_ram_mb=>8192,

  • :model=>“15-inch MacBook Pro (Mid 2010)”,

  • :available_ram_slots=>0,

  • :processor_architecture=>“i386”,

  • :bus_speed_mhz=>0,

  • :total_ram=>8192,

  • :os_name=>“Mac OS X”,

  • :optical_drive=>“HL-DT-ST DVDRW GS23N”,

  • :model_identifier=>“MacBookPro6,2”,

  • :cache_size_kb=>3072,

  • :boot_rom=>“MBP61.0057.B0F”,

  • :os_version=>“10.9.3”,

  • :mapped_printers=> An Array of Hashes, one per printer, with these keys

    • :name => the name of the printer

    • :location => the location of the printer

    • :type => the printer model

    • :uri => the uri to reach the printer on the network

  • :nic_speed=>“10/100/1000”,

  • :processor_speed=>2530,

  • :active_directory_status=>“Not Bound”,

  • :bus_speed=>0,

  • :os_build=>“13D65”,

  • :smc_version=>“1.58f17”,

  • :service_pack=>“”,

  • :battery_capacity=>87

  • :storage=> An Array of Hashes, one per Drive, with these keys

    • :smart_status=>“Verified”,

    • :connection_type=>“NO”,

    • :model=>“M4-CT256M4SSD2”,

    • :revision=>“040H”,

    • :serial_number=>“00000000130709JH7GhhC”,

    • :size=>262205,

    • :disk=>“disk0”,

    • :drive_capacity_mb=>262205}],

    • :partition=> A Hash with these keys

      • :filevault2_status=>“Encrypted”,

      • :type=>“boot”,

      • :filevault2_percent=>100,

      • :partition_capacity_mb=>38014,

      • :lvgUUID=>“C4883AF5-3E58-4F76-A56C-094D4CEC7E9F”,

      • :percentage_full=>61,

      • :lvUUID=>“745A262E-AEA6-4608-8A3A-6CDC225B4DE6”,

      • :filevault_status=>“Encrypted”,

      • :size=>38014,

      • :pvUUID=>“C38051CF-5066-442F-A442-1035060ED462”,

      • :name=>“KimDrive40 (Boot Partition)”,

      • :filevault_percent=>100

initial_entry_date[R]

@return [Time] when was it added to the JSS

ip_address[R]

@return [IPAddr] the last known IP address from the server’s perspective

itunes_store_account_is_active[R]

@return [Boolean]

jamf_version[R]

@return [String] the version of the jamf binary

last_contact_time[R]

@return [Time] the last contact time

last_enrolled[R]

@return [Time] the last time this machine was enrolled

last_recon[R]

@return [Time] the last recon time

mac_address[R]

@return [String] the primary macaddress

managed[R]

@return [Boolean] is this machine “managed” by Casper?

managed?[R]

@return [Boolean] is this machine “managed” by Casper?

management_status[R]

@return [Hash] some MDM status details in general

management_username[R]

@return [String] the name of the management account

mdm?[R]

@return [Boolean] doesit support MDM?

mdm_capable[R]

@return [Boolean] doesit support MDM?

mdm_capable?[R]

@return [Boolean] doesit support MDM?

mdm_capable_users[R]

@return [Array] user accts that support MDM?

NOTE: This suffers from the JSON-Hash-treated-like_XML-Array-loses-data
bug and only shows the last listed user, cuz it comes from the API
as a hash, not an array.
mdm_profile_expiration[R]

@return [Time] when does the mdm profile expire

netboot_server[R]

@return [String] the name of the netboot server for this machine

peripherals[R]

@return [Array<Hash>]

A Hash per peripheral

Each hash has these keys & sample data:

  • :id=>286,

  • :type=>“Display”,

  • :field_0=>“HP”,

  • :field_1=>“HP LP2480zx”,

  • :field_2=>“DreamColor”,

  • :field_3=>“3CM10800F4”,

  • :field_4=>“”,

  • :field_5=>“”

  • :field_6=>“”,

  • :bar_code_1=>“”,

  • :bar_code_2=>“”,

  • :purchasing=> A hash with these keys:

    • :warranty_expires_utc=>“”,

    • :is_leased=>false,

    • :po_date=>“”,

    • :lease_expires=>“”,

    • :po_number=>“”,

    • :po_date_epoch=>0,

    • :lease_expires_epoch=>0,

    • :vendor=>“”,

    • :attachments=>[],

    • :po_date_utc=>“”,

    • :lease_expires_utc=>“”,

    • :applecare_id=>“”,

    • :warranty_expires=>“”,

    • :life_expectancy=>0,

    • :purchase_price=>“”,

    • :warranty_expires_epoch=>0,

    • :is_purchased=>true,

    • :purchasing_contact=>“”,

    • :purchasing_account=>“”

platform[R]

@return [String] what kind of computer?

report_date[R]

@return [Time] the last recon time

reported_ip_address[R]

@return [IPAddr] the last known IP address from the client’s perspecive

security[R]

@return [Hash] The security settings for this Computer

Keys are:
activation_lock:  Boolean
recovery_lock_enabled: Boolean
secure_boot_level: String
external_boot_level: String
firewall_enabled: Boolean
serial_number[R]

@return [String] the serial number

serialnumber[R]

@return [String] the serial number

site[R]

@return [Hash] the :name and :id of the site for this machine

sn[R]

@return [String] the serial number

software[R]

@return [Hash]

A Hash of software data

The Hash has these keys:

  • :running_services => An Array of services running on the computer (if gathered) TODO - is each item a hash?

  • :installed_by_casper => An Array of Package names unstalled on this computer by Casper

  • :fonts => An Array of fonts on this computer (if gathered) TODO - is each item a hash?

  • :installed_by_installer_swu => An Array of pkg IDs for pkgs installed by SoftwareUpdate or the Apple Installer

  • :applications => An Array of Hashes, one per Application on the computer, with these keys:

    • :path => String, the path to the app

    • :name => String, the name of the app, including the .app suffix

    • :version => String, the version of the app at that path.

  • :cached_by_casper => An Array of Casper Package names cached on the machine, awaiting installation

  • :available_software_updates => An Array of available SoftwareUpdate (if gathered) TODO - is each item a hash?

  • :plugins => An Array of plugins installed on the machine (if gathered) TODO - is each item a hash?

  • :available_updates => A Hash - Deprecated?

  • :licensed_software => An Array, the names of Licenced Software (as defined in Casper) on this machine

  • :unix_executables => DEPRECATED

supervised[R]

@return [Boolean] Is it supervised?

supervised?[R]

@return [Boolean] Is it supervised?

sus[R]

@return [String] the name of the Software Update Server assigned to this machine.

udid[R]

@return [String] the UDID of the computer

user_approved_enrollment[R]

@return [Boolean] was enrollment user-approved

user_approved_enrollment?[R]

@return [Boolean] was enrollment user-approved

user_approved_mdm[R]

@return [Boolean] was MDM user-approved (meaning the User authorized the MDM profile)

user_approved_mdm?[R]

@return [Boolean] was MDM user-approved (meaning the User authorized the MDM profile)

Public Class Methods

all(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

A larger set of info about the computers in the JSS.

Casper 9.4 introduced the API Resource /computers/subset/basic that returns an array of hashes with more data than just /computers/ (which was just :name and :id). Similar to /mobildevices/, this new list includes :udid, :serial_number, and :mac_address, as well as :model, :managed, :building, :department, :username, and :report_date

Because this requires a different, unusual, resource path, we’re completely re-defining {APIObject.all} for Jamf::Computer. Hopefully some day the original /computers/ resource will be updated to return this data.

@param refresh should the data be re-queried from the API?

@param cnx an API connection to use for the query.

Defaults to the corrently active API. See {Jamf::Connection}

@return [Array<Hash{:name=>String, :id=> Integer}>]

    # File lib/jamf/api/classic/api_objects/computer.rb
333 def self.all(refresh = false, api: nil, cnx: Jamf.cnx)
334   cnx = api if api
335 
336   cache = cnx.c_object_list_cache
337   cache_key = self::RSRC_LIST_KEY
338   cache[cache_key] = nil if refresh
339   return cache[cache_key] if cache[cache_key]
340 
341   cache[cache_key] = cnx.c_get(self::LIST_RSRC)[cache_key]
342 end
all_desktops(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all desktop macs in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
394 def self.all_desktops(refresh = false, api: nil, cnx: Jamf.cnx)
395   cnx = api if api
396 
397   all(refresh, cnx: cnx).reject { |d| d[:model] =~ /serve|book/i }
398 end
all_imacs(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all imacs in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
401 def self.all_imacs(refresh = false, api: nil, cnx: Jamf.cnx)
402   cnx = api if api
403 
404   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^imac/i }
405 end
all_laptops(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all laptop computers in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
359 def self.all_laptops(refresh = false, api: nil, cnx: Jamf.cnx)
360   cnx = api if api
361 
362   all(refresh, cnx: cnx).select { |d| d[:model] =~ /book/i }
363 end
all_macbookairs(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all macbookairs in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
380 def self.all_macbookairs(refresh = false, api: nil, cnx: Jamf.cnx)
381   cnx = api if api
382 
383   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^macbookair\d/i }
384 end
all_macbookpros(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all macbookpros in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
373 def self.all_macbookpros(refresh = false, api: nil, cnx: Jamf.cnx)
374   cnx = api if api
375 
376   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^macbookpro\d/i }
377 end
all_macbooks(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all macbooks in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
366 def self.all_macbooks(refresh = false, api: nil, cnx: Jamf.cnx)
367   cnx = api if api
368 
369   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^macbook\d/i }
370 end
all_macpros(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all macpros in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
415 def self.all_macpros(refresh = false, api: nil, cnx: Jamf.cnx)
416   cnx = api if api
417 
418   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^macpro/i }
419 end
all_managed(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all managed computers in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
345 def self.all_managed(refresh = false, api: nil, cnx: Jamf.cnx)
346   cnx = api if api
347 
348   all(refresh, cnx: cnx).select { |d| d[:managed] }
349 end
all_minis(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all mac minis in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
408 def self.all_minis(refresh = false, api: nil, cnx: Jamf.cnx)
409   cnx = api if api
410 
411   all(refresh, cnx: cnx).select { |d| d[:model] =~ /^macmini/i }
412 end
all_unmanaged(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all unmanaged computers in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
352 def self.all_unmanaged(refresh = false, api: nil, cnx: Jamf.cnx)
353   cnx = api if api
354 
355   all(refresh, cnx: cnx).reject { |d| d[:managed] }
356 end
all_xserves(refresh = false, api: nil, cnx: Jamf.cnx) click to toggle source

@return [Array<Hash>] all xserves in the jss

    # File lib/jamf/api/classic/api_objects/computer.rb
387 def self.all_xserves(refresh = false, api: nil, cnx: Jamf.cnx)
388   cnx = api if api
389 
390   all(refresh, cnx: cnx).select { |d| d[:model] =~ /serve/i }
391 end
application_installs(appname, fields: [], version: nil, ids_only: false, api: nil, cnx: Jamf.cnx) click to toggle source

Query the JSS for computers with some app installed. An app name is required as the first parameter.

If no other parameters are given, returns a Hash, one key per version of the app. For each version there is an array of Hashes, one Hash for each computer with that version. The sub hashes contain keys for the computer’s identifiers, i.e. :name, :id, :udid, :serial_number, :mac_address.

If one or more inventory fields are provided in the ‘fields’ parameter, each computer’s hash also has keys and values for those fields if they exist in the JSS. These fields are those available in the display options for Advanced Computer Searches (including extention attribute names) and their names are case-sensitive, so ‘Username’, not ‘username’

If a specific version is provided in the ‘version’ parameter, only computers containing that version of the app are returned as an Array of Hashes.

If the ids_only parameter is truthy, an Array of JSS id numbers for computers with this app is returned. In this case the ‘fields’ parameter is ignored, however the ‘version’ parameters is still valid and will restrict the list to those computer ids with that version installed.

This method implements the ‘computerapplications’ API endpoint.

NOTE: To see all the apps installed on a specific computer, fetch the Jamf::Computer instance and call its {Jamf::Computer#apps} method.

@param appname [String] The name of the app to look for, e.g. ‘Transmogrifier.app’

@param fields [String,Array<String>] Additional ‘inventory fields’ to return

with each computer's data

@param version [String] Limit search to a specific version of the app

@param ids_only [Boolean] Just return an array of the id’s of computers

found with this query. Defaults to false

@param cnx [Jamf::Connection] The API connection to use for the query.

default: Jamf.cnx

@return [Array<Integer>] When ids_only == true, the ids of computers with

the app installed (possibly limited to version)

@return [Array<Hash>] When version is provided, An Array of Hashes, one

for each computer, with keys for identifiers plus any requested fields.

@return [Hash{String => Array<Hash>}] When no version is provided, a Hash

with keys for each version, pointing to an array of Hashes, one for
each computer with that version. Each computer's Hash has keys for
identifiers plus any requested fields.
    # File lib/jamf/api/classic/api_objects/computer.rb
524 def self.application_installs(appname, fields: [], version: nil, ids_only: false, api: nil, cnx: Jamf.cnx)
525   cnx = api if api
526 
527   fields = [fields] unless fields.is_a? Array
528 
529   rsrc = "#{COMPUTER_APPLICATIONS_RSRC}/#{CGI.escape appname.to_s}"
530   rsrc << "/version/#{CGI.escape version.to_s}" if version
531   rsrc << "/inventory/#{CGI.escape fields.join(',')}" unless ids_only || fields.empty?
532 
533   result = cnx.c_get(rsrc)[:computer_applications]
534 
535   return result[:unique_computers].map { |c| c[:id] } if ids_only
536 
537   if version.nil?
538     hash_by_version = {}
539     result[:versions].each { |v| hash_by_version[v[:number]] = v[:computers] }
540     return hash_by_version
541   end
542 
543   result[:versions].first[:computers]
544 end
application_usage(ident, start_date, end_date = nil, api: nil, cnx: Jamf.cnx) click to toggle source

Retrieve Application Usage data for a computer by id, without instantiation.

@param ident [Integer,String] An identifier (id, name, serialnumber,

macadress or udid) of the computer for which to retrieve Application Usage

@param start_date [Time,Date,DateTime,String] The earliest date to retrieve

@param end_date [String,Date,DateTime,Time] Defaults to start_date

@param cnx [Jamf::Connection] an API connection to use for the query.

Defaults to the corrently active API. See {Jamf::Connection}

@return [Hash{Date=>Array<Hash>}] A Hash with keys (Date instances) for

each day in the range.

Each hash value contains an Array of apps used
on that day.

Each item in the array is a hash of data about the app.
Those hash keys are:
  :name => String, the name of the app
  :version => String ,the version of the app
  :foreground => Integer, the minutes it was in the foreground
  :open => Integer, the minutes it was running.
    # File lib/jamf/api/classic/api_objects/computer.rb
447 def self.application_usage(ident, start_date, end_date = nil, api: nil, cnx: Jamf.cnx)
448   cnx = api if api
449 
450   id = valid_id ident, cnx: cnx
451   raise Jamf::NoSuchItemError, "No computer matches identifier: #{ident}" unless id
452 
453   end_date ||= start_date
454   start_date = Jamf.parse_time start_date
455   end_date = Jamf.parse_time end_date
456 
457   start_date = start_date.strftime APPLICATION_USAGE_DATE_FMT
458   end_date = end_date.strftime APPLICATION_USAGE_DATE_FMT
459 
460   data = cnx.c_get(APPLICATION_USAGE_RSRC + "/id/#{id}/#{start_date}_#{end_date}")
461 
462   parsed_data = {}
463 
464   data[APPLICATION_USAGE_KEY].each do |day_hash|
465     date = Date.parse day_hash[:date]
466     parsed_data[date] = day_hash[:apps]
467   end
468 
469   parsed_data
470 end
checkin_settings(api: nil, cnx: Jamf.cnx) click to toggle source

Display the current Computer CheckIn settings in the JSS. Currently this is read-only in ruby-jss, even tho the API allows updating.

@param cnx [Jamf::Connection] an API connection to use for the query.

Defaults to the corrently active API. See {Jamf::Connection}

@return [Hash] the Computer Checkin Settings from the

currently connected JSS.
    # File lib/jamf/api/classic/api_objects/computer.rb
294 def self.checkin_settings(api: nil, cnx: Jamf.cnx)
295   cnx = api if api
296   cnx.c_get(CHECKIN_RSRC)[CHECKIN_KEY]
297 end
inventory_collection_settings(api: nil, cnx: Jamf.cnx) click to toggle source

Display the current Computer Inventory Collection settings in the JSS. Currently this is read-only in ruby-jss, even tho the API allows updating.

@param cnx [Jamf::Connection] an API connection to use for the query.

Defaults to the corrently active API. See {Jamf::Connection}

@return [Hash] the Computer Inventpry Collection Settings from the

currently connected JSS.
    # File lib/jamf/api/classic/api_objects/computer.rb
309 def self.inventory_collection_settings(api: nil, cnx: Jamf.cnx)
310   cnx = api if api
311   cnx.c_get(INV_COLLECTION_RSRC)[INV_COLLECTION_KEY]
312 end
management_data(ident, subset: nil, only: nil, api: nil, cnx: Jamf.cnx) click to toggle source

The ‘computer management’ data for a given computer by id, looked up on the fly.

Without specifying a subset:, the entire dataset is returned as a hash of arrays, one per subset

If a subset is given then only that array is returned, and it contains hashes with data about each item (usually :name and :id)

If the only: param is provided with a subset, it is used as a hash-key to map the array to just those values, so subset: :smart_groups, only: :name will return an array of names of smartgroups that contain the computer.

@param ident [Integer,String] An identifier (id, name, serialnumber,

macadress or udid) of the computer for which to retrieve Application Usage

@param subset Fetch only a subset of data, as an array.

must be one of the symbols in MGMT_DATA_SUBSETS

@param only When fetching a subset, only return one value

per item in the array. meaningless without a subset.

@param cnx [Jamf::Connection] an API connection to use for the query.

Defaults to the corrently active API. See {Jamf::Connection}

@return [Hash] Without a subset:, a hash of all subsets, each of which is

an Array

@return [Array] With a subset:, an array of items in that subset, possibly

limited to just certain values with only:
    # File lib/jamf/api/classic/api_objects/computer.rb
577 def self.management_data(ident, subset: nil, only: nil, api: nil, cnx: Jamf.cnx)
578   cnx = api if api
579 
580   id = valid_id ident, cnx: cnx
581   raise "No computer matches identifier: #{ident}" unless id
582 
583   if subset
584     management_data_subset id, subset: subset, only: only, cnx: cnx
585   else
586     full_management_data id, cnx: cnx
587   end
588 end
new(**args) click to toggle source

@param (see APIObject#initialize)

# When creating new records with .make, these can be provided in the arg, or after instantiation via setter methods:

serial_number:, udid:, asset_tag:, mac_address:
alt_mac_address:, barcode_1:, barcode_2:
Calls superclass method Jamf::APIObject::new
    # File lib/jamf/api/classic/api_objects/computer.rb
907 def initialize(**args)
908   super
909   if @in_jss
910 
911     # mutable stuff
912     @alt_mac_address = @init_data[:general][:alt_mac_address]
913     @asset_tag = @init_data[:general][:asset_tag]
914     @barcode1 = @init_data[:general][:barcode_1]
915     @barcode2 = @init_data[:general][:barcode_2]
916     @mac_address = @init_data[:general][:mac_address]
917     @managed = @init_data[:general][:remote_management][:managed]
918     @management_username = @init_data[:general][:remote_management][:management_username]
919     @serial_number = @init_data[:general][:serial_number]
920     @udid = @init_data[:general][:udid]
921 
922     # immutable single-values
923     @distribution_point = @init_data[:general][:distribution_point]
924     @initial_entry_date = JSS.epoch_to_time @init_data[:general][:initial_entry_date_epoch]
925     @last_enrolled = JSS.epoch_to_time @init_data[:general][:last_enrolled_date_epoch]
926 
927     @management_status = @init_data[:general][:management_status]
928     if @management_status
929       @enrolled_via_dep = @management_status[:enrolled_via_dep]
930       @user_approved_enrollment = @management_status[:user_approved_enrollment]
931       @user_approved_mdm = @management_status[:user_approved_mdm]
932     end
933 
934     @ip_address = @init_data[:general][:ip_address]
935     @reported_ip_address = @init_data[:general][:last_reported_ip]
936     @itunes_store_account_is_active = @init_data[:general][:itunes_store_account_is_active]
937     @jamf_version = @init_data[:general][:jamf_version]
938     @last_contact_time = JSS.epoch_to_time @init_data[:general][:last_contact_time_epoch]
939 
940     @mdm_capable = @init_data[:general][:mdm_capable]
941     @mdm_capable_users = @init_data[:general][:mdm_capable_users].values
942     @supervised = @init_data[:general][:supervised]
943     @mdm_profile_expiration = JSS.epoch_to_time @init_data[:general][:mdm_profile_expiration_epoch]
944 
945     @netboot_server = @init_data[:general][:netboot_server]
946     @platform = @init_data[:general][:platform]
947     @report_date = JSS.epoch_to_time @init_data[:general][:report_date_epoch]
948     @sus = @init_data[:general][:sus]
949 
950     @security = @init_data[:security] || {}
951 
952     @configuration_profiles = @init_data[:configuration_profiles]
953 
954     @groups_accounts = @init_data[:groups_accounts]
955     @hardware = @init_data[:hardware]
956     @peripherals = @init_data[:peripherals]
957     @software = @init_data[:software]
958     @certificates = @init_data[:certificates].map do |cert|
959       {
960         expires: JSS.epoch_to_time(cert[:expires_epoch]),
961         common_name: cert[:common_name],
962         identity: cert[:identity],
963         name: cert[:name]
964       }
965     end # map do cert
966 
967     # Freeze immutable things.
968     # These are updated via recon, and aren't sent
969     # with #update, so changing them here is meaningless anyway.
970     @configuration_profiles.freeze
971     @certificates.freeze
972     @groups_accounts.freeze
973     @hardware.freeze
974     @peripherals.freeze
975     @software.freeze
976 
977     @management_password = nil
978 
979   # not in jss
980   else
981     @udid = args[:udid]
982     @serial_number = args[:serial_number]
983     @asset_tag = args[:asset_tag]
984     @mac_address = args[:mac_address]
985     @alt_mac_address = args[:alt_mac_address]
986     @barcode1 = args[:barcode_1]
987     @barcode2 = args[:barcode_2]
988   end # if in jss
989 end

Private Class Methods

full_management_data(id, api: nil, cnx: Jamf.cnx) click to toggle source

The full set of management data for a given computer. This private method is called by self.management_data, q.v.

    # File lib/jamf/api/classic/api_objects/computer.rb
593 def self.full_management_data(id, api: nil, cnx: Jamf.cnx)
594   cnx = api if api
595 
596   mgmt_rsrc = MGMT_DATA_RSRC + "/id/#{id}"
597   cnx.c_get(mgmt_rsrc)[MGMT_DATA_KEY]
598 end
management_data_subset(id, subset: nil, only: nil, api: nil, cnx: Jamf.cnx) click to toggle source

A subset of management data for a given computer. This private method is called by self.management_data, q.v.

    # File lib/jamf/api/classic/api_objects/computer.rb
604 def self.management_data_subset(id, subset: nil, only: nil, api: nil, cnx: Jamf.cnx)
605   cnx = api if api
606 
607   raise "Subset must be one of :#{MGMT_DATA_SUBSETS.join ', :'}" unless MGMT_DATA_SUBSETS.include? subset
608 
609   subset_rsrc = MGMT_DATA_RSRC + "/id/#{id}/subset/#{subset}"
610   subset_data = cnx.c_get(subset_rsrc)[MGMT_DATA_KEY]
611   return subset_data[subset] unless only
612 
613   subset_data[subset].map { |d| d[only] }
614 end

Public Instance Methods

accounts()
Alias for: local_accounts
accts()
Alias for: local_accounts
alt_mac_address=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1257 def alt_mac_address=(new_val)
1258   return nil if new_val == @alt_mac_address
1259 
1260   @alt_mac_address = new_val.empty? ? new_val : Jamf::Validate.mac_address(new_val)
1261   @need_to_update = true
1262 end
app_store_apps(only: nil) click to toggle source

A shortcut for ‘management_data subset: :mac_app_store_apps’

     # File lib/jamf/api/classic/api_objects/computer.rb
1138 def app_store_apps(only: nil)
1139   management_data subset: :mac_app_store_apps, only: only
1140 end
application_usage(start_date, end_date = nil) click to toggle source

Get application usage data for this computer for a given date range. See {Jamf::Computer.application_usage} for details

     # File lib/jamf/api/classic/api_objects/computer.rb
1090 def application_usage(start_date, end_date = nil)
1091   Jamf::Computer.application_usage @id, start_date, end_date, cnx: @cnx
1092 end
apps() click to toggle source

@return [Array<Hash>] all apps installed on this machine.

Hash keys are :name, :path, and :version
     # File lib/jamf/api/classic/api_objects/computer.rb
1075 def apps
1076   @software[:applications]
1077 end
asset_tag=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1193 def asset_tag=(new_val)
1194   new_val =  new_val.to_s.strip
1195   return nil if @asset_tag.to_s == new_val
1196 
1197   @asset_tag = new_val
1198   @need_to_update = true
1199 end
bar_code_1=(new_val)
Alias for: barcode1=
bar_code_2=(new_val)
Alias for: barcode2=
barcode1=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1227 def barcode1=(new_val)
1228   new_val = new_val.strip
1229   return nil if @barcode1 == new_val
1230 
1231   @barcode1 = new_val
1232   @need_to_update = true
1233 end
Also aliased as: bar_code_1=, barcode_1=
barcode2=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1235 def barcode2=(new_val)
1236   new_val = new_val.strip
1237   return nil if @barcode2 == new_val
1238 
1239   @barcode2 = new_val
1240   @need_to_update = true
1241 end
Also aliased as: bar_code_2=, barcode_2=
barcode_1=(new_val)
Alias for: barcode1=
barcode_2=(new_val)
Alias for: barcode2=
boot_drive() click to toggle source

@return [Hash, nil] The hardware hash of the boot drive

     # File lib/jamf/api/classic/api_objects/computer.rb
1061 def boot_drive
1062   drives.select { |d| d[:partition] && d[:partition][:type] == 'boot' }.first
1063 end
computer_groups() click to toggle source

@return [Array] the JSS groups to which thismachine belongs (smart and static)

     # File lib/jamf/api/classic/api_objects/computer.rb
1027 def computer_groups
1028   @groups_accounts[:computer_group_memberships]
1029 end
delete() click to toggle source

Delete this computer from the JSS

@return [void]

Calls superclass method Jamf::APIObject::delete
     # File lib/jamf/api/classic/api_objects/computer.rb
1292 def delete
1293   super
1294   @alt_mac_address = nil
1295   @asset_tag = nil
1296   @barcode1 = nil
1297   @barcode2 = nil
1298   @distribution_point = nil
1299   @initial_entry_date = nil
1300   @ip_address = nil
1301   @jamf_version = nil
1302   @last_contact_time = nil
1303   @macaddress = nil
1304   @managed = nil
1305   @management_username = nil
1306   @mdm_capable = nil
1307   @netboot_server = nil
1308   @platform = nil
1309   @report_date = nil
1310   @serial_number = nil
1311   @site = nil
1312   @sus = nil
1313   @udid = nil
1314 
1315   @building = nil
1316   @department = nil
1317   @email_address = nil
1318   @phone = nil
1319   @position = nil
1320   @real_name = nil
1321   @room = nil
1322   @username = nil
1323 
1324   @configuration_profiles = nil
1325   @extension_attributes = nil
1326   @groups_accounts = nil
1327   @hardware = nil
1328   @peripherals = nil
1329   @purchasing = nil
1330   @software = nil
1331 end
drives() click to toggle source

@return [Array<Hash>] each storage device

     # File lib/jamf/api/classic/api_objects/computer.rb
1055 def drives
1056   @hardware[:storage]
1057 end
ebooks(only: nil) click to toggle source

A shortcut for ‘management_data subset: :ebooks’

     # File lib/jamf/api/classic/api_objects/computer.rb
1132 def ebooks(only: nil)
1133   management_data subset: :ebooks, only: only, refresh: refresh
1134 end
filevault1_accounts() click to toggle source

@return [Array<Hash>] The local_accounts Array that have Legacy FV enabled

     # File lib/jamf/api/classic/api_objects/computer.rb
1047 def filevault1_accounts
1048   return [] if filevault2_enabled?
1049 
1050   local_accounts.select { |a| a[:filevault_enabled] }
1051 end
filevault2_enabled?() click to toggle source

@return [Boolean] is FileVault2 enabled?

     # File lib/jamf/api/classic/api_objects/computer.rb
1041 def filevault2_enabled?
1042   boot_drive[:partition][:filevault2_status] != 'Not Encrypted'
1043 end
flush_policy_logs(older_than: 0, period: :days) click to toggle source

Flush all policy logs for this computer older than a given time period.

IMPORTANT: from the Jamf Developer Site:

The ability to flush logs is currently only supported for flushing all logs
for a given policy or all logs for a given computer. There is no support for
flushing logs for a given policy and computer combination.

With no parameters, will flush all logs for the computer

NOTE: Currently the API doesn’t have a way to flush only failed policies.

@param older_than 0, 1, 2, 3, or 6

@param period :days, :weeks, :months, or :years

@see Jamf::Policy.flush_logs_for_computers

     # File lib/jamf/api/classic/api_objects/computer.rb
1218 def flush_policy_logs(older_than: 0, period: :days)
1219   Jamf::Policy.flush_logs_for_computers(
1220     [@id],
1221     older_than: older_than,
1222     period: period,
1223     cnx: @cnx
1224   )
1225 end
ip_address=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1243 def ip_address=(new_val)
1244   return nil if @ip_address == new_val
1245 
1246   @ip_address = new_val.empty? ? new_val : Jamf::Validate.ip_address(new_val)
1247   @need_to_update = true
1248 end
licensed_sw() click to toggle source

@return [Array<String>] the JSS-defined “licensed software” titles

installed on this machine.
     # File lib/jamf/api/classic/api_objects/computer.rb
1082 def licensed_sw
1083   @software[:licensed_software]
1084 end
local_accounts() click to toggle source

@return [Array<Hash>] all the local accts on the machine.

Each item has keys :name, :realname, :uid, :home, :home_size, :administrator, :filevault_enabled

     # File lib/jamf/api/classic/api_objects/computer.rb
1035 def local_accounts
1036   @groups_accounts[:local_accounts]
1037 end
Also aliased as: accounts, accts
mac_address=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1250 def mac_address=(new_val)
1251   return nil if new_val == @mac_address
1252 
1253   @mac_address =  new_val.empty? ? new_val : Jamf::Validate.mac_address(new_val)
1254   @need_to_update = true
1255 end
make_managed(name, password)
Alias for: set_management_to
make_unmanaged() click to toggle source

Make the machine unmanaged.

The same as

#set_management_to nil, nil

followed by

Jamf::Computer.send_mdm_command @id, :unmanage_device

which currently isn’t working

@return [void]

     # File lib/jamf/api/classic/api_objects/computer.rb
1186 def make_unmanaged
1187   return nil unless managed?
1188 
1189   set_management_to(nil, nil)
1190   @unmange_at_update = true
1191 end
management_data(subset: nil, only: nil) click to toggle source

The ‘computer management’ data for this computer

NOTE: the data isn’t cached locally, and the API is queried every time

@see {Jamf::Computer.management_data} for details

     # File lib/jamf/api/classic/api_objects/computer.rb
1100 def management_data(subset: nil, only: nil)
1101   raise Jamf::NoSuchItemError, 'Computer not yet saved in the JSS' unless @in_jss
1102 
1103   Jamf::Computer.management_data @id, subset: subset, only: only, cnx: @cnx
1104 end
method_missing(method, *args, &block) click to toggle source

Make all the keys of the @hardware hash available as top-level methods on the Computer instance.

This is done by catching method_missing and seeing if the method exists as key of @hardware, and if so, retuning that value, if not, passing on the method_missing call. So:

comp.processor_type

is now the same as:

comp.hardware[:processor_type]

The reason for using ‘method_missing` rather than looping through the @hardware hash during initialization and doing `define_method` is speed. When instantiating lots of computers, defining the methods for each one, when those methods may not be needed, just slows things down. This way, they’re only used when needed.

This method may be expanded in the future to handle other ad-hoc, top-level methods.

Calls superclass method
     # File lib/jamf/api/classic/api_objects/computer.rb
1011 def method_missing(method, *args, &block)
1012   if @hardware.key? method
1013     @hardware[method]
1014   else
1015     super
1016   end # if
1017 end
patch_titles(only: nil) click to toggle source

A shortcut for ‘management_data subset: :patch_reporting_software_titles’

     # File lib/jamf/api/classic/api_objects/computer.rb
1150 def patch_titles(only: nil)
1151   management_data subset: :patch_reporting_software_titles, only: only
1152 end
policies(only: nil) click to toggle source

A shortcut for ‘management_data subset: :policies’

     # File lib/jamf/api/classic/api_objects/computer.rb
1120 def policies(only: nil)
1121   management_data subset: :policies, only: only
1122 end
printers() click to toggle source

@return [Array<Hash>] each printer on this computer

Keys are :name, :uri, :type, :location
     # File lib/jamf/api/classic/api_objects/computer.rb
1068 def printers
1069   @hardware[:mapped_printers]
1070 end
respond_to_missing?(method, *) click to toggle source

Companion to method_missing, allows for easier debugging in backtraces that involve missing methods.

Calls superclass method
     # File lib/jamf/api/classic/api_objects/computer.rb
1021 def respond_to_missing?(method, *)
1022   @hardware.key?(method) || super
1023 end
restricted_software(only: nil) click to toggle source

A shortcut for ‘management_data subset: :restricted_software’

     # File lib/jamf/api/classic/api_objects/computer.rb
1144 def restricted_software(only: nil)
1145   management_data subset: :restricted_software, only: only
1146 end
serial_number=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1264 def serial_number=(new_val)
1265   return nil if new_val == @serial_number
1266 
1267   @serial_number =  new_val.empty? ? new_val : Jamf::Validate.doesnt_already_exist(Jamf::Computer, :serial_number, new_val, cnx: cnx)
1268   @need_to_update = true
1269 end
set_management_to(name, password) click to toggle source

Set or unset management acct and password for this computer

@param name the name of the management acct.

@param password the password of the management acct

@return [void]

The changes will need to be pushed to the server with {#update} before they take effect.

CAUTION: this does nothing to confirm the name and password will work on the machine!

     # File lib/jamf/api/classic/api_objects/computer.rb
1168 def set_management_to(name, password)
1169   password = nil unless name
1170   @management_username = name
1171   @management_password = password
1172   @managed = name ? true : false
1173   @need_to_update = true
1174 end
Also aliased as: make_managed
smart_groups(only: nil) click to toggle source

A shortcut for ‘management_data subset: :smart_groups’

     # File lib/jamf/api/classic/api_objects/computer.rb
1108 def smart_groups(only: nil)
1109   management_data subset: :smart_groups, only: only
1110 end
static_groups(only: nil) click to toggle source

A shortcut for ‘management_data subset: :static_groups’

     # File lib/jamf/api/classic/api_objects/computer.rb
1114 def static_groups(only: nil)
1115   management_data subset: :static_groups, only: only
1116 end
udid=(new_val) click to toggle source
     # File lib/jamf/api/classic/api_objects/computer.rb
1271 def udid=(new_val)
1272   return nil if new_val == @udid
1273 
1274   @udid = new_val.empty? ? new_val : Jamf::Validate.doesnt_already_exist(Jamf::Computer, :udid, new_val, cnx: cnx)
1275   @need_to_update = true
1276 end
update() click to toggle source

Send changes to the API

@return [void]

Calls superclass method Jamf::APIObject#update
     # File lib/jamf/api/classic/api_objects/computer.rb
1282 def update
1283   remove_mdm_profile if mdm_capable && @unmange_at_update
1284   @unmange_at_update = false
1285   super
1286 end

Private Instance Methods

rest_xml() click to toggle source

Return a String with the XML Resource for submitting changes to the JSS via the API

For Computers, only some items can be changed via the API In particular, any data gatherd by a Recon cannot be changed

     # File lib/jamf/api/classic/api_objects/computer.rb
1363 def rest_xml
1364   doc = REXML::Document.new Jamf::Connection::XML_HEADER
1365   computer = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
1366 
1367   general = computer.add_element('general')
1368   general.add_element('name').text = @name
1369   general.add_element('alt_mac_address').text = @alt_mac_address
1370   general.add_element('asset_tag').text = @asset_tag
1371   general.add_element('barcode_1').text = @barcode1
1372   general.add_element('barcode_2').text = @barcode2
1373   general.add_element('ip_address').text = @ip_address
1374   general.add_element('mac_address').text = @mac_address
1375   general.add_element('udid').text = @udid
1376   general.add_element('serial_number').text = @serial_number
1377 
1378   rmgmt = general.add_element('remote_management')
1379   rmgmt.add_element('managed').text = @managed
1380   rmgmt.add_element('management_username').text = @management_username
1381   rmgmt.add_element('management_password').text = @management_password if @management_password
1382 
1383   computer << ext_attr_xml if unsaved_eas?
1384 
1385   computer << location_xml if has_location?
1386 
1387   computer << purchasing_xml if has_purchasing?
1388 
1389   add_site_to_xml(doc)
1390 
1391   doc.to_s
1392 end