Class: JSS::PatchTitle

Inherits:
APIObject show all
Includes:
Categorizable, Creatable, Sitable, Updatable
Defined in:
lib/jss/api_object/patch_title.rb,
lib/jss/api_object/patch_title/version.rb

Overview

An active Patch Software Title in the JSS.

This class provides access to titles that have been added to Jamf Pro via a PatchInternalSource or a PatchExternalSource, and the versions contained therein.

Patch versions for the title are available in the #versions read-only attribute, a Hash of versions keyed by the version string. The values are JSS::PatchTitle::Version objects.

When creating/activating new Patch Titles, with .make, a unique name:, a source: and a name_id: must be provided - the source must be the name or id of an existing PatchSource, and the name_id must be offered by that source. Once created, the source_id and name_id cannot be changed.

When fetching titles, they can be fetched by id:, source_name_id:, or both source: and name_id:

WARNING: While they can be fetched by name, beware: the JSS does not enforce unique names of titles even thought ruby-jss does. If there are duplicates of the name you fetch, which one you get is undefined.

Use the patch_report class or instance method, or PatchTitle::Version.patch_report, to retrieve a report of computers with a specific version of the title installed, or :all, :latest, or :unknown versions. Reports called on the class or an instance default to :all versions, and are slower to retrieve than a specific version,

See Also:

Defined Under Namespace

Classes: Version

Constant Summary collapse

USE_XML_WORKAROUND =

TODO: remove this and adjust parsing when jamf fixes the JSON Data map for PatchTitle XML data parsing cuz Borked JSON

See Also:

  • for details
{
  patch_software_title: {
    id: -1,
    name: JSS::BLANK,
    name_id: JSS::BLANK,
    source_id: -1,
    notifications: {
      email_notification: nil,
      web_notification: nil
    },
    category: {
      id: -1,
      name: JSS::BLANK
    },
    site: {
      id: -1,
      name: JSS::BLANK
    },
    versions: [
      {
        software_version: JSS::BLANK,
        package: {
          id: -1,
          name: JSS::BLANK
        }
      }
    ]
  }
}.freeze
PATCH_REPORT_DATA_MAP =

TODO: remove this and adjust parsing when jamf fixes the JSON Data map for PatchReport XML data parsing cuz Borked JSON

See Also:

  • for details
{
  patch_report: {
    name: JSS::BLANK,
    patch_software_title_id: -1,
    total_computers: 0,
    total_versions: 0,
    versions: [
      {
        software_version: JSS::BLANK,
        computers: [
          {
            id: -1,
            name: JSS::BLANK,
            mac_address: JSS::BLANK,
            alt_mac_address: JSS::BLANK,
            serial_number: JSS::BLANK
          }
        ]
      }
    ]
  }
}.freeze
RSRC_BASE =

The base for REST resources of this class

'patchsoftwaretitles'.freeze
RSRC_LIST_KEY =

the hash key used for the JSON list output of all objects in the JSS

:patch_software_titles
RSRC_OBJECT_KEY =

The hash key used for the JSON object output. It's also used in various error messages

:patch_software_title
VALID_DATA_KEYS =

these keys, as well as :id and :name, are present in valid API JSON data for this class

i[notifications name_id source_id].freeze
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry TODO: comfirm this in 10.4

604
SITE_SUBSET =
:top
CATEGORY_SUBSET =

Where is the Category in the API JSON?

:top
CATEGORY_DATA_TYPE =

How is the category stored in the API data?

Hash
LATEST_VERSION_ID =

when fetching a specific version, this is a valid version

'Latest'.freeze
UNKNOWN_VERSION_ID =

when fetching a specific version, this is a valid version

'Unknown'.freeze
REPORTS_RSRC_BASE =
'/patchreports/patchsoftwaretitleid'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**args) ⇒ PatchTitle


366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
# File 'lib/jss/api_object/patch_title.rb', line 366

