Class: Jamf::PatchPolicy

Inherits:
APIObject show all
Includes:
Creatable, Scopable, SelfServable, Updatable
Defined in:
lib/jamf/api/classic/api_objects/patch_policy.rb

Overview

A Patch Policy in the JSS

When making new Patch Polices :patch_title and :target_version must be provided as well as :name.

:patch_title is the name or id of a currently active patch title

:target_version is the string identfier of an available version of the title. The target version MUST have a package assigned to it.

See PatchTitle and Jamf::PatchSource.available_titles for methods to acquire such info.

See Also:

Constant Summary collapse

RSRC_BASE = 
'patchpolicies'.freeze
RSRC_LIST_KEY = 
:patch_policies
RSRC_OBJECT_KEY = 
:patch_policy
RSRC_BY_PATCH_TITLE = 
'patchpolicies/softwaretitleconfig/id/'.freeze
RSRC_BY_PATCH_TITLE_LIST_KEY =

TODO: complain to jamf about this - should be the same as RSRC_LIST_KEY

:"patch policies"
SCOPE_TARGET_KEY = 
:computers
AUTO_INSTALL_GRACE_PERIOD_MESSAGE = 
'$APP_NAMES will quit in $DELAY_MINUTES minutes so that $SOFTWARE_TITLE can be updated. Save anything you are working on and quit the app(s).'.freeze
DFT_ENABLED = 
false
DFT_DISTRIBUTION =

the default dist method - not in ssvc

'prompt'.freeze
NO_DEADLINE =

the value of #deadline when there is no deadline

:none
DFT_DEADLINE = 
7
DFT_GRACE_PERIOD =

The valud of #grace_period when not defined

15
DFT_GRACE_PERIOD_SUBJECT = 
'Important'.freeze
DFT_GRACE_PERIOD_MESSAGE = 
'$APP_NAMES will quit in $DELAY_MINUTES minutes so that $SOFTWARE_TITLE can be updated. Save anything you are working on and quit the app(s).'.freeze
USE_XML_WORKAROUND =

See XMLWorkaround

{
  patch_policy: {
    general: {
      id: -1,
      name: Jamf::BLANK,
      enabled: nil,
      target_version: Jamf::BLANK,
      release_date: 0,
      incremental_update: nil,
      reboot: nil,
      minimum_os: Jamf::BLANK,
      kill_apps: [
        {
          kill_app_name: Jamf::BLANK,
          kill_app_bundle_id: Jamf::BLANK
        }
      ],
      distribution_method: Jamf::BLANK,
      allow_downgrade: nil,
      patch_unknown: nil
    },
    scope: {
      all_computers: nil,
      computers: [
        {
          id: -1,
          name: Jamf::BLANK,
          udid: Jamf::BLANK
        }
      ],
      computer_groups: [
        {
          id: -1,
          name: Jamf::BLANK
        }
      ],
      users: [
        {
          id: -1,
          username: Jamf::BLANK
        }
      ],
      user_groups: [
        {
          id: -1,
          name: Jamf::BLANK
        }
      ],
      buildings: [
        {
          id: -1,
          name: Jamf::BLANK
        }
      ],
      departments: [
        {
          id: -1,
          name: Jamf::BLANK
        }
      ],
      limitations: {
        network_segments: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        ibeacons: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ]
      },
      exclusions: {
        computers: [
          {
            id: -1,
            name: Jamf::BLANK,
            udid: Jamf::BLANK
          }
        ],
        computer_groups: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        users: [
          {
            id: -1,
            username: Jamf::BLANK
          }
        ],
        user_groups: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        buildings: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        departments: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        network_segments: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ],
        ibeacons: [
          {
            id: -1,
            name: Jamf::BLANK
          }
        ]
      }
    },
    user_interaction: {
      install_button_text: Jamf::BLANK,
      self_service_description: Jamf::BLANK,
      self_service_icon: {
        id: -1,
        filename: Jamf::BLANK,
        uri: Jamf::BLANK
      },
      notifications: {
        notification_enabled: nil,
        notification_type: Jamf::BLANK,
        notification_subject: Jamf::BLANK,
        notification_message: Jamf::BLANK,
        reminders: {
          notification_reminders_enabled: nil,
          notification_reminder_frequency: 1
        }
      },
      deadlines: {
        deadline_enabled: nil,
        deadline_period: 7
      },
      grace_period: {
        grace_period_duration: 15,
        notification_center_subject: 'Important',
        message: AUTO_INSTALL_GRACE_PERIOD_MESSAGE
      }
    },
    software_title_configuration_id: 2
  }
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**data) ⇒ PatchPolicy

When making new Patch Polices :patch_title is required and is a Jamf::PatchTitle or the name or id of one

If target_version: is provided, it must exist in the PatchTitle, and must have a package assigned to it.



365
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
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 365

