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.



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 351

def initialize(data)
  @init_data = data

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

  if @creating_from_create
    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

#creating_from_create ⇒ Boolean (readonly)

If this is true, we are being created via the .create method and not fetched from the API.

Returns:

  • (Boolean) 


342
343
344
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 342

def creating_from_create
  @creating_from_create
end

#init_data ⇒ Hash (readonly)

the raw hash from which this object was constructed

Returns:



337
338
339
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 337

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) 


33
34
35
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 33

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) 


47
48
49
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 47

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.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 57

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



41
42
43
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 41

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) 


320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 320

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.



477
478
479
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 477

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

#clear_unsaved_changes ⇒ Object 



419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 419

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


377
378
379
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 377

def mutable?
  self.class.mutable?
end

#pretty_jamf_json ⇒ Object

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



455
456
457
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 455

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



465
466
467
468
469
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 465

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



483
484
485
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 483

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



437
438
439
440
441
442
443
444
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 437

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



449
450
451
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 449

def to_json(*_args)
  to_jamf.to_json
end

#unsaved_changes ⇒ Object

a hash of all unsaved changes



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

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) 


413
414
415
416
417
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 413

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

  !unsaved_changes.empty?
end