Module: Jamf

Defined in:
lib/jamf.rb,
lib/jamf/client.rb,
lib/jamf/utility.rb,
lib/jamf/version.rb,
lib/jamf/composer.rb,
lib/jamf/validate.rb,
lib/jamf/exceptions.rb,
lib/jamf/configuration.rb,
lib/jamf/api/connection.rb,
lib/jamf/api/mixins/abstract.rb,
lib/jamf/api/mixins/lockable.rb,
lib/jamf/api/connection/token.rb,
lib/jamf/api/mixins/immutable.rb,
lib/jamf/api/mixins/locatable.rb,
lib/jamf/api/mixins/referable.rb,
lib/jamf/api/mixins/change_log.rb,
lib/jamf/api/mixins/extendable.rb,
lib/jamf/api/mixins/searchable.rb,
lib/jamf/api/mixins/uncreatable.rb,
lib/jamf/api/mixins/undeletable.rb,
lib/jamf/api/connection/api_error.rb,
lib/jamf/api/json_objects/country.rb,
lib/jamf/api/json_objects/location.rb,
lib/jamf/api/mixins/bulk_deletable.rb,
lib/jamf/api/json_objects/criterion.rb,
lib/jamf/api/json_objects/attachment.rb,
lib/jamf/api/json_objects/ios_details.rb,
lib/jamf/api/abstract_classes/prestage.rb,
lib/jamf/api/abstract_classes/resource.rb,
lib/jamf/api/json_objects/account_prefs.rb,
lib/jamf/api/attribute_classes/timestamp.rb,
lib/jamf/api/json_objects/prestage_scope.rb,
lib/jamf/api/abstract_classes/json_object.rb,
lib/jamf/api/attribute_classes/ip_address.rb,
lib/jamf/api/json_objects/android_details.rb,
lib/jamf/api/json_objects/appletv_details.rb,
lib/jamf/api/json_objects/installed_ebook.rb,
lib/jamf/api/json_objects/purchasing_data.rb,
lib/jamf/api/json_objects/cellular_network.rb,
lib/jamf/api/json_objects/change_log_entry.rb,
lib/jamf/api/json_objects/md_prestage_name.rb,
lib/jamf/api/json_objects/md_prestage_names.rb,
lib/jamf/api/json_objects/prestage_location.rb,
lib/jamf/api/connection/api_error_styleguide.rb,
lib/jamf/api/abstract_classes/advanced_search.rb,
lib/jamf/api/json_objects/prestage_assignment.rb,
lib/jamf/api/json_objects/prestage_sync_status.rb,
lib/jamf/api/abstract_classes/generic_reference.rb,
lib/jamf/api/json_objects/installed_application.rb,
lib/jamf/api/json_objects/installed_certificate.rb,
lib/jamf/api/json_objects/mobile_device_details.rb,
lib/jamf/api/abstract_classes/singleton_resource.rb,
lib/jamf/api/json_objects/mobile_device_security.rb,
lib/jamf/api/resources/collection_resources/site.rb,
lib/jamf/api/abstract_classes/collection_resource.rb,
lib/jamf/api/json_objects/device_enrollment_device.rb,
lib/jamf/api/json_objects/prestage_purchasing_data.rb,
lib/jamf/api/resources/collection_resources/script.rb,
lib/jamf/api/json_objects/extension_attribute_value.rb,
lib/jamf/api/resources/collection_resources/account.rb,
lib/jamf/api/resources/collection_resources/building.rb,
lib/jamf/api/resources/collection_resources/category.rb,
lib/jamf/api/resources/collection_resources/computer.rb,
lib/jamf/api/resources/collection_resources/time_zone.rb,
lib/jamf/api/json_objects/md_prestage_skip_setup_items.rb,
lib/jamf/api/resources/collection_resources/department.rb,
lib/jamf/api/abstract_classes/prestage_skip_setup_items.rb,
lib/jamf/api/json_objects/device_enrollment_sync_status.rb,
lib/jamf/api/json_objects/installed_provisioning_profile.rb,
lib/jamf/api/resources/singleton_resources/authorization.rb,
lib/jamf/api/json_objects/installed_configuration_profile.rb,
lib/jamf/api/resources/collection_resources/mobile_device.rb,
lib/jamf/api/json_objects/computer_prestage_skip_setup_items.rb,
lib/jamf/api/resources/collection_resources/computer_prestage.rb,
lib/jamf/api/resources/collection_resources/device_enrollment.rb,
lib/jamf/api/json_objects/inventory_preload_extension_attribute.rb,
lib/jamf/api/resources/collection_resources/extension_attribute.rb,
lib/jamf/api/resources/collection_resources/advanced_user_search.rb,
lib/jamf/api/resources/singleton_resources/reenrollment_settings.rb,
lib/jamf/api/resources/collection_resources/mobile_device_prestage.rb,
lib/jamf/api/resources/singleton_resources/app_store_country_codes.rb,
lib/jamf/api/resources/singleton_resources/client_checkin_settings.rb,
lib/jamf/api/resources/collection_resources/inventory_preload_record.rb,
lib/jamf/api/resources/collection_resources/advanced_mobile_device_search.rb

