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.



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 368

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) 


359
360
361
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 359

def creating_from_create
  @creating_from_create
end

#init_data ⇒ Hash (readonly)

the raw hash from which this object was constructed

Returns:



354
355
356
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 354

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) 


337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 337

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.



494
495
496
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 494

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

#clear_unsaved_changes ⇒ Object 



436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 436

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


394
395
396
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 394

def mutable?
  self.class.mutable?
end

#pretty_jamf_json ⇒ Object

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



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

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



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

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



500
501
502
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 500

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



454
455
456
457
458
459
460
461
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 454

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



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

def to_json(*_args)
  to_jamf.to_json
end

#unsaved_changes ⇒ Object

a hash of all unsaved changes



400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 400

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) 


430
431
432
433
434
 
# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 430

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

  !unsaved_changes.empty?
end