Class: Windoo::SoftwareTitle

Inherits:
BaseClasses::JSONObject show all
Includes:
Mixins::APICollection, Mixins::SoftwareTitle::ExtensionAttribute
Defined in:
lib/windoo/objects/software_title.rb

Overview

A Software Title in the Title Editor

NOTE: SoftwareTitles cannot be enabled when created. You must call ‘enable’ on them after creating any necessary sub-objects.

Constant Summary collapse

LOCAL_TITLE_EDITOR_SOURCE_NAME =

Constants

'Local'
LOCAL_TITLE_EDITOR_SOURCE_ID = 
0
RSRC_PATH = 
'softwaretitles'
CONTAINER_CLASS = 
nil
JSON_ATTRIBUTES =

Attributes not defined in the superclasses

{

  # @!attribute softwareTitleId
  #   @return [Integer] The id of this title in the Title Editor
  softwareTitleId: {
    class: :Integer,
    # primary means this is the one used to fetch via API calls
    identifier: :primary,
    readonly: true,
    do_not_send: true
  },

  # @!attribute id
  # @return [String] A string, unique any patch source (in this case
  #   the TitleEditor), that identifies this Software Title.
  #   Can be thought of as the unique name on the Title Editor.
  #   Not to be confused with the 'name' attribute, which is more
  #   of a Display Name, and is not unique
  id: {
    class: :String,
    # true means this is a unique value in and can be used to find a valid
    # primary identifier.
    identifier: true,
    # required means this value is required to create or update this
    # object on the server(s)
    required: true
  },

  # @!attribute enabled
  #   @return [Boolean] Is this title enabled, and available to be subscribed to?
  enabled: {
    class: :Boolean
  },

  # @!attribute name
  #   @return [String] The name of this title in the Title Editor. NOT UNIQUE,
  #     and not an identfier. See 'id'.
  name: {
    class: :String,
    required: true
  },

  # @!attribute publisher
  #   @return [String] The publisher of this software
  publisher: {
    class: :String,
    required: true
  },

  # @attribute appName
  #   @return [String] Currently not used by the Title Editor
  #      or Jamf Pro Patch Titles.
  #      There is no matching data in the Web UI.
  #      These data exist in the killApps associated with Patches
  appName: {
    class: :String
  },

  # @attribute bundleId
  #   @return [String] Currently not used by the Title Editor
  #      or Jamf Pro Patch Titles.
  #      There is no matching data in the Web UI.
  #      These data exist in the killApps associated with Patches
  bundleId: {
    class: :String
  },

  # @!attribute lastModified
  #   @return [Time]  When was the title last modified, in UTC?
  #     @note This timestamp is only valid as of the last time
  #       you fetched this SoftwareTitle or updated one of its
  #       immediate attributes (i.e. not arrays of other API
  #       objects like requirements or patches.)
  #       To be sure of the most recent time, accounting for
  #       potential updates from other places (like the Web UI)
  #       you should re-fetch the Title
  lastModified: {
    class: :Time,

    # for classes (like Time) that are not Symbols (like :String)
    # This is the Class method to call on them to convert the
    # raw API data into the ruby value we want. The API data
    # will be passed as the sole param to this method.
    # For most, it will be :new, but for, e.g., Time, it is
    # :parse
    to_ruby: :to_time,

    # The method to call on the value when converting to
    # data to be sent to the API.
    # e.g. on Time values, convert to iso8601
    # to_api: :iso8601

    # attributes with this set to true are never
    # sent to the server when creating or updating
    do_not_send: true,
    readonly: true
  },

  # @!attribute currentVersion
  #   @return [String] the version number of the most recent patch
  currentVersion: {
    class: :String,
    required: true
  },

  # This value only appears in the .all summary hash, not in the
  # full instance init_data.
  #
  # _!attribute source
  # _return [String] The name of the Patch Source that ultimately
  #   hosts this title definition. If hosted by our TitleEditor
  #   directly, this is LOCAL_TITLE_EDITOR_SOURCE_NAME
  #
  #   @todo implement external patches.
  # source: {
  #   class: :String
  # },

  # @!attribute sourceId
  # @return [Integer] The id of the Patch Source that ultimately
  #   hosts this title definition. If hosted by our TitleEditor
  #   directly, this is LOCAL_TITLE_EDITOR_SOURCE_ID
  #
  #   @todo implement external patches.
  # sourceId: {
  #   class: :Integer,
  #   do_not_send: true
  # },

  # @!attribute requirements
  #   @return [Array<Windoo::Requirement>] The requirements - criteria that
  #     define which computers have the software installed.
  requirements: {
    class: Windoo::RequirementManager,
    do_not_send: true,
    readonly: true
  },

  # @!attribute patches
  #   @return [Array<Windoo::Patch>] The patches available for this title
  patches: {
    class: Windoo::PatchManager,
    do_not_send: true,
    readonly: true
  },

  # @!attribute extensionAttributes
  #   @return [Windoo::ExtensionAttribute] The Extension Attribute used by this title.
  #     NOTE: See the module Windoo::Mixins::SoftwareTitle::ExtentionAttribute
  extensionAttribute: {
    class: Windoo::ExtensionAttribute,
    do_not_send: true,
    readonly: true
  }
}.freeze