Overview

The Module

Defined Under Namespace

Modules: Abstract, ChangeLog, Composer, Extendable, Immutable, Locatable, Lockable, Referable, Searchable, UnCreatable, UnDeletable, Validate Classes: APIError, APIErrorDetail, APIRequestError, Account, AccountPreferences, AdvancedMobileDeviceSearch, AdvancedSearch, AdvancedUserSearch, AlreadyExistsError, AndroidDetails, AppStoreCountryCodes, AppleTVDetails, Attachment, AuthenticationError, Authorization, BadRequestError, Building, Category, CellularNetwork, ChangeLogEntry, Client, ClientCheckInSettings, CollectionResource, Computer, ComputerPrestage, ComputerPrestageSkipSetupItems, Configuration, ConflictError, Connection, Country, Criterion, Department, DeviceEnrollment, DeviceEnrollmentDevice, DeviceEnrollmentSyncStatus, ExtensionAttribute, ExtensionAttributeValue, FileServiceError, GenericReference, IPAddress, InstalledApplication, InstalledCertificate, InstalledConfigurationProfile, InstalledEBook, InstalledProvisioningProfile, InvalidConnectionError, InvalidDataError, InvalidTokenError, InventoryPreloadExtensionAttribute, InventoryPreloadRecord, IosDetails, JSONObject, Location, MissingDataError, MobileDevice, MobileDeviceDetails, MobileDevicePrestage, MobileDevicePrestageName, MobileDevicePrestageNames, MobileDevicePrestageSkipSetupItems, MobileDeviceSecurity, NoSuchItemError, Prestage, PrestageAssignment, PrestageLocation, PrestagePurchasingData, PrestageScope, PrestageSkipSetupItems, PrestageSyncStatus, PurchasingData, ReEnrollmentSettings, Resource, Script, SingletonResource, Site, TimeZone, TimeoutError, Timestamp, UnmanagedError, UnsupportedError, VersionLockError

Constant Summary collapse

MINIMUM_RUBY_VERSION =

The minimum Ruby version that works with this gem 2.3 allows us to start using some nice features like the safe-navigation operator and Array#dig & Hash#dig, and such.

For a list of features, see github.com/ruby/ruby/blob/v2_3_0/NEWS and nithinbekal.com/posts/ruby-2-3-features/

'2.3'.freeze
BLANK =

These Utility constants are useful all over the place. Many of them are commonly used Strings.

''.freeze
UNDERSCORE = 
'_'.freeze
VERSION =

The version of the Jamf module

'0.0.3'.freeze

Class Method Summary collapse

Class Method Details

.api_object_class(name) ⇒ Class

TODO: Move to APIObject

Given a name, singular or plural, of a Jamf::APIObject subclass as a String or Symbol (e.g. :computer/‘computers’), return the class itself (e.g. Jamf::Computer) The available names are the RSRC_LIST_KEY and RSRC_OBJECT_KEY values for each APIObject subclass.

