Class: Jamf::OAPIObject

Inherits:
Object show all
Includes:
Comparable
Defined in:
lib/jamf/api/jamf_pro/base_classes/oapi_object.rb

Overview

The parent class for all objects auto-generated in the Jamf::OAPISchemas module more docs to come

Direct Known Subclasses

Jamf::OAPISchemas::AccountGroup, Jamf::OAPISchemas::AccountPreferencesV1, Jamf::OAPISchemas::AccountSettingsRequest, Jamf::OAPISchemas::AccountSettingsResponse, Jamf::OAPISchemas::ApiError, Jamf::OAPISchemas::ApiErrorCause, Jamf::OAPISchemas::ApiIntegrationRequest, Jamf::OAPISchemas::ApiIntegrationResponse, Jamf::OAPISchemas::ApiIntegrationSearchResult, Jamf::OAPISchemas::ApiRole, Jamf::OAPISchemas::ApiRoleRequest, Jamf::OAPISchemas::ApiRoleResult, Jamf::OAPISchemas::AssignRemoveProfileResponseSyncState, Jamf::OAPISchemas::AuthAccountV1, Jamf::OAPISchemas::AuthenticationType, Jamf::OAPISchemas::AuthorizationV1, Jamf::OAPISchemas::AvailableUpdates, Jamf::OAPISchemas::Building, Jamf::OAPISchemas::BuildingSearchResults, Jamf::OAPISchemas::ComputerApplication, Jamf::OAPISchemas::ComputerAttachment, Jamf::OAPISchemas::ComputerCertificate, Jamf::OAPISchemas::ComputerConfigurationProfile, Jamf::OAPISchemas::ComputerContentCaching, Jamf::OAPISchemas::ComputerContentCachingAlert, Jamf::OAPISchemas::ComputerContentCachingCacheDetail, Jamf::OAPISchemas::ComputerContentCachingDataMigrationError, Jamf::OAPISchemas::ComputerContentCachingDataMigrationErrorUserInfo, Jamf::OAPISchemas::ComputerContentCachingParent, Jamf::OAPISchemas::ComputerContentCachingParentAlert, Jamf::OAPISchemas::ComputerContentCachingParentCapabilities, Jamf::OAPISchemas::ComputerContentCachingParentDetails, Jamf::OAPISchemas::ComputerContentCachingParentLocalNetwork, Jamf::OAPISchemas::ComputerDisk, Jamf::OAPISchemas::ComputerDiskEncryption, Jamf::OAPISchemas::ComputerExtensionAttribute, Jamf::OAPISchemas::ComputerFont, Jamf::OAPISchemas::ComputerGeneral, Jamf::OAPISchemas::ComputerHardware, Jamf::OAPISchemas::ComputerIbeacon, Jamf::OAPISchemas::ComputerInventory, Jamf::OAPISchemas::ComputerInventoryFileVault, Jamf::OAPISchemas::ComputerLicensedSoftware, Jamf::OAPISchemas::ComputerLocalUserAccount, Jamf::OAPISchemas::ComputerMdmCapability, Jamf::OAPISchemas::ComputerOperatingSystem, Jamf::OAPISchemas::ComputerPackageReceipts, Jamf::OAPISchemas::ComputerPartition, Jamf::OAPISchemas::ComputerPartitionEncryption, Jamf::OAPISchemas::ComputerPartitionFileVault2State, Jamf::OAPISchemas::ComputerPlugin, Jamf::OAPISchemas::ComputerPrestageSearchResultsV3, Jamf::OAPISchemas::ComputerPrestageV3, Jamf::OAPISchemas::ComputerPrinter, Jamf::OAPISchemas::ComputerPurchase, Jamf::OAPISchemas::ComputerRemoteManagement, Jamf::OAPISchemas::ComputerSection, Jamf::OAPISchemas::ComputerSecurity, Jamf::OAPISchemas::ComputerService, Jamf::OAPISchemas::ComputerSoftwareUpdate, Jamf::OAPISchemas::ComputerStorage, Jamf::OAPISchemas::ComputerUserAndLocation, Jamf::OAPISchemas::DeviceEnrollmentDevice, Jamf::OAPISchemas::DeviceEnrollmentDeviceSearchResults, Jamf::OAPISchemas::DeviceEnrollmentDisownResponse, Jamf::OAPISchemas::DeviceEnrollmentInstance, Jamf::OAPISchemas::DeviceEnrollmentInstanceSearchResults, Jamf::OAPISchemas::DeviceEnrollmentInstanceSyncStatus, Jamf::OAPISchemas::DeviceEnrollmentPrestageV2, Jamf::OAPISchemas::DeviceEnrollmentToken, Jamf::OAPISchemas::DssDeclaration, Jamf::OAPISchemas::DssDeclarations, Jamf::OAPISchemas::EnrollmentMethod, Jamf::OAPISchemas::GetComputerPrestageV3, Jamf::OAPISchemas::GetMobileDevicePrestageV2, Jamf::OAPISchemas::GroupMembership, Jamf::OAPISchemas::HistorySearchResultsV1, Jamf::OAPISchemas::InventoryPreloadExtensionAttribute, Jamf::OAPISchemas::InventoryPreloadRecordSearchResultsV2, Jamf::OAPISchemas::InventoryPreloadRecordV2, Jamf::OAPISchemas::LocationInformation, Jamf::OAPISchemas::LocationInformationV2, Jamf::OAPISchemas::MacOsManagedSoftwareUpdate, Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse, Jamf::OAPISchemas::ManagedSoftwareUpdatePlan, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanEventStore, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanGroupPost, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanPost, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanPostResponse, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanToggle, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanToggleStatus, Jamf::OAPISchemas::ManagedSoftwareUpdatePlanToggleStatusWrapper, Jamf::OAPISchemas::ManagedSoftwareUpdatePlans, Jamf::OAPISchemas::ManagedSoftwareUpdateStatus, Jamf::OAPISchemas::ManagedSoftwareUpdateStatuses, Jamf::OAPISchemas::MobileDevicePrestageNameV2, Jamf::OAPISchemas::MobileDevicePrestageNamesV2, Jamf::OAPISchemas::MobileDevicePrestageSearchResultsV2, Jamf::OAPISchemas::MobileDevicePrestageV2, Jamf::OAPISchemas::OAuthClientCredentials, Jamf::OAPISchemas::ObjectHistoryNote, Jamf::OAPISchemas::ObjectHistoryV1, Jamf::OAPISchemas::Package, Jamf::OAPISchemas::PackagesSearchResults, Jamf::OAPISchemas::PlanConfigurationPost, Jamf::OAPISchemas::PlanDevice, Jamf::OAPISchemas::PlanDevicePost, Jamf::OAPISchemas::PlanDeviceResponse, Jamf::OAPISchemas::PlanGroupPost, Jamf::OAPISchemas::PlanSearchResults, Jamf::OAPISchemas::PlanStatus, Jamf::OAPISchemas::PostComputerPrestageV3, Jamf::OAPISchemas::PrestagePurchasingInformation, Jamf::OAPISchemas::PrestagePurchasingInformationV2, Jamf::OAPISchemas::PrestageScopeAssignmentV2, Jamf::OAPISchemas::PrestageScopeResponseV2, Jamf::OAPISchemas::PrestageScopeV2, Jamf::OAPISchemas::PutComputerPrestageV3, Jamf::OAPISchemas::PutMobileDevicePrestageV2, Jamf::OAPISchemas::RedeployJamfManagementFrameworkResponse, Jamf::OAPISchemas::V1Site

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data) ⇒ OAPIObject