Constants inherited from BaseClasses::JSONObject

BaseClasses::JSONObject::PP_OMITTED_INST_VARS

Instance Attribute Summary collapse

Attributes inherited from BaseClasses::JSONObject

#init_data

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mixins::SoftwareTitle::ExtensionAttribute

#add_extensionAttribute, #delete_extensionAttribute

Methods included from Mixins::APICollection

#==, #cnx, #container, #create_on_server, #delete, #deleted_id, included, #pretty_print_instance_variables, #primary_id, #softwareTitle, #update_on_server

Methods inherited from BaseClasses::JSONObject

attribute_already_parsed?, ident_keys, json_attributes, json_attributes_parsed, mutable?, parse_json_attributes, #pretty_print_instance_variables, primary_id_key, required_attributes, #to_api, #to_json, validate_attr

Constructor Details

#initialize(**init_data) ⇒ SoftwareTitle

Construcor



333
334
335
336
337
338
 
# File 'lib/windoo/objects/software_title.rb', line 333

def initialize(**init_data)
  super

  @requirements = Windoo::RequirementManager.new @requirements, container: self
  @patches = Windoo::PatchManager.new @patches, container: self
end

Instance Attribute Details

#appName ⇒ String

Returns Currently not used by the Title Editor or Jamf Pro Patch Titles. There is no matching data in the Web UI. These data exist in the killApps associated with Patches.

Returns:

  • (String) —

    Currently not used by the Title Editor or Jamf Pro Patch Titles. There is no matching data in the Web UI. These data exist in the killApps associated with Patches




# File 'lib/windoo/objects/software_title.rb', line 224

#bundleId ⇒ String

Returns Currently not used by the Title Editor or Jamf Pro Patch Titles. There is no matching data in the Web UI. These data exist in the killApps associated with Patches.

Returns:

  • (String) —

    Currently not used by the Title Editor or Jamf Pro Patch Titles. There is no matching data in the Web UI. These data exist in the killApps associated with Patches




# File 'lib/windoo/objects/software_title.rb', line 233

#currentVersion ⇒ String

Returns the version number of the most recent patch.

Returns:

  • (String) —

    the version number of the most recent patch




# File 'lib/windoo/objects/software_title.rb', line 273

#enabled ⇒ Boolean

Returns Is this title enabled, and available to be subscribed to?.

Returns:

  • (Boolean) —

    Is this title enabled, and available to be subscribed to?




# File 'lib/windoo/objects/software_title.rb', line 203

#extensionAttributes ⇒ Windoo::ExtensionAttribute

Returns The Extension Attribute used by this title. NOTE: See the module Windoo::Mixins::SoftwareTitle::ExtentionAttribute.

Returns:

  • (Windoo::ExtensionAttribute) —

    The Extension Attribute used by this title. NOTE: See the module Windoo::Mixins::SoftwareTitle::ExtentionAttribute




# File 'lib/windoo/objects/software_title.rb', line 321

#id ⇒ String

Returns A string, unique any patch source (in this case the TitleEditor), that identifies this Software Title. Can be thought of as the unique name on the Title Editor. Not to be confused with the ‘name’ attribute, which is more of a Display Name, and is not unique.

Returns:

  • (String) —

    A string, unique any patch source (in this case the TitleEditor), that identifies this Software Title. Can be thought of as the unique name on the Title Editor. Not to be confused with the ‘name’ attribute, which is more of a Display Name, and is not unique




# File 'lib/windoo/objects/software_title.rb', line 187

#lastModified ⇒ Time

Returns When was the title last modified, in UTC? @note This timestamp is only valid as of the last time

you fetched this SoftwareTitle or updated one of its
immediate attributes (i.e. not arrays of other API
objects like requirements or patches.)
To be sure of the most recent time, accounting for
potential updates from other places (like the Web UI)
you should re-fetch the Title.