Parameters:

  • name (String, Symbol) —

    The name of a Jamf::APIObject subclass, singluar or plural

Returns:

  • (Class) —

    The class

Raises:



274
275
276
277
278
 
# File 'lib/jamf/utility.rb', line 274

def self.api_object_class(name)
  klass = api_object_names[name.downcase.to_sym]
  raise Jamf::InvalidDataError, "Unknown API Object Class: #{name}" unless klass
  klass
end

.api_object_names ⇒ Hash

TODO: Move to APIObject

APIObject subclasses have singular names, and are, of course capitalized, e.g. ‘Computer’ But we often want to refer to them in the plural, or lowercase, e.g. ‘computers’ This method returns a Hash of the RSRC_LIST_KEY (a plural symbol) and the RSRC_OBJECT_KEY (a singular symbol) of each APIObject subclass, keyed to the class itself, such that both :computer and :computers are keys for Jamf::Computer and both :policy and :policies are keys for Jamf::Policy, and so on.

Returns:

  • (Hash) —

    APIObject subclass names to Classes



294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/jamf/utility.rb', line 294

def self.api_object_names
  return @api_object_names if @api_object_names
  @api_object_names ||= {}
  JSS.constants.each do |const|
    klass = JSS.const_get const
    next unless klass.is_a? Class
    next unless klass.ancestors.include? Jamf::APIObject
    @api_object_names[klass.const_get(:RSRC_LIST_KEY).to_sym] = klass if klass.constants.include? :RSRC_LIST_KEY
    @api_object_names[klass.const_get(:RSRC_OBJECT_KEY).to_sym] = klass if klass.constants.include? :RSRC_OBJECT_KEY
  end
  @api_object_names
end

.cnx ⇒ Jamf::Connection

Returns the active connection.

Returns:



824
825
826
 
# File 'lib/jamf/api/connection.rb', line 824

def self.cnx
  @active_connection ||= Connection.new do_not_connect: true
end

.cnx=(connection) ⇒ APIConnection

Switch the connection used for all API interactions to the one provided. See APIConnection for details and examples of using multiple connections

Parameters:

  • connection (APIConnection) —

    The APIConnection to use for future API calls. If omitted, use the default connection created when ruby-jss was loaded (which may or may not yet be connected)

Returns:

  • (APIConnection) —

    The connection now being used.



853
854
855
856
857
 
# File 'lib/jamf/api/connection.rb', line 853

def self.cnx=(connection)
  raise 'API connections must be instances of Jamf::Connection' unless connection.is_a? Jamf::Connection

  @active_connection = connection
end

.config ⇒ Object

class Config



275
276
277
 
# File 'lib/jamf/configuration.rb', line 275

def self.config
  Jamf::Configuration.instance
end

.connect(url = nil, **params) ⇒ APIConnection

Create a new Connection object and use it as the active_connection, replacing the current active_connection. If connection options are provided, they are passed to the connect method immediately, otherwise Jamf.cnx.connect must be called before attemting to use the connection.

Parameters:

Returns:

  • (APIConnection) —

    the new, active connection



838
839
840
841
 
# File 'lib/jamf/api/connection.rb', line 838

def self.connect(url = nil, **params)
  @active_connection = Connection.new url, params
  @active_connection.to_s
end

.devmode(setting) ⇒ Boolean

un/set devmode mode. Useful when coding - methods can call JSS.devmode? and then e.g. spit out something instead of performing some action.

Parameters:

  • Set (Symbol) —

    devmode :on or :off

Returns:

  • (Boolean) —

    The new state of devmode



411
412
413
 
# File 'lib/jamf/utility.rb', line 411

def self.devmode(setting)
  @devmode = setting == :on
end

.devmode? ⇒ Boolean

is devmode currently on?

Returns:

  • (Boolean) 


419
420
421
 
# File 'lib/jamf/utility.rb', line 419

def self.devmode?
  @devmode
end

.disconnect ⇒ Object 