Make an instance. Data comes from the API

Parameters:

  • data (Hash) —

    the data for constructing a new object.



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 355

def initialize(data)
  @init_data = data

  # creating a new one via ruby-jss, not fetching one from the API
  creating = data.delete :creating_from_create if data.is_a?(Hash)

  if creating
    self.class::OAPI_PROPERTIES.each_key do |attr_name|
      # we'll enforce required values when we save
      next unless data.key? attr_name

      # use our setters for each value so that they are validated, and
      # in the unsaved changes list
      send "#{attr_name}=", data[attr_name]
    end
    return
  end

  parse_init_data data
end

Instance Attribute Details

#init_data ⇒ Hash (readonly)

the raw hash from which this object was constructed

Returns:



346
347
348
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 346

def init_data
  @init_data
end

Class Method Details

.mutable? ⇒ Boolean

By default,OAPIObjects (as a whole) are mutable, although some attributes may not be (see OAPI_PROPERTIES in the JSONObject docs)

When an entire sublcass of OAPIObject is read-only/immutable, ‘extend Jamf::Immutable`, which will override this to return false. Doing so will prevent any setters from being created for the subclass and will cause Jamf::Resource.save to raise an error

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 50

def self.mutable?
  !singleton_class.ancestors.include? Jamf::Immutable
end

.oapi_properties_parsed? ⇒ Boolean

have we already parsed our OAPI_PROPERTIES? If so, we shoudn’t do it again, an this can be used to check

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 64

def self.oapi_properties_parsed?
  @oapi_properties_parsed
end

.parse_oapi_properties ⇒ Object

create getters and setters for subclasses of APIObject based on their OAPI_PROPERTIES Hash.

This method can’t be private, cuz we want to call it from a Zeitwerk callback when subclasses are loaded.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 74

def self.parse_oapi_properties
  # only do this once
  return if @oapi_properties_parsed

  # only if this constant is defined
  return unless defined? self::OAPI_PROPERTIES

  # TODO: is the concept of 'primary' needed anymore?
  got_primary = false

  self::OAPI_PROPERTIES.each do |attr_name, attr_def|
    Jamf.load_msg "Creating getters and setters for attribute '#{attr_name}' of #{self}"

    # see above comment
    # don't make one for :id, that one's hard-coded into CollectionResource
    # create_list_methods(attr_name, attr_def) if need_list_methods && attr_def[:identifier] && attr_name != :id

    # there can be only one (primary ident)
    if attr_def[:identifier] == :primary
      raise Jamf::UnsupportedError, 'Two identifiers marked as :primary' if got_primary

      got_primary = true
    end

    # create getter unless the attr is write only
    create_getters attr_name, attr_def unless attr_def[:writeonly]

    # Don't crete setters for readonly attrs, or immutable objects
    next if attr_def[:readonly] || !mutable?

    create_setters attr_name, attr_def
  end #  do |attr_name, attr_def|

  if defined? self::OBJECT_NAME_ATTR
    alias_method(:name, self::OBJECT_NAME_ATTR)
    alias_method('name=', "#{self::OBJECT_NAME_ATTR}=")
  end

  @oapi_properties_parsed = true
end

.required_attributes ⇒ Object

An array of attribute names that are required when making new instances - they cannot be nil, but may be empty.

See the OAPI_PROPERTIES documentation in Jamf::OAPIObject



58
59
60
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 58

def self.required_attributes
  self::OAPI_PROPERTIES.select { |_attr, deets| deets[:required] }.keys
end

.validate_attr(attr_name, value) ⇒ Object

Used by auto-generated setters and .create to validate new values.

returns a valid value or raises an exception

This method only validates single values. When called from multi-value setters, it is used for each value individually.

Parameters:

  • attr_name (Symbol) —

    , a top-level key from OAPI_PROPERTIES for this class

  • value (Object) —

    the value to validate for that attribute.

Returns:

  • (Object) —

    The validated, possibly converted, value.

Raises:

  • (ArgumentError) 


329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 329

def self.validate_attr(attr_name, value)
  attr_def = self::OAPI_PROPERTIES[attr_name]
  raise ArgumentError, "Unknown attribute: #{attr_name} for #{self} objects" unless attr_def

  # validate the value based on the OAPI definition.
  Jamf::Validate.oapi_attr value, attr_def: attr_def, attr_name: attr_name

  # if this is an identifier, it must be unique
  # TODO: move this to colloection resouce code
  # Jamf::Validate.doesnt_exist(value, self, attr_name, cnx: cnx) if attr_def[:identifier] && superclass == Jamf::CollectionResource
end

Instance Method Details

#<=>(other) ⇒ Object

Comparable by the sha1 hash of our properties. Subclasses or mixins may override this in ways that make sense for them TODO: Using this may not make sense for most objects, esp when comparing objects instantiated from Create vs those from Fetch.



481
482
483
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 481

def <=>(other)
  sha1_hash <=> other.sha1_hash
end

#clear_unsaved_changes ⇒ Object 



423
424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 423

def clear_unsaved_changes
  return unless self.class.mutable?

  unsaved_changes.keys.each do |attr_name|
    attrib_val = instance_variable_get "@#{attr_name}"
    if self.class::OAPI_PROPERTIES[attr_name][:multi]
      attrib_val.each { |item| item.send :clear_unsaved_changes if item.respond_to? :clear_unsaved_changes }
    elsif attrib_val.respond_to? :clear_unsaved_changes
      attrib_val.send :clear_unsaved_changes
    end
  end
  ext_attrs_clear_unsaved_changes if self.class.include? Jamf::Extendable
  @unsaved_changes = {}
end

#mutable? ⇒ Boolean

Are objects of this class mutable?

Returns:

  • (Boolean)

See Also:

  • class method in OAPIObject


381
382
383
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 381

def mutable?
  self.class.mutable?
end

#pretty_jamf_json ⇒ Object

Print the JSON version of the to_jamf outout mostly for debugging/troubleshooting



459
460
461
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 459

def pretty_jamf_json
  puts JSON.pretty_generate(to_jamf)
end

#pretty_print_instance_variables ⇒ Array

Remove large cached items from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables



469
470
471
472
473
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 469

def pretty_print_instance_variables
  vars = super.sort
  vars.delete :@init_data
  vars
end

#sha1_hash ⇒ Object

The SHA1 hash of all the values of our properties as defined in the OAPI schema



487
488
489
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 487

def sha1_hash
  Digest::SHA1.hexdigest(to_jamf.to_s)
end

#to_jamf ⇒ Hash

Returns The data to be sent to the API, as a Hash to be converted to JSON before sending to the JPAPI.

Returns:

  • (Hash) —

    The data to be sent to the API, as a Hash to be converted to JSON before sending to the JPAPI



441
442
443
444
445
446
447
448
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 441

def to_jamf
  jamf_data = {}
  self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
    raw_value = instance_variable_get "@#{attr_name}"
    jamf_data[attr_name] = attr_def[:multi] ? multi_to_jamf(raw_value, attr_def) : single_to_jamf(raw_value, attr_def)
  end
  jamf_data
end

#to_json(*_args) ⇒ String

Returns the JSON to be sent to the API for this object.

Returns:

  • (String) —

    the JSON to be sent to the API for this object



453
454
455
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 453

def to_json(*_args)
  to_jamf.to_json
end

#unsaved_changes ⇒ Object

a hash of all unsaved changes



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 387

def unsaved_changes
  return {} unless self.class.mutable?

  @unsaved_changes ||= {}

  changes = @unsaved_changes.dup

  self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
    # skip non-Class attrs
    next unless attr_def[:class].is_a? Class

    # the current value of the thing, e.g. a Location
    # which may have unsaved changes
    value = instance_variable_get "@#{attr_name}"

    # skip those that don't have any changes
    next unless value.respond_to? :unsaved_changes?

    attr_changes = value.unsaved_changes
    next if attr_changes.empty?

    # add the sub-changes to ours
    changes[attr_name] = attr_changes
  end
  changes[:ext_attrs] = ext_attrs_unsaved_changes if self.class.include? Jamf::Extendable
  changes
end

#unsaved_changes? ⇒ Boolean

return true if we or any of our attributes have unsaved changes

Returns:

  • (Boolean) 


417
418
419
420
421
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 417

def unsaved_changes?
  return false unless self.class.mutable?

  !unsaved_changes.empty?
end