def initialize(**args)
  super

  if in_jss
    @name_id = @init_data[:name_id]
    @source_id = @init_data[:source_id]
  else
    # source: and source_id: are considered the same, source_id: wins
    @init_data[:source_id] ||= @init_data[:source]

    raise JSS::MissingDataError, 'source: and name_id: must be provided' unless @init_data[:name_id] && @init_data[:source_id]

    @source_id = JSS::PatchSource.valid_id(@init_data[:source_id])

    raise JSS::NoSuchItemError, "No Patch Sources match '#{@init_data[:source]}'" unless source_id

    @name_id = @init_data[:name_id]

    valid_name_id = JSS::PatchSource.available_name_ids(@source_id).include? @name_id

    raise JSS::NoSuchItemError, "source #{@init_data[:source]} doesn't offer name_id '#{@init_data[:name_id]}'" unless valid_name_id
  end

  @source_name_id = "#{@source_id}-#{@name_id}"

  @init_data[:notifications] ||= {}
  notifs = @init_data[:notifications]
  @web_notification = notifs[:web_notification].nil? ? false : notifs[:web_notification]
  @email_notification = notifs[:email_notification].nil? ? false : notifs[:email_notification]

  @versions = {}
  @init_data[:versions] ||= []
  @init_data[:versions].each do |vers|
    @versions[vers[:software_version]] = JSS::PatchTitle::Version.new(self, vers)
  end # each do vers

  @changed_pkgs = []
end

Instance Attribute Details

#email_notificationBoolean Also known as: email_notification?


362
363
364
# File 'lib/jss/api_object/patch_title.rb', line 362

def email_notification
  @email_notification
end

#name_idString (readonly)


348
349
350
# File 'lib/jss/api_object/patch_title.rb', line 348

def name_id
  @name_id
end

#need_to_updateBoolean (readonly) Originally defined in module Updatable

#source_idInteger (readonly)


352
353
354
# File 'lib/jss/api_object/patch_title.rb', line 352

def source_id
  @source_id
end

#source_name_idString (readonly)


355
356
357
# File 'lib/jss/api_object/patch_title.rb', line 355

def source_name_id
  @source_name_id
end

#web_notificationBoolean Also known as: web_notification?


358
359
360
# File 'lib/jss/api_object/patch_title.rb', line 358

def web_notification
  @web_notification
end

Class Method Details

.all(refresh = false, source_id: nil, api: JSS.api) ⇒ Object

The same as @see APIObject.all but also takes an optional source_id: parameter, which limites the results to patch titles with the specified source_id.

Also - since the combined source_id and name_id are unique, create an identifier key ':source_name_id' by joining them with '-'