859
860
861
 
# File 'lib/jamf/api/connection.rb', line 859

def self.disconnect
  @active_connection.disconnect if @active_connection
end

.epoch_to_time(epoch) ⇒ Time?

TODO: Sill needed in Jamf API?

Converts JSS epoch (unix epoch + milliseconds) to a Ruby Time object

Parameters:

  • epoch (String, Integer, nil)

Returns:

  • (Time, nil) —

    nil is returned if epoch is nil, 0 or an empty String.



254
255
256
257
 
# File 'lib/jamf/utility.rb', line 254

def self.epoch_to_time(epoch)
  return nil if NIL_DATES.include? epoch
  Time.at(epoch.to_i / 1000.0)
end

.expand_min_os(min_os) ⇒ Array

Converts an OS Version into an Array of higher OS versions.

It’s unlikely that this library will still be in use as-is by the release of OS X 10.30.20. Hopefully well before then JAMF will implement a “minimum OS” in the JSS itself.

Examples:

JSS.expand_min_os ">=10.6.7" # => returns this array
 # ["10.6.7",
 #  "10.6.8",
 #  "10.6.9",
 #   ...
 #  "10.6.20",
 #  "10.7.x",
 #  "10.8.x",
 #  ...
 #  "10.30.x"]

Parameters:

  • min_os (String) —

    the mimimum OS version to expand, e.g. “>=10.6.7” or “10.6.7”

Returns:

  • (Array) —

    Nearly all potential OS versions from the minimum to 10.19.x.



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
 
# File 'lib/jamf/utility.rb', line 67

def self.expand_min_os(min_os)
  min_os = min_os.delete '>='

  # split the version into major, minor and maintenance release numbers
  (maj, min, maint) = min_os.split('.')
  maint = 'x' if maint.nil? || maint == '0'

  # if the maint release number is an "x" just start the list of OK OS's with it
  if maint == 'x'
    ok_oses = [maj + '.' + min.to_s + '.x']

  # otherwise, start with it and explicitly add all maint releases up to 20
  # (and hope apple doesn't do more than 20 maint releases for an OS)
  else
    ok_oses = []
    (maint.to_i..20).each do |m|
      ok_oses << maj + '.' + min + '.' + m.to_s
    end # each m
  end

  # now account for all OS X versions starting with 10.
  # up to at least 10.30.x
  ((min.to_i + 1)..30).each do |v|
    ok_oses << maj + '.' + v.to_s + '.x'
  end # each v
  ok_oses
end

.humanize_secs(secs) ⇒ Object

Very handy! lifted from stackoverflow.com/questions/4136248/how-to-generate-a-human-readable-time-range-using-ruby-on-rails



393
394
395
396
397
398
399
400
401
 
# File 'lib/jamf/utility.rb', line 393

def self.humanize_secs(secs)
  [[60, :second], [60, :minute], [24, :hour], [7, :day], [52.179, :week], [1_000_000, :year]].map do |count, name|
    next unless secs > 0

    secs, n = secs.divmod(count)
    n = n.to_i
    "#{n} #{n == 1 ? name : (name.to_s + 's')}"
  end.compact.reverse.join(' ')
end

.os_ok?(requirement, os_to_check = nil) ⇒ Boolean

Scripts and packages can have OS limitations. This method tests a given OS, against a requirement list to see if the requirement is met.

Parameters:

  • requirement (String, Array) —

    The os requirement list, a comma-seprated string or array of strings of allows OSes. e.g. 10.7, 10.8.5 or 10.9.x

  • processor (String) —

    the os to check, defaults to the os of the current machine.

Returns:

  • (Boolean) —

    can this pkg be installed with the processor given?



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/jamf/utility.rb', line 128