def initialize(**data)
  super

  # creation...
  unless in_jss
    @init_data[:general] ||= {}
    @init_data[:software_title_configuration_id] = validate_patch_title @init_data[:patch_title]

    # were we given target_version in the make params?
    validate_target_version @init_data[:target_version] if @init_data[:target_version]
    @init_data[:general][:target_version] = @init_data[:target_version]

    # other defaults
    @init_data[:general][:enabled] = false
    @init_data[:general][:allow_downgrade] = false
    @init_data[:general][:patch_unknown] = false
    @init_data[:general][:distribution_method] = DFT_DISTRIBUTION
  end

  @patch_title_id = @init_data[:software_title_configuration_id]

  gen = @init_data[:general]
  @enabled = gen[:enabled]
  @target_version = gen[:target_version]
  @allow_downgrade = gen[:allow_downgrade]
  @patch_unknown = gen[:patch_unknown]

  @init_data[:user_interaction] ||= {}

  deadlines = @init_data[:user_interaction][:deadlines]
  deadlines ||= {}
  deadlines[:deadline_period] = DFT_DEADLINE if deadlines[:deadline_period].to_s.empty?
  @deadline = deadlines[:deadline_enabled] ? deadlines[:deadline_period] : NO_DEADLINE

  grace = @init_data[:user_interaction][:grace_period]
  grace ||= {}

  @grace_period = grace[:grace_period_duration]
  @grace_period = DFT_GRACE_PERIOD if @grace_period.to_s.empty?

  @grace_period_subject = grace[:notification_center_subject]
  @grace_period_subject = DFT_GRACE_PERIOD_SUBJECT if @grace_period_subject.to_s.empty?

  @grace_period_message = grace[:message]
  @grace_period_message = DFT_GRACE_PERIOD_MESSAGE if @grace_period_message.to_s.empty?

  # read-only values, they come from the version.
  @release_date = JSS.epoch_to_time gen[:release_date]
  @incremental_update = gen[:incremental_update]
  @reboot = gen[:reboot]
  @minimum_os = gen[:minimum_os]
  @kill_apps = gen[:kill_apps]
end

Instance Attribute Details

#allow_downgrade ⇒ Boolean Also known as: allow_downgrade?, downgradable?

Can this title be downgraded to this version?



315
316
317
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 315

def allow_downgrade
  @allow_downgrade
end

#deadline ⇒ Integer, Symnol

How many days is the install deadline?



330
331
332
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 330

def deadline
  @deadline
end

#enabled ⇒ Boolean (readonly) Also known as: enabled? 



279
280
281
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 279

def enabled
  @enabled
end

#grace_period ⇒ Integer Also known as: grace_period_duration 



336
337
338
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 336

def grace_period
  @grace_period
end

#grace_period_message ⇒ String 



350
351
352
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 350

def grace_period_message
  @grace_period_message
end

#grace_period_subject ⇒ String Also known as: grace_period_notification_center_subject 



343
344
345
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 343

def grace_period_subject
  @grace_period_subject
end

#icon ⇒ Jamf::Icon? Also known as: self_service_icon Originally defined in module SelfServable

#in_self_service ⇒ Boolean (readonly) Also known as: in_self_service? Originally defined in module SelfServable

#incremental_update ⇒ Boolean (readonly) Also known as: incremental_update? 



296
297
298
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 296

def incremental_update
  @incremental_update
end

#kill_apps ⇒ Array<Hash> (readonly) 



310
311
312
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 310

def kill_apps
  @kill_apps
end

#minimum_os ⇒ String (readonly) 



306
307
308
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 306

def minimum_os
  @minimum_os
end

#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable

#patch_title_id ⇒ Integer (readonly) Also known as: software_title_id, software_title_configuration_id 



355
356
357
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 355

def patch_title_id
  @patch_title_id
end

#patch_unknown ⇒ Boolean Also known as: patch_unknown?

Can this policy run when we don’t know the prev. version?



322
323
324
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 322

def patch_unknown
  @patch_unknown
end

#reboot ⇒ Boolean (readonly) Also known as: reboot_required, reboot?, reboot_required? 



300
301
302
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 300

def reboot
  @reboot
end

#release_date ⇒ Time (readonly) 



293
294
295
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 293

def release_date
  @release_date
end

#scope ⇒ Object Originally defined in module Scopable

Attribtues

#self_service_categories ⇒ Array<Hash> (readonly) Originally defined in module SelfServable

Each Hash has these keys about the category

  • :id => [Integer] the JSS id of the category

  • :name => [String] the name of the category

Most objects also include one or both of these keys:

  • :display_in => [Boolean] should the item be displayed in this category in SSvc? (not MobDevConfProfiles)

  • :feature_in => [Boolean] should the item be featured in this category in SSVC? (macOS targets only)

#self_service_description ⇒ String Originally defined in module SelfServable

#self_service_display_name ⇒ String Also known as: self_service_dislay_name Originally defined in module SelfServable

#self_service_feature_on_main_page ⇒ Boolean Originally defined in module SelfServable

Only applicable to macOS targets

#self_service_force_users_to_view_description ⇒ Boolean Originally defined in module SelfServable

#self_service_install_button_text ⇒ String Originally defined in module SelfServable

defaults to ‘Install’

#self_service_notification_message ⇒ String Originally defined in module SelfServable

#self_service_notification_subject ⇒ String Originally defined in module SelfServable

object name.

