Module: JSS

Defined in:
lib/jss.rb,
lib/jss/client.rb,
lib/jss/server.rb,
lib/jss/utility.rb,
lib/jss/version.rb,
lib/jss/composer.rb,
lib/jss/validate.rb,
lib/jss/api_object.rb,
lib/jss/exceptions.rb,
lib/jss/configuration.rb,
lib/jss/db_connection.rb,
lib/jss/api_connection.rb,
lib/jss/api_object/mdm.rb,
lib/jss/api_object/site.rb,
lib/jss/api_object/user.rb,
lib/jss/api_object/ebook.rb,
lib/jss/api_object/group.rb,
lib/jss/api_object/patch.rb,
lib/jss/api_object/policy.rb,
lib/jss/api_object/script.rb,
lib/jss/api_object/account.rb,
lib/jss/api_object/package.rb,
lib/jss/api_object/sitable.rb,
lib/jss/api_object/vppable.rb,
lib/jss/api_object/webhook.rb,
lib/jss/client/jamf_binary.rb,
lib/jss/client/jamf_helper.rb,
lib/jss/api_object/building.rb,
lib/jss/api_object/category.rb,
lib/jss/api_object/computer.rb,
lib/jss/api_object/scopable.rb,
lib/jss/api_object/creatable.rb,
lib/jss/api_object/locatable.rb,
lib/jss/api_object/matchable.rb,
lib/jss/api_object/updatable.rb,
lib/jss/api_object/department.rb,
lib/jss/api_object/extendable.rb,
lib/jss/api_object/peripheral.rb,
lib/jss/api_object/uploadable.rb,
lib/jss/api_object/criteriable.rb,
lib/jss/api_object/ldap_server.rb,
lib/jss/api_object/purchasable.rb,
lib/jss/api_object/patch_policy.rb,
lib/jss/api_object/categorizable.rb,
lib/jss/api_object/mobile_device.rb,
lib/jss/api_object/self_servable.rb,
lib/jss/client/management_action.rb,
lib/jss/api_object/netboot_server.rb,
lib/jss/api_object/scopable/scope.rb,
lib/jss/api_object/advanced_search.rb,
lib/jss/api_object/mac_application.rb,
lib/jss/api_object/network_segment.rb,
lib/jss/api_object/peripheral_type.rb,
lib/jss/api_object/group/user_group.rb,
lib/jss/api_object/removable_macaddr.rb,
lib/jss/api_object/distribution_point.rb,
lib/jss/api_object/management_history.rb,
lib/jss/api_object/self_servable/icon.rb,
lib/jss/api_object/computer_invitation.rb,
lib/jss/api_object/extension_attribute.rb,
lib/jss/api_object/restricted_software.rb,
lib/jss/api_object/criteriable/criteria.rb,
lib/jss/api_object/group/computer_group.rb,
lib/jss/api_object/configuration_profile.rb,
lib/jss/api_object/criteriable/criterion.rb,
lib/jss/api_object/software_update_server.rb,
lib/jss/api_object/management_history/ebook.rb,
lib/jss/api_object/group/mobile_device_group.rb,
lib/jss/api_object/mobile_device_application.rb,
lib/jss/api_object/management_history/hashlike.rb,
lib/jss/api_object/computer/application_installs.rb,
lib/jss/api_object/management_history/policy_log.rb,
lib/jss/api_object/management_history/audit_event.rb,
lib/jss/api_object/management_history/mdm_command.rb,
lib/jss/api_object/advanced_search/advanced_user_search.rb,
lib/jss/api_object/management_history/casper_remote_log.rb,
lib/jss/api_object/management_history/mac_app_store_app.rb,
lib/jss/api_object/management_history/mobile_device_app.rb,
lib/jss/api_object/management_history/casper_imaging_log.rb,
lib/jss/api_object/management_history/computer_usage_log.rb,
lib/jss/api_object/management_history/screen_sharing_log.rb,
lib/jss/api_object/management_history/user_location_change.rb,
lib/jss/api_object/advanced_search/advanced_computer_search.rb,
lib/jss/api_object/extension_attribute/user_extension_attribute.rb,
lib/jss/api_object/advanced_search/advanced_mobile_device_search.rb,
lib/jss/api_object/configuration_profile/osx_configuration_profile.rb,
lib/jss/api_object/extension_attribute/computer_extension_attribute.rb,
lib/jss/api_object/extension_attribute/mobile_device_extension_attribute.rb,
lib/jss/api_object/configuration_profile/mobile_device_configuration_profile.rb