def self.os_ok?(requirement, os_to_check = nil)
  return true if requirement.to_s =~ /none/i
  return true if requirement.to_s == 'n'
  requirement = JSS.to_s_and_a(requirement)[:arrayform]
  return true if requirement.empty?

  os_to_check ||= `/usr/bin/sw_vers -productVersion`.chomp

  # convert the requirement array into an array of regexps.
  # examples:
  #   "10.8.5" becomes  /^10\.8\.5$/
  #   "10.8" becomes /^10.8(.0)?$/
  #   "10.8.x" /^10\.8\.?\d*$/
  req_regexps = requirement.map do |r|
    if r.end_with?('.x')
      /^#{r.chomp('.x').gsub('.', '\.')}\.?\d*$/

    elsif r =~ /^\d+\.\d+$/
      /^#{r.gsub('.', '\.')}(.0)?$/

    else
      /^#{r.gsub('.', '\.')}$/
    end
  end

  req_regexps.each { |re| return true if os_to_check =~ re }
  false
end

.parse_jss_version(version) ⇒ Hash{Symbol => String, Gem::Version}

TODO: Update or remove for Jamf API Parse a JSS Version number into something comparable.

This method returns a Hash with these keys:

  • :major => the major version, Integer

  • :minor => the minor version, Integor

  • :maint => the revision, Integer (also available as :patch and :revision)

  • :build => the revision, String

  • :version => a Gem::Version object built from :major, :minor, :revision which can be easily compared with other Gem::Version objects.

NOTE: the :version value ignores build numbers, so comparisons only compare major.minor.maint

Parameters:

  • version (String) —

    a JSS version number from the API

Returns:

  • (Hash{Symbol => String, Gem::Version}) —

    the parsed version data.

Raises:



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/jamf/utility.rb', line 325

def self.parse_jss_version(version)
  major, second_part, *_rest = version.split('.')
  raise Jamf::InvalidDataError, 'JSS Versions must start with "x.x" where x is one or more digits' unless major =~ /\d$/ && second_part =~ /^\d/

  release, build = version.split(/-/)

  major, minor, revision = release.split '.'
  minor ||= 0
  revision ||= 0

  {
    major: major.to_i,
    minor:  minor.to_i,
    revision:  revision.to_i,
    maint:  revision.to_i,
    patch:  revision.to_i,
    build:  build,
    version: Gem::Version.new("#{major}.#{minor}.#{revision}")
  }
end

.parse_plist(plist) ⇒ Object

Parse a plist into a Ruby data structure. This enhances Plist::parse_xml taking file paths, as well as XML Strings and reading the files regardless of binary/XML format.

Parameters:

  • plist (Pathname, String) —

    the plist XML, or the path to a plist file

Returns:

  • (Object) —

    the parsed plist as a ruby hash,array, etc.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/jamf/utility.rb', line 198

