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 =
{
  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.



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
418
419
420
421
422
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 368

def initialize(**data)
  super

  # creation...
  unless in_jss
    @init_data[:general] ||= {}
    @init_data[:software_title_configuration_id] = validate_patch_title @init_data[:patch_title]
    # need this set here for the validations below
    @patch_title_id = @init_data[:software_title_configuration_id]

    # 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_downgradeBoolean Also known as: allow_downgrade?, downgradable?

Can this title be downgraded to this version?

Parameters:

  • new_val (Boolean)

Returns:

  • (Boolean)


318
319
320
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 318

def allow_downgrade
  @allow_downgrade
end

#deadlineInteger, Symnol

How many days is the install deadline?

Parameters:

  • days (Integer, Symbol)

    :none, or a positive integer. Integers < 1 have the same meaning as :none

Returns:

  • (Integer, Symnol)

    :none, or a positive integer



333
334
335
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 333

def deadline
  @deadline
end

#enabledBoolean (readonly) Also known as: enabled?

Returns is this patch policy enabled?.

Returns:

  • (Boolean)

    is this patch policy enabled?



282
283
284
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 282

def enabled
  @enabled
end

#grace_periodInteger Also known as: grace_period_duration

Returns How many minutes does the user have to quit the killapps?.

Parameters:

  • new_period (Integer)

    Negative integers will be saved as 0

Returns:

  • (Integer)

    How many minutes does the user have to quit the killapps?



339
340
341
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 339

def grace_period
  @grace_period
end

#grace_period_messageString

Returns The message displayed asking the user to quit the killapps within @grace_period minutes.

Parameters:

  • subj (String)

    the new message

Returns:

  • (String)

    The message displayed asking the user to quit the killapps within @grace_period minutes



353
354
355
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 353

def grace_period_message
  @grace_period_message
end

#grace_period_subjectString Also known as: grace_period_notification_center_subject

Returns The Subject of the message displayed asking the user to quit the killapps within @grace_period minutes.

Parameters:

  • subj (String)

    the new subject

Returns:

  • (String)

    The Subject of the message displayed asking the user to quit the killapps within @grace_period minutes



346
347
348
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 346

def grace_period_subject
  @grace_period_subject
end

#iconJamf::Icon? Also known as: self_service_icon Originally defined in module SelfServable

Returns The icon used in self-service.

Returns:

  • (Jamf::Icon, nil)

    The icon used in self-service

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

Returns Is this thing available in Self Service?.

Returns:

  • (Boolean)

    Is this thing available in Self Service?

#incremental_updateBoolean (readonly) Also known as: incremental_update?

Returns must this patch be installed only over the prev. version?.

Returns:

  • (Boolean)

    must this patch be installed only over the prev. version?



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

def incremental_update
  @incremental_update
end

#kill_appsArray<Hash> (readonly)

Returns The apps that cannot be running when this is installed. each Hash contains :kill_app_name and :kill_app_bundle_id, both Strings.

Returns:

  • (Array<Hash>)

    The apps that cannot be running when this is installed. each Hash contains :kill_app_name and :kill_app_bundle_id, both Strings



313
314
315
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 313

def kill_apps
  @kill_apps
end

#minimum_osString (readonly)

Returns The min. OS version require to install this patch.

Returns:

  • (String)

    The min. OS version require to install this patch



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

def minimum_os
  @minimum_os
end

#need_to_updateBoolean (readonly) Originally defined in module Updatable

Returns do we have unsaved changes?.

Returns:

  • (Boolean)

    do we have unsaved changes?

#patch_title_idInteger (readonly) Also known as: software_title_id, software_title_configuration_id

Returns the id of the Jamf::PatchTitle for this policy. Can be set with the patch_title: param of .make, but is read-only after that.

Returns:

  • (Integer)

    the id of the Jamf::PatchTitle for this policy. Can be set with the patch_title: param of .make, but is read-only after that.



358
359
360
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 358

def patch_title_id
  @patch_title_id
end

#patch_unknownBoolean Also known as: patch_unknown?

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

Parameters:

  • new_val (Boolean)

Returns:

  • (Boolean)


325
326
327
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 325

def patch_unknown
  @patch_unknown
end

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

Returns does this patch require a reboot after installation?.

Returns:

  • (Boolean)

    does this patch require a reboot after installation?



303
304
305
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 303

def reboot
  @reboot
end

#release_dateTime (readonly)

Returns when the target_version was released.

Returns:

  • (Time)

    when the target_version was released



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

def release_date
  @release_date
end

#scopeObject Originally defined in module Scopable

Attribtues

#self_service_categoriesArray<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)

Returns:

  • (Array<Hash>)

    The categories in which this item should appear in SSvc

#self_service_descriptionString Originally defined in module SelfServable

Returns The verbage that appears in SelfSvc for this item.

Returns:

  • (String)

    The verbage that appears in SelfSvc for this item

#self_service_display_nameString Also known as: self_service_dislay_name Originally defined in module SelfServable

Returns The name to display in macOS Self Service.

Returns:

  • (String)

    The name to display in macOS Self Service.

#self_service_feature_on_main_pageBoolean Originally defined in module SelfServable

Only applicable to macOS targets

Returns:

  • (Boolean)

    Should this item feature on the main page of SSvc?

#self_service_force_users_to_view_descriptionBoolean Originally defined in module SelfServable

Returns Should an extra window appear before the user can install the item? (OSX SSvc only).

Returns:

  • (Boolean)

    Should an extra window appear before the user can install the item? (OSX SSvc only)

#self_service_install_button_textString Originally defined in module SelfServable

defaults to ‘Install’

Returns:

  • (String)

    The text label on the install button in SSvc (OSX SSvc only)

#self_service_notification_messageString Originally defined in module SelfServable

Returns The message text of the notification.

Returns:

  • (String)

    The message text of the notification

#self_service_notification_subjectString Originally defined in module SelfServable

object name.

Returns:

  • (String)

    The subject text of the notification. Defaults to the

#self_service_notification_typeSymbol Originally defined in module SelfServable

Returns How should notifications be sent either :ssvc_only or :ssvc_and_nctr.

Returns:

  • (Symbol)

    How should notifications be sent either :ssvc_only or :ssvc_and_nctr

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

Returns Should jamf send notifications to self service?.

Returns:

  • (Boolean)

    Should jamf send notifications to self service?

#self_service_reinstall_button_textString Originally defined in module SelfServable

defaults to ‘Reinstall’

Returns:

  • (String)

    The text label on the reinstall button in SSvc (OSX SSvc only)

#self_service_reminder_frequencyInteger Originally defined in module SelfServable

Returns How often (in days) should reminders be given.

Returns:

  • (Integer)

    How often (in days) should reminders be given

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

Returns Should self service give reminders by displaying the notification repeatedly?.

Returns:

  • (Boolean)

    Should self service give reminders by displaying the notification repeatedly?

#self_service_removal_passwordString (readonly) Originally defined in module SelfServable

Returns The password needed for removal, in plain text.

Returns:

  • (String)

    The password needed for removal, in plain text.

#self_service_user_removableSymbol Originally defined in module SelfServable

Returns one of the keys in PROFILE_REMOVAL_BY_USER.

Returns:

  • (Symbol)

    one of the keys in PROFILE_REMOVAL_BY_USER

#target_versionString Also known as: version

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

Parameters:

  • new_tgt_vers (String)

    the new version for this Patch Policy.

Returns:

  • (String)

    The version deployed by this policy



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

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

Parameters:

  • title (String, Integer)

    the name or id of the PatchTitle for which to retrieve a list of patch policies

Returns:

  • (Array<Hash>)

    the :id and :name of each policy for the title

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
274
275
276
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 264

def self.fetch(searchterm = nil, **args)
  cnx = args[:cnx]
  cnx ||= Jamf.cnx

  name_search = args.delete :name
  if name_search
    id = valid_id name_search, cnx: cnx
    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

Parameters:

  • new_cat (String, Integer)

    the name or id of a category where this object should appear in SelfSvc

  • display_in (Boolean) (defaults to: true)

    should this item appear in the SelfSvc page for the category? Only meaningful in applicable classes

  • feature_in (Boolean) (defaults to: false)

    should this item be featured in the SelfSvc page for the category? Only meaningful in applicable classes. NOTE: this will always be false if display_in is false.

Raises:

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

Parameters:

  • name (String)

    the name for the new object

  • cnx (Jamf::Connection) (defaults to: nil)

    the API in which to create the object Defaults to the API used to instantiate this object

Returns:

  • (APIObject)

    An unsaved clone of this APIObject with the given name

Raises:

#createInteger

Create a new PatchPolicy in the JSS

Returns:

  • (Integer)

    the id of the new policy



539
540
541
542
543
544
545
546
547
548
549
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 539

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

#disablevoid

This method returns an undefined value.

disable this policy



468
469
470
471
472
473
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 468

def disable
  return unless enabled

  @enabled = false
  @need_to_update = true
end

#enablevoid

This method returns an undefined value.

enable this policy



457
458
459
460
461
462
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 457

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.

Parameters:

  • newname (String)

    the new name

Raises:

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

Parameters:

  • refresh (Boolean) (defaults to: false)

    Should the Title be re-fetched from the API?

Returns:



430
431
432
433
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 430

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

#patch_title_nameString

Returns the name of the PatchTitle for this patch policy.

Returns:

  • (String)

    the name of the PatchTitle for this patch policy



437
438
439
440
441
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 437

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_servicevoid 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

Parameters:

  • cat (String, Integer)

    the name or id of the category to remove

#self_service_execute_urlString Originally defined in module SelfServable

Returns The url to view this thing in Self Service.

Returns:

  • (String)

    The url to view this thing in Self Service

#self_service_payloadSymbol Originally defined in module SelfServable

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

Returns:

  • (Symbol)

    :profile, :app, or :policy

#self_service_targetsArray<Symbol> Originally defined in module SelfServable

What devices types can get this thing in Self Service

Returns:

  • (Array<Symbol>)

    An array of :macos, :ios, or both.

#self_service_view_urlString Originally defined in module SelfServable

Returns The url to view this thing in Self Service.

Returns:

  • (String)

    The url to view this thing in Self Service

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

#updateInteger

Update an existing PatchPolicy with changes from ruby

Returns:

  • (Integer)

    the id of the policy



555
556
557
558
559
560
561
# File 'lib/jamf/api/classic/api_objects/patch_policy.rb', line 555

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

Parameters:

  • type (Symbol)

    the type of upload happening. Must be one of the keys defined in the class’s UPLOAD_TYPES Hash.

  • local_file (String, Pathname)

    String or Pathname pointing to the locally-readable file to be uploaded.

  • force_ipa_upload (Boolean) (defaults to: false)

    Should the server upload the .ipa file to JCDS or AWS if such are confgured for use?

Returns:

  • (Boolean)

    was the upload successful?

Raises:

#user_removable?Boolean? Originally defined in module SelfServable

Can this thing be removed by the user?

Returns:

  • (Boolean, nil)

    nil means ‘not applicable’