JAMF BUG: More broken json - the id is coming as a string. so here we turn it into an integer manually :-( Ditto for source_id


174
175
176
177
178
179
180
181
182
183
# File 'lib/jss/api_object/patch_title.rb', line 174

def self.all(refresh = false, source_id: nil, api: JSS.api)
  data = super refresh, api: api
  data.each do |info|
    info[:id] = info[:id].to_i
    info[:source_name_id] = "#{info[:source_id]}-#{info[:name_id]}"
    info[:source_id] = info[:source_id].to_i
  end
  return data unless source_id
  data.select { |p| p[:source_id] == source_id }
end

.all_ids(refresh = false, source_id: nil, api: JSS.api) ⇒ Object

The same as @see APIObject.all_ids but also takes an optional source_id: parameter, which limites the results to patch titles with the specified source_id.


197
198
199
# File 'lib/jss/api_object/patch_title.rb', line 197

def self.all_ids(refresh = false, source_id: nil, api: JSS.api)
  all(refresh, source_id: source_id, api: api).map { |i| i[:id] }
end

.all_names(refresh = false, source_id: nil, api: JSS.api) ⇒ Object

The same as @see APIObject.all_names but also takes an optional source_id: parameter, which limites the results to patch titles with the specified source_id.


189
190
191
# File 'lib/jss/api_object/patch_title.rb', line 189

def self.all_names(refresh = false, source_id: nil, api: JSS.api)
  all(refresh, source_id: source_id, api: api).map { |i| i[:name] }
end

.all_source_ids(refresh = false, api: JSS.api) ⇒ Array<Integer>

Returns an Array of unique source_ids used by active Patches

e.g. if there are patches that come from one internal source and two external sources this might return [1,3,4].

Regardless of how many patches come from each source, the source id appears only once in this array.


216
217
218
# File 'lib/jss/api_object/patch_title.rb', line 216

def self.all_source_ids(refresh = false, api: JSS.api)
  all(refresh, api: api).map { |i| i[:source_id] }.sort.uniq
end

.all_source_name_ids(refresh = false, api: JSS.api) ⇒ Array<String>


222
223
224
# File 'lib/jss/api_object/patch_title.rb', line 222

def self.all_source_name_ids(refresh = false, api: JSS.api)
  all(refresh, api: api).map { |i| i[:source_name_id] }
end

.fetch(identifier = nil, **params) ⇒ Object

Patch titles only have an id-based GET resource in the API. so all other lookup values have to be converted to ID before the call to super


303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
# File 'lib/jss/api_object/patch_title.rb', line 303

def self.fetch(identifier = nil, **params)
  # default api
  api = params[:api] ? params[:api] : JSS.api

  # source: and source_id: are considered the same, source_id: wins
  params[:source_id] ||= params[:source]

  # if given a source name, this converts it to an id
  params[:source_id] = JSS::PatchSource.valid_id params[:source_id]

  # build a possible source_name_id
  params[:source_name_id] ||= "#{params[:source_id]}-#{params[:name_id]}"

  id =
    if identifier
      valid_id identifier
    elsif params[:id]
      all_ids.include?(params[:id]) ? params[:id] : nil
    elsif params[:source_name_id]
      map_all_ids_to(:source_name_id).invert[params[:source_name_id]]
    elsif params[:name]
      map_all_ids_to(:name).invert[params[:name]]
    end

  raise JSS::NoSuchItemError, "No matching #{name} found" unless id

  super id: id, api: api
end

.patch_report(title, version: :all, api: JSS.api) ⇒ Hash

Get a patch report for a softwaretitle, withouth fetching an instance. Defaults to reporting all versions. Specifiying a version will be faster.

The Hash returned has 3 keys:

- :total_comptuters [Integer] total computers found for the requested version(s)
- :total versions [Integer] How many versions does this title have?
    Always 1 if you report a specific version
- :versions [Hash {String => Array<Hash>}] Keys are the version(s) requested
  values are Arrays of Hashes, one per computer with the keyed version
  installed. Computer Hashes have identifiers as keys.

PatchTitle#patch_report calls this method, as does PatchTitle::Version.patch_report.


252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
# File 'lib/jss/api_object/patch_title.rb', line 252

def self.patch_report(title, version: :all, api: JSS.api)
  title_id = valid_id title, api: api
  raise JSS::NoSuchItemError, "No PatchTitle matches '#{title}'" unless title_id

  rsrc = patch_report_rsrc title_id, version

  # TODO: remove this and adjust parsing when jamf fixes the JSON
  raw_report = XMLWorkaround.data_via_xml(rsrc, PATCH_REPORT_DATA_MAP, api)[:patch_report]
  report = {}
  report[:total_computers] = raw_report[:total_computers]
  report[:total_versions] = raw_report[:total_versions]

  if raw_report[:versions].is_a? Hash
    vs = raw_report[:versions][:version][:software_version].to_s
    comps = raw_report[:versions][:version][:computers]
    comps = [] if comps.empty?
    report[:versions] = { vs => comps }
    return report
  end

  report[:versions] = {}
  raw_report[:versions].each do |v|
    report[:versions][v[:software_version].to_s] = v[:computers].empty? ? [] : v[:computers]
  end
  report
end

.valid_id(ident, refresh = false, api: JSS.api) ⇒ Object

Override the APIObject.valid_id, since patch sources are so non-standard Accept id, source_name_id, or name. Note name may not be unique, and if not, ymmv


336
337
338
339
340
341
# File 'lib/jss/api_object/patch_title.rb', line 336

def self.valid_id(ident, refresh = false, api: JSS.api)
  id = all_ids(refresh, api: api).include?(ident) ? ident : nil
  id ||= map_all_ids_to(:source_name_id).invert[ident]
  id ||= map_all_ids_to(:name).invert[ident]
  id
end

Instance Method Details

#category=(new_cat) ⇒ void Originally defined in module Categorizable

This method returns an undefined value.

Change the category of this object. Any of the NON_CATEGORIES values will unset the category

#category_assigned?Boolean Also known as: categorized? Originally defined in module Categorizable

Does this object have a category assigned?

#category_idInteger Originally defined in module Categorizable

The id of the category for this object.

#category_nameString Also known as: category Originally defined in module Categorizable

The name of the category for this object. For backward compatibility, this is aliased to just 'category'

#category_objectJSS::Category Originally defined in module Categorizable

The JSS::Category instance for this object's category

#changed_pkg_for_version(version) ⇒ Object

this is called by JSS::PatchTitle::Version#package= to update @changed_pkgs which is used by #rest_xml to change the package assigned to a patch version in this title.


449
450
451
452
# File 'lib/jss/api_object/patch_title.rb', line 449

def changed_pkg_for_version(version)
  @changed_pkgs << version
  @need_to_update = true
end

#clone(new_name, api: nil) ⇒ APIObject Originally defined in module Creatable

make a clone of this API object, with a new name. The class must be creatable

#createObject

wrapper to fetch versions after creating


455
456
457
458
# File 'lib/jss/api_object/patch_title.rb', line 455

def create
  response = super
  response
end

#evaluate_new_category(new_cat) ⇒ Array<String, Integer> Originally defined in module Categorizable

Given a category name or id, return the name and id TODO: use APIObject.exist? and/or APIObject.valid_id

#name=(newname) ⇒ void Originally defined in module Updatable

This method returns an undefined value.

Change the name of this item Remember to #update to push changes to the server.

#patch_report(vers = :all) ⇒ Object Also known as: version_report, report

Get a patch report for this title.

See the class method JSS::PatchTitle.patch_report


471
472
473
# File 'lib/jss/api_object/patch_title.rb', line 471

def patch_report(vers = :all)
  JSS::PatchTitle.patch_report id, version: vers, api: @api
end

#pretty_print_instance_variablesArray

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


483
484
485
486
487
# File 'lib/jss/api_object/patch_title.rb', line 483

def pretty_print_instance_variables
  vars = super
  vars.delete :@versions
  vars
end

#site=(new_site) ⇒ void Originally defined in module Sitable

This method returns an undefined value.

Change the site of this object. Any of the NON_SITES values will unset the site

#site_assigned?Boolean Originally defined in module Sitable

Does this object have a site assigned?

#site_idInteger Originally defined in module Sitable

The id of the site for this object.

#site_nameString Also known as: site Originally defined in module Sitable

The name of the site for this object. For backward compatibility, this is aliased to just 'site'

#site_objectJSS::Site Originally defined in module Sitable

The JSS::Site instance for this object's site

#unset_categoryvoid Originally defined in module Categorizable

This method returns an undefined value.

Set the category to nothing

#unset_sitevoid Originally defined in module Sitable

This method returns an undefined value.

Set the site to nothing

#updateObject

wrapper to clear @changed_pkgs after updating


461
462
463
464
465
# File 'lib/jss/api_object/patch_title.rb', line 461

def update
  response = super
  @changed_pkgs.clear
  response
end

#versionsHash{String => JSS::PatchTitle::Version}


407
408
409
410
411
412
# File 'lib/jss/api_object/patch_title.rb', line 407

def versions
  return @versions unless in_jss
  return @versions unless @versions.empty?
  # if we are in jss, and versions is empty, re-fetch them
  @versions = self.class.fetch(id: id).versions
end

#versions_with_packagesHash


418
419
420
# File 'lib/jss/api_object/patch_title.rb', line 418

def versions_with_packages
  versions.select { |_ver_string, vers| vers.package_assigned? }
end