def self.parse_plist(plist)
  # did we get a string of xml, or a string pathname?
  case plist
  when String
    return Plist.parse_xml plist if plist.include? '</plist>'
    plist = Pathname.new plist
  when Pathname
    true
  else
    raise ArgumentError, 'Argument must be a path (as a Pathname or String) or a String of XML'
  end # case plist

  # if we're here, its a Pathname
  raise Jamf::MissingDataError, "No such file: #{plist}" unless plist.file?

  Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape(plist.to_s)}`.force_encoding('UTF-8')
end

.parse_time(a_datetime) ⇒ Time?

TODO: Sill needed in Jamf API?

Converts anything that responds to #to_s to a Time, or nil

Return nil if the item is nil, 0 or an empty String.

Otherwise the item converted to a string, and parsed with DateTime.parse. It is then examined to see if it has a UTC offset. If not, the local offset is applied, then the DateTime is converted to a Time.

Parameters:

  • a_datetime (#to_s) —

    The thing to convert to a time.

Returns:

  • (Time, nil) —

    nil is returned if a_datetime is nil, 0 or an empty String.



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/jamf/utility.rb', line 230

def self.parse_time(a_datetime)
  return nil if NIL_DATES.include? a_datetime

  the_dt = DateTime.parse(a_datetime.to_s)

  # The microseconds in DateTimes are stored as a fraction of a day.
  # Convert them to an integer of microseconds
  usec = (the_dt.sec_fraction * 60 * 60 * 24 * (10**6)).to_i

  # if the UTC offset of the datetime is zero, make a new one with the correct local offset
  # (which might also be zero if we happen to be in GMT)
  the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, Jamf::TIME_ZONE_OFFSET) if the_dt.offset.zero?
  # now convert it to a Time and return it
  Time.at the_dt.strftime('%s').to_i, usec
end

.processor_ok?(requirement, processor = nil) ⇒ Boolean

Scripts and packages can have processor limitations. This method tests a given processor, against a requirement to see if the requirement is met.

Parameters:

  • requirement (String) —

    The processor requirement. either ‘ppc’, ‘x86’, or some variation on “none”, nil, or empty

  • processor (String) (defaults to: nil) —

    the processor to check, defaults to the processor of the current machine. Any flavor of intel

    is (i486, i386, x86-64, etc) is treated as "x86"

Returns:

  • (Boolean) —

    can this pkg be installed with the processor given?



109
110
111
112
113
 
# File 'lib/jamf/utility.rb', line 109

def self.processor_ok?(requirement, processor = nil)
  return true if requirement.to_s.empty? || requirement =~ /none/i
  processor ||= `/usr/bin/uname -p`
  requirement == (processor.to_s.include?('86') ? 'x86' : 'ppc')
end

.prompt_for_password(message) ⇒ String

Prompt for a password in a terminal.

Parameters:

  • message (String) —

    the prompt message to display

Returns:

  • (String) —

    the text typed by the user



376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/jamf/utility.rb', line 376

def self.prompt_for_password(message)
  begin
    $stdin.reopen '/dev/tty' unless $stdin.tty?
    $stderr.print "#{message} "
    system '/bin/stty -echo'
    pw = $stdin.gets.chomp("\n")
    puts
  ensure
    system '/bin/stty echo'
  end # begin
  pw
end

.stdin(line = 0) ⇒ String?

Retrive one or all lines from whatever was piped to standard input.

Standard input is read completely the first time this method is called and the lines are stored as an Array in the module var @stdin_lines

Parameters:

  • line (Integer) (defaults to: 0) —

    which line of stdin is being retrieved. The default is zero (0) which returns all of stdin as a single string.

Returns:

  • (String, nil) —

    the requested ling of stdin, or nil if it doesn’t exist.



362
363
364
365
366
367
368
 
# File 'lib/jamf/utility.rb', line 362

def self.stdin(line = 0)
  @stdin_lines ||= ($stdin.tty? ? [] : $stdin.read.lines.map { |l| l.chomp("\n") })

  return @stdin_lines.join("\n") if line <= 0
  idx = line - 1
  @stdin_lines[idx]
end

.superuser? ⇒ Boolean

Returns is this code running as root?.

Returns:

  • (Boolean) —

    is this code running as root?



348
349
350
 
# File 'lib/jamf/utility.rb', line 348

def self.superuser?
  Process.euid.zero?
end

.to_s_and_a(somedata) ⇒ Hash{:stringform => String, :arrayform => Array}

Given a list of data as a comma-separated string, or an Array of strings, return a Hash with both versions.

Some parts of the JSS require lists as comma-separated strings, while often those data are easier work with as arrays. This method is a handy way to get either form when given either form.

Examples:

JSS.to_s_and_a "foo, bar, baz" # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}

JSS.to_s_and_a ["foo", "bar", "baz"] # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}

Parameters:

  • somedata (String, Array) —

    the data to parse, of either class,

Returns:

  • (Hash{:stringform => String, :arrayform => Array}) —

    the data as both comma-separated String and Array



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/jamf/utility.rb', line 173

def self.to_s_and_a(somedata)
  case somedata
  when nil
    valstr = ''
    valarr = []
  when String
    valstr = somedata
    valarr = somedata.split(/,\s*/)
  when Array
    valstr = somedata.join ', '
    valarr = somedata
  else
    raise Jamf::InvalidDataError, 'Input must be a comma-separated String or an Array of Strings'
  end # case
  { stringform: valstr, arrayform: valarr }
end