#self_service_notification_type ⇒ Symbol Originally defined in module SelfServable

#self_service_notifications_enabled ⇒ Boolean Also known as: self_service_notifications_enabled? Originally defined in module SelfServable

#self_service_reinstall_button_text ⇒ String Originally defined in module SelfServable

defaults to ‘Reinstall’

#self_service_reminder_frequency ⇒ Integer Originally defined in module SelfServable

#self_service_reminders_enabled ⇒ Boolean Also known as: self_service_reminders_enabled? Originally defined in module SelfServable

#self_service_removal_password ⇒ String (readonly) Originally defined in module SelfServable

#self_service_user_removable ⇒ Symbol Originally defined in module SelfServable

#target_version ⇒ String Also known as: version

When setting, the version must exist in the policy’s PatchTitle, and have a package assigned to it.



289
290
291
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 289

def target_version
  @target_version
end

Class Method Details

.all_for_title(title, api: nil, cnx: Jamf.cnx) ⇒ Array<Hash>

Fetch name and id of all PatchPolicies tied to a given PatchTitle

Raises:



252
253
254
255
256
257
258
259
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 252

def self.all_for_title(title, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  title_id = Jamf::PatchTitle.valid_id title
  raise Jamf::NoSuchItemError, "No PatchTitle matching '#{title}'" unless title_id

  cnx.c_get("#{RSRC_BY_PATCH_TITLE}#{title_id}")[RSRC_BY_PATCH_TITLE_LIST_KEY]
end

.fetch(searchterm = nil, **args) ⇒ Object

Override APIObject.fetch, since there’s no …/patchpolicies/name/… endpoint

See Also:



264
265
266
267
268
269
270
271
272
273
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 264

def self.fetch(searchterm = nil, **args)
  name_search = args.delete :name
  if name_search
    id = valid_id name_search
    raise Jamf::NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found #{err_detail}" unless id

    args[:id] = id
  end
  super
end

Instance Method Details

#add_self_service_category(new_cat, display_in: true, feature_in: false) ⇒ void Also known as: set_self_service_category, change_self_service_category Originally defined in module SelfServable

This method returns an undefined value.

Add or change one of the categories for this item in self service

Raises:

#add_to_self_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Add this object to self service if not already there.

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

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

Raises:

#create ⇒ Integer

Create a new PatchPolicy in the JSS



534
535
536
537
538
539
540
541
542
543
544
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 534

def create
  validate_for_saving
  # TODO: prepare for more cases where the POST rsrc is
  # different from the PUT/GET/DELETE.
  orig_rsrc = @rest_rsrc
  @rest_rsrc = "#{RSRC_BY_PATCH_TITLE}#{CGI.escape patch_title_id.to_s}"
  super
  @rest_rsrc = orig_rsrc
  refetch_version_info
  id
end

#disable ⇒ void

This method returns an undefined value.

disable this policy



463
464
465
466
467
468
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 463

def disable
  return unless enabled

  @enabled = false
  @need_to_update = true
end

#enable ⇒ void

This method returns an undefined value.

enable this policy



452
453
454
455
456
457
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 452

def enable
  return if enabled

  @enabled = true
  @need_to_update = true
end

#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.

Raises:

#parse_scope ⇒ void Originally defined in module Scopable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Call this during initialization of objects that have a scope and the scope instance will be created from @init_data

#patch_title(refresh = false) ⇒ Jamf::PatchTitle?

The Jamf::PatchTitle to for this PatchPolicy



425
426
427
428
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 425

def patch_title(refresh = false)
  @patch_title = nil if refresh
  @patch_title ||= Jamf::PatchTitle.fetch id: patch_title_id
end

#patch_title_name ⇒ String 



432
433
434
435
436
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 432

def patch_title_name
  return @patch_title.name if @patch_title

  Jamf::PatchTitle.map_all_ids_to(:name)[software_title_configuration_id]
end

#remove_from_self_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Remove this object from self service if it’s there.

#remove_self_service_category(cat) ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Remove a category from those for this item in SSvc

#self_service_execute_url ⇒ String Originally defined in module SelfServable

#self_service_payload ⇒ Symbol Originally defined in module SelfServable

What does this object deploy to the device via self service?

#self_service_targets ⇒ Array<Symbol> Originally defined in module SelfServable

What devices types can get this thing in Self Service

#self_service_view_url ⇒ String Originally defined in module SelfServable

#should_update ⇒ void Originally defined in module Scopable

This method returns an undefined value.

When the scope changes, it calls this to tell us that an update is needed.

#update ⇒ Integer

Update an existing PatchPolicy with changes from ruby



550
551
552
553
554
555
556
 
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 550

def update
  validate_for_saving
  super
  refetch_version_info if @refetch_for_new_version
  @refetch_for_new_version = false
  id
end

#upload(type, local_file, force_ipa_upload: false) ⇒ Boolean Originally defined in module Uploadable

instance method wrapper for class method

Upload a file to the JSS to be stored with this instance of the class mixing in the Uploadable module

Raises:

#user_removable? ⇒ Boolean? Originally defined in module SelfServable

Can this thing be removed by the user?