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:
-
Management
Account
(seeset_management_to
) -
barcodes 1 and 2
-
udid
-
serial_number
Note: Even tho the webUI doesn’t allow editing theserial_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
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
- 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 theJSS
@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
@return [String] the secondary mac address
@return [String] the secondary mac address
@return [String] the asset tag
@return [String] the barcodes
@return [String] the barcodes
@return [String] the barcodes
@return [String] the barcodes
@return [String] the barcodes
@return [String] the barcodes
@return [Array<Hash>]
A Hash
for each ConfigurationProfile
on the computer
The Hash
keys are:
-
:id => the
ConfigurationProfile
id in theJSS
-
:name => the username to whom this user-level profile has been applied (if it’s a user-level profile)
-
:uuid => the
ConfigurationProfile
uuid
@return [String] The name of the distribution point for this computer
@return [Boolean] was the last enrollment via ADE/DEP
@return [Boolean] was the last enrollment via ADE/DEP
@return [Boolean] was the last enrollment via ADE/DEP
@return [Boolean] was the last enrollment via ADE/DEP
@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
-
@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
-
-
@return [Time] when was it added to the JSS
@return [IPAddr] the last known IP address from the server’s perspective
@return [Boolean]
@return [String] the version of the jamf binary
@return [Time] the last contact time
@return [Time] the last time this machine was enrolled
@return [Time] the last recon time
@return [String] the primary macaddress
@return [Boolean] is this machine “managed” by Casper?
@return [Boolean] is this machine “managed” by Casper?
@return [Hash] some MDM
status details in general
@return [String] the name of the management account
@return [Boolean] doesit support MDM
?
@return [Boolean] doesit support MDM
?
@return [Boolean] doesit support MDM
?
@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.
@return [Time] when does the mdm profile expire
@return [String] the name of the netboot server for this machine
@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=>“”
-
@return [String] what kind of computer?
@return [Time] the last recon time
@return [IPAddr] the last known IP address from the client’s perspecive
@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
@return [String] the serial number
@return [String] the serial number
@return [Hash] the :name and :id of the site for this machine
@return [String] the serial number
@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
ofPackage
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: -
:cached_by_casper => An
Array
of CasperPackage
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
@return [Boolean] Is it supervised?
@return [Boolean] Is it supervised?
@return [String] the name of the Software Update Server assigned to this machine.
@return [String] the UDID of the computer
@return [Boolean] was enrollment user-approved
@return [Boolean] was enrollment user-approved
Public Class Methods
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
@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
@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
@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
@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
@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
@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
@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
@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
@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
@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
@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
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
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
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
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
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
@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:
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
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
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
# 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
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
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
@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
# 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
# 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
# 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
@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
@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 this computer from the JSS
@return [void]
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
@return [Array<Hash>] each storage device
# File lib/jamf/api/classic/api_objects/computer.rb 1055 def drives 1056 @hardware[:storage] 1057 end
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
@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
@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 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
# 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
@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
@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
# 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 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
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
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.
# 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
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
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
@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
Companion to method_missing
, allows for easier debugging in backtraces that involve missing methods.
# File lib/jamf/api/classic/api_objects/computer.rb 1021 def respond_to_missing?(method, *) 1022 @hardware.key?(method) || super 1023 end
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
# 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 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
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
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
# 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
Send changes to the API
@return [void]
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
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