Overview

A mix-in module providing object-updating via the JSS API.

Defined Under Namespace

Modules: Categorizable, Composer, Creatable, Criteriable, Extendable, FileUpload, Locatable, MDM, ManagementHistory, Matchable, Purchasable, Scopable, SelfServable, Sitable, Updatable, Uploadable, VPPable, Validate Classes: APIConnection, APIObject, Account, AdvancedComputerSearch, AdvancedMobileDeviceSearch, AdvancedSearch, AdvancedUserSearch, AlreadyExistsError, AuthenticationError, Building, Category, Client, Computer, ComputerExtensionAttribute, ComputerGroup, ComputerInvitation, Configuration, ConfigurationProfile, ConflictError, DBConnection, Department, DistributionPoint, EBook, ExtensionAttribute, FileServiceError, Group, Icon, InvalidConnectionError, InvalidDataError, LDAPServer, MacApplication, MissingDataError, MobileDevice, MobileDeviceApplication, MobileDeviceConfigurationProfile, MobileDeviceExtensionAttribute, MobileDeviceGroup, NetBootServer, NetworkSegment, NoSuchItemError, OSXConfigurationProfile, Package, Patch, PatchPolicy, Peripheral, PeripheralType, Policy, Preferences, RemovableMacAddress, RestrictedSoftware, Script, Server, Site, SoftwareUpdateServer, TimeoutError, UnmanagedError, UnsupportedError, User, UserExtensionAttribute, UserGroup, WebHook

Constant Summary collapse

MINIMUM_RUBY_VERSION =

The minimum Ruby version that works with this gem

'2.0.0'.freeze
MINIMUM_SERVER_VERSION =

The minimum JSS version that works with this gem, as returned by the API in the deprecated ‘jssuser’ resource

'9.4'.freeze
TIME_ZONE_OFFSET =

The current local UTC offset as a fraction of a day (Time.now.utc_offset is the offset in seconds, 60*60*24 is the seconds in a day)

Rational(Time.now.utc_offset, 60 * 60 * 24)
TRUE_FALSE =

These are handy for testing values without making new arrays, strings, etc every time.

[true, false].freeze
NIL_DATES =

When parsing a date/time data into a Time object, these will return nil

[0, nil, '', '0'].freeze
BLANK =

Empty strings are used in various places

''.freeze
VERSION =

The version of the JSS ruby gem

'0.13.0'.freeze
CONFIG =

The single instance of Configuration

JSS::Configuration.instance
DB_CNX =

The single instance of the DBConnection

DBConnection.instance
API =

Save the default connection in the API constant, mostly for backward compatibility.

@api
@@stdin_lines =

The contents of anything piped to stdin, split into lines. See stdin

nil

Class Method Summary collapse

Class Method Details

.api ⇒ JSS::APIConnection Also known as: api_connection, connection, active_connection

The currently active JSS::APIConnection instance.

Returns:



1183
1184
1185
 
# File 'lib/jss/api_connection.rb', line 1183

def self.api
  @api
end

.api_object_class(name) ⇒ Class