Returns:

  • (Time) —

    When was the title last modified, in UTC? @note This timestamp is only valid as of the last time

    you fetched this SoftwareTitle or updated one of its
immediate attributes (i.e. not arrays of other API
objects like requirements or patches.)
To be sure of the most recent time, accounting for
potential updates from other places (like the Web UI)
you should re-fetch the Title




# File 'lib/windoo/objects/software_title.rb', line 242

#name ⇒ String

Returns The name of this title in the Title Editor. NOT UNIQUE, and not an identfier. See ‘id’.

Returns:

  • (String) —

    The name of this title in the Title Editor. NOT UNIQUE, and not an identfier. See ‘id’.




# File 'lib/windoo/objects/software_title.rb', line 209

#patches ⇒ Array<Windoo::Patch>

Returns The patches available for this title.

Returns:

  • (Array<Windoo::Patch>) —

    The patches available for this title




# File 'lib/windoo/objects/software_title.rb', line 313

#publisher ⇒ String

Returns The publisher of this software.

Returns:

  • (String) —

    The publisher of this software




# File 'lib/windoo/objects/software_title.rb', line 217

#requirements ⇒ Array<Windoo::Requirement>

Returns The requirements - criteria that define which computers have the software installed.

Returns:

  • (Array<Windoo::Requirement>) —

    The requirements - criteria that define which computers have the software installed.




# File 'lib/windoo/objects/software_title.rb', line 304

#softwareTitleId ⇒ Integer

Returns The id of this title in the Title Editor.

Returns:

  • (Integer) —

    The id of this title in the Title Editor




# File 'lib/windoo/objects/software_title.rb', line 177

#sourceId ⇒ Integer

sourceId: 

class: :Integer,
do_not_send: true

,

Returns:

  • (Integer) —

    The id of the Patch Source that ultimately hosts this title definition. If hosted by our TitleEditor directly, this is LOCAL_TITLE_EDITOR_SOURCE_ID

    @todo implement external patches.




# File 'lib/windoo/objects/software_title.rb', line 293

Class Method Details

.all(cnx: Windoo.cnx) ⇒ Array<Hash>

Software Titles are the only collection resource that has an endpoint that returns summary list.

All others, patches, components, ext attrs, etc… can only be individually accessed using their primary identifier, so the .all and .valid_id methods are not applicable to them.

.all returns summmary Hashes for all Software Titles in the Title Editor the Hash keys are:

:softwareTitleId=>1, :enabled=>false, :name=>“Test”, :publisher=>“Some Company”, :appName=>nil, :bundleId=>nil, :lastModified=>“2022-09-10T22:06:39Z”, :currentVersion=>“5.0.1”, :requirements=>3, :patches=>0, # Number of enabled patches, not existing patches? :id=>“com.somecompany.test”, :sourceId=>0, :source=>“Local”

Returns:

  • (Array<Hash>) 


66
67
68
 
# File 'lib/windoo/objects/software_title.rb', line 66

def self.all(cnx: Windoo.cnx)
  cnx.get(self::RSRC_PATH)
end

.all_ids(cnx: Windoo.cnx) ⇒ Array<String>

Returns The ids (unique names) of all titles.

Returns:

  • (Array<String>) —

    The ids (unique names) of all titles



72
73
74
 
# File 'lib/windoo/objects/software_title.rb', line 72

def self.all_ids(cnx: Windoo.cnx)
  all(cnx: cnx).map { |t| t[:id] }
end

.all_softwareTitleIds(cnx: Windoo.cnx) ⇒ Array<Integer>

Returns The all_softwareTitleIds (numeric id numbers) of all titles.

Returns:

  • (Array<Integer>) —

    The all_softwareTitleIds (numeric id numbers) of all titles



78
79
80
 
# File 'lib/windoo/objects/software_title.rb', line 78

def self.all_softwareTitleIds(cnx: Windoo.cnx)
  all(cnx: cnx).map { |t| t[:softwareTitleId] }
end

.autofill_patches(ident, cnx: Windoo.cnx) ⇒ Array<Hash>

Get the ‘autofill patches’ for a given software title

Parameters:

  • ident (String, Integer) —

    An identifier for a software title

Returns:

  • (Array<Hash>) —

    the autofill patch data



152
153
154
155
156
 
# File 'lib/windoo/objects/software_title.rb', line 152