Given a name, singular or plural, of a JSS::APIObject subclass as a String or Symbol (e.g. :computer/‘computers’), return the class itself (e.g. JSS::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 JSS::APIObject subclass, singluar or plural

Returns:

  • (Class) —

    The class

Raises:



280
281
282
283
284
 
# File 'lib/jss/utility.rb', line 280

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

.api_object_names ⇒ Hash

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 JSS::Computer and both :policy and :policies are keys for JSS::Policy, and so on.

Returns:

  • (Hash) —

    APIObject subclass names to Classes



298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/jss/utility.rb', line 298

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? JSS::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

.array_to_rexml_array(element, list) ⇒ Array<REXML::Element>

Given an element name and an array of content, generate an Array of REXML::Element objects with that name, and matching content. Given element name ‘foo’ and the array [‘bar’,‘morefoo’] The array of REXML elements would render thus:

<foo>bar</foo>
<foo>morefoo</foo>

Parameters:

  • element (#to_s) —

    an element_name like :foo

  • list (Array<#to_s>) —

    an Array of element content such as [“bar”, :morefoo]

Returns:

  • (Array<REXML::Element>)

Raises:



339
340
341
342
343
344
345
346
347
 
# File 'lib/jss/utility.rb', line 339

def self.array_to_rexml_array(element, list)
  raise JSS::InvalidDataError, 'Arg. must be an Array.' unless list.is_a? Array
  element = element.to_s
  list.map do |v|
    e = REXML::Element.new(element)
    e.text = v
    e
  end
end

.db ⇒ Mysql

Returns The mysql database available through the DBConnection.instance.

Returns:

  • (Mysql) —

    The mysql database available through the DBConnection.instance



286
287
288
 
# File 'lib/jss/db_connection.rb', line 286

def self.db
  DB_CNX.db
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



569
570
571
 
# File 'lib/jss/utility.rb', line 569

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

.devmode? ⇒ Boolean

is devmode currently on?

Returns:

  • (Boolean) 


578
579
580
 
# File 'lib/jss/utility.rb', line 578

def self.devmode?
  @devmode
end

.epoch_to_time(epoch) ⇒ Time?

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.



262
263
264
265
 
# File 'lib/jss/utility.rb', line 262

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

.escape_xml(string) ⇒ String

Given a string of xml element text, escape any characters that would make XML unhappy.

* & => &amp;
* " => &quot;
* < => &lt;
* > => &gt;
* ' => &apos;

Parameters:

  • string (String) —

    the string to make xml-compliant.

Returns:

  • (String) —

    the xml-compliant string



322
323
324
 
# File 'lib/jss/utility.rb', line 322

def self.escape_xml(string)
  string.gsub(/&/, '&amp;').gsub(/\"/, '&quot;').gsub(/>/, '&gt;').gsub(/</, '&lt;').gsub(/'/, '&apos;')
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.19.15. 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.10",
 #  "10.6.11",
 #  "10.6.12",
 #  "10.6.13",
 #  "10.6.14",
 #  "10.6.15",
 #  "10.7.x",
 #  "10.8.x",
 #  "10.9.x",
 #  "10.10.x",
 #  "10.11.x",
 #  "10.12.x",
 #  "10.13.x",
 #  "10.14.x",
 #  "10.15.x",
 #  "10.16.x",
 #  "10.17.x",
 #  "10.18.x",
 #  "10.19.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.



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

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 15
  # (and hope apple doesn't do more than 15 maint releases for an OS)
  else
    ok_oses = []
    (maint.to_i..15).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.19.x
  ((min.to_i + 1)..19).each do |v|
    ok_oses << maj + '.' + v.to_s + '.x'
  end # each v
  ok_oses
end

.hash_to_rexml_array(hash) ⇒ Array<REXML::Element>

Given a simple Hash, convert it to an array of REXML Elements such that each key becomes an element, and its value becomes the text content of that element

Examples:

my_hash = {:foo => "bar", :baz => :morefoo}
xml = JSS.hash_to_rexml_array(my_hash)
xml.each{|x| puts x }

<foo>bar</foo>
<baz>morefoo</baz>

Parameters:

  • hash (Hash{#to_s => #to_s}) —

    the Hash to convert

Returns:

  • (Array<REXML::Element>) —

    the Array of REXML elements.

Raises:



365
366
367
368
369
370
371
372
373
374
 
# File 'lib/jss/utility.rb', line 365

def self.hash_to_rexml_array(hash)
  raise InvalidDataError, 'Arg. must be a Hash.' unless hash.is_a? Hash
  ary = []
  hash.each_pair do |k, v|
    el = REXML::Element.new k.to_s
    el.text = v
    ary << el
  end
  ary
end

.item_list_to_rexml_list(list_element, item_element, item_list, content = :name) ⇒ REXML::Element

Given an Array of Hashes with :id and/or :name keys, return a single REXML element with a sub-element for each item, each of which contains a :name or :id element.

e.g. :computers

e.g. :computer

Examples:

comps = [{:id=>2,:name=>'kimchi'},{:id=>5,:name=>'mantis'}]
xml = JSS.item_list_to_rexml_list(:computers, :computer , comps, :name)
puts xml
# output manually formatted for clarity. No newlines in the real xml string
<computers>
  <computer>
    <name>kimchi</name>
  </computer>
  <computer>
    <name>mantis</name>
  </computer>
</computers>

# if content is :id, then, eg. <name>kimchi</name> would be <id>2</id>

Parameters:

  • list_element (#to_s) —

    the name of the XML element that contains the list.

  • item_element (#to_s) —

    the name of each XML element in the list,

  • item_list (Array<Hash>) —

    an Array of Hashes each with a :name or :id key.

  • content (Symbol) (defaults to: :name) —

    which hash key should be used as the content of if list item? Defaults to :name

Returns:

  • (REXML::Element) —

    the item list as REXML



408
409
410
411
412
413
414
 
# File 'lib/jss/utility.rb', line 408

def self.item_list_to_rexml_list(list_element, item_element, item_list, content = :name)
  xml_list = REXML::Element.new  list_element.to_s
  item_list.each do |i|
    xml_list.add_element(item_element.to_s).add_element(content.to_s).text = i[content]
  end
  xml_list
end

.new_api_connection(args = {}) ⇒ APIConnection Also known as: new_connection, new_api

Create a new APIConnection object and use it for all future API calls. If connection options are provided, they are passed to the connect method immediately, otherwise JSS.api.connect must be called before attemting to use the connection.

Parameters:

Returns:



1151
1152
1153
1154
 
# File 'lib/jss/api_connection.rb', line 1151

def self.new_api_connection(args = {})
  @api = APIConnection.new args
  @api
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?



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
156
 
# File 'lib/jss/utility.rb', line 129

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_datetime(a_datetime) ⇒ Object

Deprecated - to be eventually removed in favor of the more-appropriately named JSS::parse_time

See Also:

  • parse_time


252
253
254
 
# File 'lib/jss/utility.rb', line 252

def self.parse_datetime(a_datetime)
  parse_time(a_datetime)
end

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

Parse a JSS Version number into something comparable.

With Jamf Pro 9.99, “Semantic Versioning” is used, see semver.org/

For versions less than 9.99 parsing is like this:

- Digits before the first dot are the Major Version
- The first digit after the first dot is the Minor Version
- Any other digits after the first dot but before a non-digit
  are the Revision
- Anything after a second dot is the build identifier
- Any non-digit anywhere means that it and everything after it
  are the build identifier

So 9.32 becomes major-9, minor-3, rev-2, build-” and 9.32.3764 becomes major-9, minor-3, rev-2, build-3764 and 9.32a3764 becomes major-9, minor-3, rev-2, build-a3764 and 9.32a1234.t234 becomes major-9, minor-3, rev-2, build-a1234.t234

This old style method of parsing will break if digits between the first dot and the second (or the end) ever gets above 99, since ‘100’ will become minor-1, rev-0

This method returns a Hash with these keys:

  • :major => the major version, Integer

  • :minor => the minor version, Integor

  • :maint => the revision, Integer (this is also available with the keys :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.

Parameters:

  • version (String) —

    a JSS version number from the API

Returns:

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

    the parsed version data.

Raises:



451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/jss/utility.rb', line 451

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

  # since ruby-jss requires 9.4 and up, this check works fine.
  if major == '9' && (second_part.to_i < 99)
    parse_jss_version_oldstyle version
  else
    parse_jss_version_newstyle version
  end
end

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

Parse a JSS Version number into something comparable.

With Jamf Pro 9.99, “Semantic Versioning” is used, see semver.org/

For versions less than 9.99 parsing is like this:

- Digits before the first dot are the Major Version
- The first digit after the first dot is the Minor Version
- Any other digits after the first dot but before a non-digit
  are the Revision
- Anything after a second dot is the build identifier
- Any non-digit anywhere means that it and everything after it
  are the build identifier

So 9.32 becomes major-9, minor-3, rev-2, build-” and 9.32.3764 becomes major-9, minor-3, rev-2, build-3764 and 9.32a3764 becomes major-9, minor-3, rev-2, build-a3764 and 9.32a1234.t234 becomes major-9, minor-3, rev-2, build-a1234.t234

This old style method of parsing will break if digits between the first dot and the second (or the end) ever gets above 99, since ‘100’ will become minor-1, rev-0

This method returns a Hash with these keys:

  • :major => the major version, Integer

  • :minor => the minor version, Integor

  • :maint => the revision, Integer (this is also available with the keys :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.

Parameters:

  • version (String) —

    a JSS version number from the API

Returns:

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

    the parsed version data.



464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/jss/utility.rb', line 464

def self.parse_jss_version_newstyle(version)
  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(version)
    version: Gem::Version.new("#{major}.#{minor}.#{revision}#{build}")
  }
end

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

Parse a JSS Version number into something comparable.

With Jamf Pro 9.99, “Semantic Versioning” is used, see semver.org/

For versions less than 9.99 parsing is like this:

- Digits before the first dot are the Major Version
- The first digit after the first dot is the Minor Version
- Any other digits after the first dot but before a non-digit
  are the Revision
- Anything after a second dot is the build identifier
- Any non-digit anywhere means that it and everything after it
  are the build identifier

So 9.32 becomes major-9, minor-3, rev-2, build-” and 9.32.3764 becomes major-9, minor-3, rev-2, build-3764 and 9.32a3764 becomes major-9, minor-3, rev-2, build-a3764 and 9.32a1234.t234 becomes major-9, minor-3, rev-2, build-a1234.t234

This old style method of parsing will break if digits between the first dot and the second (or the end) ever gets above 99, since ‘100’ will become minor-1, rev-0

This method returns a Hash with these keys:

  • :major => the major version, Integer

  • :minor => the minor version, Integor

  • :maint => the revision, Integer (this is also available with the keys :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.

Parameters:

  • version (String) —

    a JSS version number from the API

Returns:

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

    the parsed version data.



483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'lib/jss/utility.rb', line 483

def self.parse_jss_version_oldstyle(version)
  version =~ /^(\d+?)\.(.*)$/
  major = Regexp.last_match[1]
  second_part = Regexp.last_match[2].to_s

  minor = second_part[0]
  revision = second_part[1..-1]

  # if there's a non-digit anywhere in any part, it and everything after
  # is the build.
  if revision.to_s =~ /^(\d*)(\D.*)$/
    revision = Regexp.last_match[1]
    build = Regexp.last_match[2]
    # but remove a leading dot
    build = build[1..-1] if build.start_with? '.'
  end
  minor ||= ''
  revision ||= ''

  version_string = major.to_s
  unless minor.empty?
    version_string << ".#{minor}"
    version_string << ".#{revision}" unless revision.empty?
  end
  {
    major: major.to_i,
    minor:  minor.to_i,
    revision:  revision.to_i,
    maint:  revision.to_i,
    patch:  revision.to_i,
    build:  build.to_s,
    version:  Gem::Version.new(version_string)
  }
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.



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

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 JSS::MissingDataError, "No such file: #{plist}" unless plist.file?

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

.parse_time(a_datetime) ⇒ Time?

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.



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

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)
  if the_dt.offset.zero?
    the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, JSS::TIME_ZONE_OFFSET)
  end
  # 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?



110
111
112
113
114
 
# File 'lib/jss/utility.rb', line 110

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



548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/jss/utility.rb', line 548

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.



534
535
536
537
538
539
540
 
# File 'lib/jss/utility.rb', line 534

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?



520
521
522
 
# File 'lib/jss/utility.rb', line 520

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



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

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 JSS::InvalidDataError, 'Input must be a comma-separated String or an Array of Strings'
  end # case
  { stringform: valstr, arrayform: valarr }
end

.use_api_connection(connection) ⇒ APIConnection Also known as: use_api, use_connection, activate_connection

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:



1166
1167
1168
1169
 
# File 'lib/jss/api_connection.rb', line 1166

def self.use_api_connection(connection)
  raise 'API connections must be instances of JSS::APIConnection' unless connection.is_a? JSS::APIConnection
  @api = connection
end

.use_default_connection ⇒ void

This method returns an undefined value.

Make the default connection (Stored in JSS::API) active



1175
1176
1177
 
# File 'lib/jss/api_connection.rb', line 1175

def self.use_default_connection
  use_api_connection API
end