def self.autofill_patches(ident, cnx: Windoo.cnx)
  id = valid_id ident, raise_if_not_found: true, cnx: cnx

  cnx.get("#{self::RSRC_PATH}/#{id}/patches/autofill")
end

.autofill_requirements(ident, cnx: Windoo.cnx) ⇒ Array<Hash>

Get the ‘autofill requirements’ for a given software title

Parameters:

  • ident (String, Integer) —

    An identifier for a software title

Returns:

  • (Array<Hash>) —

    the autofill requirement data



164
165
166
167
168
 
# File 'lib/windoo/objects/software_title.rb', line 164

def self.autofill_requirements(ident, cnx: Windoo.cnx)
  id = valid_id ident, raise_if_not_found: true, cnx: cnx

  cnx.get("#{self::RSRC_PATH}/#{id}/requirements/autofill")
end

.fetch(ident = nil, cnx: Windoo.cnx, **key_and_ident) ⇒ Windoo::SoftwareTitle

Override the method from APICollection, because SoftwareTitles can be looked up by both the primary_ident (softwareTitleId) and secondary (id)

Returns:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/windoo/objects/software_title.rb', line 88

def self.fetch(ident = nil, cnx: Windoo.cnx, **key_and_ident)
  unless ident || !key_and_ident.empty?
    raise ArgumentError,
          "ident, or 'key: ident' is required to fetch #{self.class}"
  end

  id =
    if ident
      valid_id ident, raise_if_not_found: true, cnx: cnx
    else
      key, ident = key_and_ident.first

      # Dont call valid_id if we are fetching based on the primary_id_key
      # just used the value provided. The API will complain if it
      # doesn't exist
      key == primary_id_key ? ident : valid_id(ident, key: key, raise_if_not_found: true, cnx: cnx)
    end

  init_data = cnx.get("#{self::RSRC_PATH}/#{id}")
  init_data[:cnx] = cnx
  init_data[:fetching] = true

  new(**init_data)
end

.valid_id(ident, key: nil, raise_if_not_found: false, cnx: Windoo.cnx) ⇒ Integer?

Returns given any identifier, return the matching primary id or nil if no match.

Parameters:

  • ident (Integer, String) —

    the identifier value to search for

  • key (Symbol) (defaults to: nil) —

    if given, Only look for the value in this key.

Returns:

  • (Integer, nil) —

    given any identifier, return the matching primary id or nil if no match

Raises:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/windoo/objects/software_title.rb', line 120

def self.valid_id(ident, key: nil, raise_if_not_found: false, cnx: Windoo.cnx)
  matched_summary =
    if key
      all(cnx: cnx).select { |summary| summary[key] == ident }.first
    else
      find_summary_for_ident(ident, cnx: cnx)
    end

  value = matched_summary ? matched_summary[primary_id_key] : nil

  raise Windoo::NoSuchItemError, "No #{self} found for identifier '#{ident}'" if raise_if_not_found && value.nil?

  value
end

Instance Method Details

#autofill_patches ⇒ Array<Hash>

Get the ‘autofill patches’ for this software title

Returns:

  • (Array<Hash>) —

    the autofill patch data



345
346
347
348
 
# File 'lib/windoo/objects/software_title.rb', line 345

def autofill_patches
  id = send self.class.primary_id_key
  self.class.autofill_patches id
end

#autofill_requirements ⇒ Array<Hash>

Get the ‘autofill requirements’ for this software title

Returns:

  • (Array<Hash>) —

    the autofill requirement data



352
353
354
355
 
# File 'lib/windoo/objects/software_title.rb', line 352

def autofill_requirements
  id = send self.class.primary_id_key
  self.class.autofill_requirements id
end

#disable ⇒ Object

Disable this SoftwareTitle



371
372
373
374
375
376
 
# File 'lib/windoo/objects/software_title.rb', line 371

def disable
  return unless enabled?

  self.enabled = false
  :disabled
end

#enable ⇒ Object

Enable this SoftwareTitle



358
359
360
361
362
363
364
365
366
367
368
 
# File 'lib/windoo/objects/software_title.rb', line 358

def enable
  return if enabled?

  if requirements.empty? || patches.all_enabled.empty?
    raise Windoo::MissingDataError,
          'SoftwareTitles must have at least one requirement and one enabled patch before they can be enabled'
  end

  self.enabled = true
  :enabled
end

#update_modification_time ⇒ Object

Update our modification timestamp from other objects to the current time when they are changed on the server.



380
381
382
 
# File 'lib/windoo/objects/software_title.rb', line 380

def update_modification_time
  @lastModified = Time.now.utc
end