Class: Jamf::Policy

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

Overview

A class implementing a JSS Policy.

Like many API objects, the data comes from the API in sections, and the items in the :general section are mapped to direct attributes of this Class.

Policy instances are partially read-only:

  • Due to limitations in the API implementation of policies, as well as the complexity of policy objects, only these attributes can be set and updated via the Policy class:

    • name

    • frequency

    • target_drive

    • offline

    • enabled

    • category

    • triggers

    • client maintenance tasks

    • files and processes

    • reboot options

All other values and sections must be edited via the Web App.

Policies may be deleted via this class

Constant Summary collapse

RSRC_BASE =

The base for REST resources of this class

'policies'.freeze
RSRC_LIST_KEY =

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

:policies
RSRC_OBJECT_KEY =

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

:policy
SUBSETS =

subsets available for fetching TODO: FilesProcesses and Maintenance don't seem to work

%i[
  general
  scope
  selfservice
  self_service
  packages
  scripts
  printers
  dockitems
  dock_items
  reboot
  userinteraction
  user_interaction
  disk_encryption
  diskencryption
  accountmaintenance
  account_maintenance
].freeze
UPLOAD_TYPES =

policies can take uploaded icons

{ icon: :policies }.freeze
SELF_SERVICE_TARGET =

policies are available in macOS self Serviec

:macos
SELF_SERVICE_PAYLOAD =

policies via self services are still polcies

:policy
SECTIONS = 
%i[
  general
  maintenance
  account_maintenance
  scripts
  self_service
  package_configuration
  scope
  user_interaction
  reboot
  files_processes
  dock_items
  disk_encryption
  printers
].freeze
FREQUENCIES = 
{
  ongoing: 'Ongoing',
  once_per_computer: 'Once per computer',
  once_per_user: 'Once per user',
  once_per_user_per_computer: 'Once per user per computer',
  daily: 'Once every day',
  weekly: 'Once every week',
  monthly: 'Once every month'
}.freeze
RETRY_EVENTS = 
{
  none: 'none',
  checkin: 'check-in',
  trigger: 'trigger'
}.freeze
RESTART_WHEN = 
{
  if_pkg_requires: 'Restart if a package or update requires it',
  now: 'Restart immediately',
  delayed: 'Restart',
  dont: 'Do not restart'
}.freeze
RESTART_DISKS = 
{
  current: 'Current Startup Disk',
  selected: 'Currently Selected Startup Disk (No Bless)',
  netboot: 'NetBoot',
  os_installer: 'inPlaceOSUpgradeDirectory'
}.freeze
ACCOUNT_ACTIONS =

Note: any other value in :specify_startup is a path to some other drive to boot from, e.g. /Volumes/Foo

{
  create: 'Create',
  change_pw: 'Reset',
  delete: 'Delete',
  disable_fv2: 'DisableFileVault'
}.freeze
MGMT_ACCOUNT_ACTIONS = 
{
  no_change: 'doNotChange',
  change_pw: 'specified',
  generate_pw: 'random',
  enable_fv2: 'fileVaultEnable',
  disable_fv2: 'fileVaultDisable',
  reset_random: 'resetRandom',
  reset_pw: 'reset'
}.freeze
PACKAGE_ACTIONS = 
{
  install: 'Install',
  remove: 'Uninstall',
  cache: 'Cache',
  install_cache: 'Install Cached'
}.freeze
SCRIPT_PRIORITIES = 
{
  pre: 'Before',
  before: 'Before',
  post: 'After',
  after: 'After'
}.freeze
DISK_ENCRYPTION_ACTIONS = 
{
  apply: "apply",
  remediate: "remediate",
  none: "none"
}
PRINTER_ACTIONS = 
{
  map: 'install',
  unmap: 'uninstall'
}.freeze
DOCK_ITEM_ACTIONS = 
{
  add_start: 'Add To Beginning',
  add_end: 'Add To End', remove: 'Remove'
}.freeze
NETWORK_REQUIREMENTS = 
{
  any: 'Any',
  ethernet: 'EtherNet'
}.freeze
TRIGGER_TYPES = 
{
  event: 'EVENT',
  user: 'USER_INITIATED'
}.freeze
TRIGGER_EVENTS = 
{
  startup: :trigger_startup,
  login: :trigger_login,
  logout: :trigger_logout,
  checkin: :trigger_checkin,
  network_state: :trigger_network_state_changed,
  enrollment: :trigger_enrollment_complete,
  custom: :trigger_other
}.freeze
NO_USER_LOGGED_IN = 
[
  'Do not restart',
  'Restart immediately',
  'Restart if a package or update requires it'
].freeze
USER_LOGGED_IN = 
[
  'Do not restart',
  'Restart',
  'Restart if a package or update requires it',
  'Restart immediately'
].freeze
SCOPE_TARGET_KEY = 
:computers
LOG_FLUSH_RSRC =

Log Flushing

'logflush'.freeze
LOG_FLUSH_INTERVAL_INTEGERS = 
{
  0 => 'Zero',
  1 => 'One',
  2 => 'Two',
  3 => 'Three',
  6 => 'Six'
}.freeze
LOG_FLUSH_INTERVAL_PERIODS = 
{
  day: 'Days',
  days: 'Days',
  week: 'Weeks',
  weeks: 'Weeks',
  month: 'Months',
  months: 'Months',
  year: 'Years',
  years: 'Years'
}.freeze
OBJECT_HISTORY_OBJECT_TYPE =

the object type for this object in the object history table. See APIObject#add_object_history_entry

3
SITE_SUBSET =

Where is the Site data in the API JSON?

:general
CATEGORY_SUBSET =

Where is the Category in the API JSON?

:general
CATEGORY_DATA_TYPE =

How is the category stored in the API data?

Hash
SCRIPT_PARAMETERS_AVAILABLE =

All valid script parameters

%i[parameter4 parameter5 parameter6 parameter7 parameter8 parameter9 parameter10 parameter11].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**args) ⇒ Policy

Returns a new instance of Policy.

See Also:



699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 699

def initialize(**args)
  super

  if @in_jss
    gen = @init_data[:general]
    @target_drive = gen[:target_drive]
    @offline = gen[:offline]
    @enabled = gen[:enabled]
    @site = Jamf::APIObject.get_name(gen[:site][:name])
    @override_default_settings = gen[:override_default_settings]
    @trigger = gen[:trigger]
    @trigger_events = {
      trigger_startup: gen[:trigger_startup],
      trigger_login: gen[:trigger_login],
      trigger_logout: gen[:trigger_logout],
      trigger_checkin: gen[:trigger_checkin],
      trigger_network_state_changed: gen[:trigger_network_state_changed],
      trigger_enrollment_complete: gen[:trigger_enrollment_complete],
      trigger_other: gen[:trigger_other]
    }
    @frequency = gen[:frequency]
    @retry_event = gen[:retry_event]
    @retry_attempts = gen[:retry_attempts]
    @notify_failed_retries = gen[:notify_on_each_failed_retry]

    dtl = gen[:date_time_limitations]

    @server_side_limitations = {
      activation: JSS.epoch_to_time(dtl[:activation_date_epoch]),
      expiration: JSS.epoch_to_time(dtl[:expiration_date_epoch])
    }

    @client_side_limitations = {
      no_execute_on: dtl[:no_execute_on], # NOTE- there's a bug in the JSON output, it's been reported to JAMF.
      no_execute_start: dtl[:no_execute_start], # String like "1:01 AM"
      no_execute_end: dtl[:no_execute_end], # String like "2:02 PM"
      network_requirements: gen[:network_requirements]
    }

    maint = @init_data[:maintenance]
    @verify_startup_disk = maint[:verify]
    @permissions_repair = maint[:permissions]
    @recon = maint[:recon]
    @fix_byhost = maint[:byhost]
    @reset_name = maint[:reset_name]
    @flush_system_cache = maint[:system_cache]
    @install_cached_pkgs = maint[:install_all_cached_packages]
    @flush_user_cache = maint[:user_cache]

    amaint = @init_data[:account_maintenance]
    @directory_bindings = amaint[:directory_bindings]
    @open_firmware_efi_password = amaint[:open_firmware_efi_password]
    @management_account = amaint[:management_account]
    @accounts = amaint[:accounts]

    @packages = @init_data[:package_configuration][:packages] ? @init_data[:package_configuration][:packages] : []

    @scripts = @init_data[:scripts]

    uint = @init_data[:user_interaction]
    @user_may_defer = uint[:allow_users_to_defer]
    @user_may_defer_until = Jamf.parse_time uint[:allow_deferral_until_utc]
    @user_message_start =  uint[:message_start]
    @user_message_finish = uint[:message_finish]

    @reboot_options = @init_data[:reboot]

    @files_processes = @init_data[:files_processes]

    @dock_items = @init_data[:dock_items]

    @disk_encryption = @init_data[:disk_encryption]

    @printers = @init_data[:printers]
    @printers.shift

    # Not in jss yet
  end

  # set non-nil defaults
  @enabled ||= false
  @frequency ||= 'Once per computer'
  @target_drive ||= '/'
  @offline ||= false
  @override_default_settings ||= {}
  @scripts ||= []
  @server_side_limitations ||= {}
  @client_side_limitiations ||= {}
  @trigger_events ||= {}
  @directory_bindings ||= []
  @open_firmware_efi_password ||= {}
  @management_account ||= {}
  @accounts  ||= []
  @packages  ||= []
  @scripts ||= []
  @self_service ||= {}
  @dock_items ||= []
  @disk_encryption ||= {}
  @printers ||= []
  @files_processes ||= {}
  unless @reboot_options
    @reboot_options = {}
    @reboot_options[:user_logged_in] = 'Do not restart'
    @reboot_options[:no_user_logged_in] = 'Do not restart'
  end

  @scope ||= Jamf::Scopable::Scope.new(:computers, all_computers: false)
end

Instance Attribute Details

#accounts ⇒ Array<Hash> (readonly)

Local accts acted-upon by this policy

Keys are:

  • :action => “Create”,

  • :hint => “foo bar”,

  • :picture => “/path/to/pic.tif”,

  • :admin => true,

  • :home => “/Users/chrisltest”,

  • :realname => “ChrisTest Lasell”,

  • :filevault_enabled => true,

  • :username => “chrisltest”,

  • :password_md5 => “3858f62230ac3c915f300c664312c63f”,

  • :password => “foobar”,

  • :password_sha256=> “c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2”

TODO: make individial getters/setters as for @files_processes

Returns:



584
585
586
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 584

def accounts
  @accounts
end

#client_side_limitations ⇒ Hash (readonly)

The client-side limitations of this policy.

The keys are:

  • :no_execute_on - An array of short day names as strings, e.g. [“Sun”, “Mon”, “Tue”]

  • :no_execute_start - Time

  • :no_execute_end - Time

  • :network_connection - String

The data for the first three comes from the API in the date_time_limitations hash of the general section. The fourth comes from the network_requirements of the general section of the API, but the UI shows them in the Client Side Limitations area.

This attribute is just for convience and consistency, and just refers to the data in their API locations

Returns:



473
474
475
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 473

def client_side_limitations
  @client_side_limitations
end

#directory_bindings ⇒ Array<Hash> (readonly)

The directory bindings applied

each hash is like: {:name => “LDAP”, :id => 4} TODO: handle as for packages & scripts

Returns:



547
548
549
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 547

def directory_bindings
  @directory_bindings
end

#disk_encryption ⇒ Hash (readonly)

Disk encryption options for this policy

The hash looks like {:disk_encryption_configuration_id => 3, :action => “apply”}

Returns:



684
685
686
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 684

def disk_encryption
  @disk_encryption
end

#dock_items ⇒ Array<Hash> (readonly)

The dock items handled by this policy

each item hash looks like: {:name => “Mail”, :id => 14, :action => “Add To Beginning”}

Returns:



677
678
679
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 677

def dock_items
  @dock_items
end

#enabled ⇒ Boolean Also known as: enabled?

Returns is the policy enabled?.

Returns:

  • (Boolean) —

    is the policy enabled?



391
392
393
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 391

def enabled
  @enabled
end

#fix_byhost ⇒ Boolean

Should this policy fix the ByHost prefs?

Returns:

  • (Boolean) —

    client maintenance task



523
524
525
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 523

def fix_byhost
  @fix_byhost
end

#flush_system_cache ⇒ Boolean

Should this policy flush the system cache?

Returns:

  • (Boolean) —

    client maintenance task



531
532
533
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 531

def flush_system_cache
  @flush_system_cache
end

#flush_user_cache ⇒ Boolean

Should this policy flush the user cache?

Returns:

  • (Boolean) —

    client maintenance task



539
540
541
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 539

def flush_user_cache
  @flush_user_cache
end

#frequency ⇒ String

Returns how often to run the policy on each computer.

Returns:

  • (String) —

    how often to run the policy on each computer



382
383
384
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 382

def frequency
  @frequency
end

#icon ⇒ Jamf::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_service ⇒ Boolean (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?

#install_cached_pkgs ⇒ Boolean

Should this policy install any cached JSS packages?

Returns:

  • (Boolean) —

    client maintenance task



535
536
537
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 535

def install_cached_pkgs
  @install_cached_pkgs
end

#management_account ⇒ Hash (readonly)

The management accout changes applied by the policy

The keys are:

  • :action see MGMT_ACCOUNT_ACTIONS

  • :managed_password

  • :managed_password_md5

  • :managed_password_sha256

  • :managed_password_length # for random generating pws

TODO: make individial getters/setters as for @files_processes

Returns:



564
565
566
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 564

def 
  @management_account
end

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

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    do we have unsaved changes?

#offline ⇒ Boolean

Returns should be policy be available offline.

Returns:

  • (Boolean) —

    should be policy be available offline



388
389
390
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 388

def offline
  @offline
end

#open_firmware_efi_password ⇒ Hash (readonly)

Returns the open firmware mode and password.

Returns:

  • (Hash) —

    the open firmware mode and password



550
551
552
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 550

def open_firmware_efi_password
  @open_firmware_efi_password
end

#override_default_settings ⇒ Hash (readonly)

Overrides for various defaults

NOTE: There's an API bug in both XML and JSON with the

:distribution_point and :target_drive values.
First off, it's not clear what the :target_drive value here
is overriding, since there's a :target_drive value in the
main General hash.
Second off - when you set a non-default dist.point in the
packages section of the UI, that value shows up in both
this :target_drive and the general one, but the :distribution_point
value here stays empty.

The hash looks like: :distribution_point => “”, :force_afp_smb => false, :netboot_server => “current”, :target_drive => “default”, :sus => “default”

Returns:



418
419
420
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 418

def override_default_settings
  @override_default_settings
end

#packages ⇒ Array<Hash> (readonly) Also known as: pkgs

The pkgs handled by this policy

Hash keys are:

  • :action => “Install”

  • :update_autorun => false,

  • :feu => false,

  • :name => “rbgem-json-1.6.5-4.pkg”,

  • :id => 1073

Returns:



597
598
599
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 597

def packages
  @packages
end

#permissions_repair ⇒ Boolean

Should this policy run a permission repair?

Returns:

  • (Boolean) —

    client maintenance task



514
515
516
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 514

def permissions_repair
  @permissions_repair
end

#printers ⇒ Array<Hash> (readonly)

The printers handled by this policy

Each Hash looks like: {:make_default => false, :name => “torlan”, :id => 3, :action => “install”}

Returns:



691
692
693
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 691

def printers
  @printers
end

#reboot_options ⇒ Hash (readonly)

Reboot options for the policy

The hash keys are:

  • :user_logged_in => “Do not restart”,

  • :minutes_until_reboot => 5,

  • :message=> “This computer will restart in 5 minutes. yaddayadda.”,

  • :startup_disk => “Current Startup Disk”,

  • :specify_startup => “”,

  • :no_user_logged_in => “Do not restart”

  • :file_vault_2_reboot => false

Returns:



655
656
657
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 655

def reboot_options
  @reboot_options
end

#recon ⇒ Boolean Also known as: update_inventory

Should this policy run a recon?

Returns:

  • (Boolean) —

    client maintenance task



518
519
520
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 518

def recon
  @recon
end

#reset_name ⇒ Boolean

Should this policy reset the local hostname?

Returns:

  • (Boolean) —

    client maintenance task



527
528
529
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 527

def reset_name
  @reset_name
end

#scope ⇒ Object Originally defined in module Scopable

Attribtues

#scripts ⇒ Array<Hash> (readonly)

The scripts run by this policy

Hash keys are:

  • :name => “chromegetter.sh”,

  • :parameter4 => “”,

  • :parameter5 => “”,

  • :parameter6 => “”,

  • :parameter7 => “”,

  • :parameter8 => “”,

  • :parameter9 => “”,

  • :parameter10 => “”,

  • :parameter11 => “”,

  • :id => 1428,

  • :priority => “After”

Returns:



617
618
619
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 617

def scripts
  @scripts
end

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

Returns:

  • (Array<Hash>) —

    The categories in which this item should appear in SSvc

#self_service_description ⇒ String 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_name ⇒ String 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_page ⇒ Boolean 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_description ⇒ Boolean 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_text ⇒ String 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_message ⇒ String Originally defined in module SelfServable

Returns The message text of the notification.

Returns:

  • (String) —

    The message text of the notification

#self_service_notification_subject ⇒ String Originally defined in module SelfServable

object name.

Returns:

  • (String) —

    The subject text of the notification. Defaults to the

#self_service_notification_type ⇒ Symbol 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_enabled ⇒ Boolean 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_text ⇒ String 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_frequency ⇒ Integer 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_enabled ⇒ Boolean 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_password ⇒ String (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_removable ⇒ Symbol 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

#server_side_limitations ⇒ Hash (readonly)

The server-side limitations of this policy.

The keys are :activation and :expiration, both are Times.

the data comes from the API in the date_time_limitations hash of the general section, but the UI shows them in the Server Side Limitations area. This attribute is just for convience and consistency, and just refers to the data in their API locations

Returns:



455
456
457
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 455

def server_side_limitations
  @server_side_limitations
end

#site ⇒ String (readonly)

Returns a string with the site name.

Returns:

  • (String) —

    a string with the site name



395
396
397
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 395

def site
  @site
end

#target_drive ⇒ String

Returns which drive should the policy target.

Returns:

  • (String) —

    which drive should the policy target



385
386
387
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 385

def target_drive
  @target_drive
end

#trigger ⇒ String (readonly)

Either EVENT or USER_INITIATED

If it's EVENT, then one or more of the members @trigger_events must true.

Returns:



480
481
482
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 480

def trigger
  @trigger
end

#trigger_events ⇒ Hash (readonly)

The triggers that cause this policy to execute on a client when the @trigger is “EVENT”

This is a hash with the following keys. Each comes from the API as a key in the :general hash, but they make more sense separated out like this.

  • :trigger_startup => Bool

  • :trigger_login => Bool

  • :trigger_logout => Bool

  • :trigger_checkin => Bool

  • :trigger_network_state_changed => Bool

  • :trigger_enrollment_complete => Bool

  • :trigger_other => the String that causes a custom trigger

To edit a value, call

set_trigger_event(type, new_val)

where type is one of the keys in TRIGGER_EVENTS and new val is the new value (usually boolean)

Returns:



501
502
503
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 501

def trigger_events
  @trigger_events
end

#user_may_defer ⇒ Boolean (readonly)

Returns can the user defer the policy?.

Returns:

  • (Boolean) —

    can the user defer the policy?



630
631
632
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 630

def user_may_defer
  @user_may_defer
end

#user_may_defer_until ⇒ Time (readonly)

Returns when is the user no longer allowed to defer?.

Returns:

  • (Time) —

    when is the user no longer allowed to defer?



633
634
635
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 633

def user_may_defer_until
  @user_may_defer_until
end

#user_message_finish ⇒ String (readonly) Also known as: user_message_end

Returns the message shown the user at policy end.

Returns:

  • (String) —

    the message shown the user at policy end



639
640
641
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 639

def user_message_finish
  @user_message_finish
end

#user_message_start ⇒ String

Returns the message shown the user at policy start.

Returns:

  • (String) —

    the message shown the user at policy start



636
637
638
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 636

def user_message_start
  @user_message_start
end

#verify_startup_disk ⇒ Boolean

Should this policy verify the startup disk?

Returns:

  • (Boolean) —

    client maintenance task



510
511
512
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 510

def verify_startup_disk
  @verify_startup_disk
end

Class Method Details

.flush_logs(policy, older_than: 0, period: :days, computers: [], api: nil, cnx: Jamf.cnx) ⇒ void

This method returns an undefined value.

Flush logs for a given policy older than some number of days, weeks, months or years, possibly limited to one or more computers.

With no parameters, flushes all logs for the policy for all computers.

NOTE: Currently the API doesn't have a way to flush only failed policies.

WARNING: Log flushing can take a long time, and the API call doesnt return until its finished. The connection timeout will be temporarily raised to 30 minutes, unless it's already higher.

Parameters:

  • policy (Integer, String) —

    The id or name of the policy to flush

  • older_than (Integer) (defaults to: 0) —

    0, 1, 2, 3, or 6

  • period (Symbol) (defaults to: :days) —

    :days, :weeks, :months, or :years

  • computers (Array<Integer,String>) (defaults to: []) —

    Identifiers of the target computers either ids, names, SNs, macaddrs, or UDIDs. If omitted, flushes logs for all computers

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    the API connection to use.



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 321

def self.flush_logs(policy, older_than: 0, period: :days, computers: [], api: nil, cnx: Jamf.cnx)
  cnx = api if api

  orig_timeout = cnx.timeout
  pol_id = valid_id policy, cnx: cnx
  raise Jamf::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id

  older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
  raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than

  period = LOG_FLUSH_INTERVAL_PERIODS[period]
  raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period

  computers = [computers] unless computers.is_a? Array

  # log flushes can be really slow
  cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800

  return cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}" if computers.empty?

  flush_logs_for_specific_computers pol_id, older_than, period, computers, cnx
ensure
  cnx.timeout = orig_timeout
end

Instance Method Details

#add_directory_binding(identifier, **opts) ⇒ Array?

Add a Directory Bidning to the list of directory_bindings handled by this policy. If the directory binding already exists in the policy, nil is returned and no changes are made.

Parameters:

  • identifier (String, Integer) —

    the name or id of the directory binding to add to this policy

  • position (Symbol, Integer) —

    where to add this directory binding among the list of directory_bindings. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end

Returns:

  • (Array, nil) —

    the new @directory_bindings array, nil if directory_binding was already in the policy



1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1564

def add_directory_binding(identifier, **opts)
  id = validate_directory_binding_opts identifier, opts

  return nil if @directory_bindings.map { |s| s[:id] }.include? id

  name = Jamf::DirectoryBinding.map_all_ids_to(:name, cnx: @cnx)[id]

  directory_binding_data = {
    id: id,
    name: name
  }

  @directory_bindings.insert opts[:position], directory_binding_data

  @need_to_update = true
  @directory_bindings
end

#add_dock_item(identifier, action) ⇒ Object

Add a dock item to the policy

Raises:



1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1662

def add_dock_item(identifier, action)
  id = Jamf::DockItem.valid_id identifier, cnx: @cnx

  raise Jamf::NoSuchItemError, "No Dock Item matches '#{identifier}'" unless id

  raise Jamf::InvalidDataError, "Action must be one of: :#{DOCK_ITEM_ACTIONS.keys.join ', :'}" unless DOCK_ITEM_ACTIONS.include? action

  return nil if @dock_items.map { |d| d[:id] }.include? id

  name = Jamf::DockItem.map_all_ids_to(:name, cnx: @cnx)[id]

  @dock_items << {id: id, name: name, action: DOCK_ITEM_ACTIONS[action]}

  @need_to_update = true
  @dock_items
end

#add_package(identifier, **opts) ⇒ Array?

Add a package to the list of pkgs handled by this policy. If the pkg already exists in the policy, nil is returned and no changes are made.

Parameters:

  • identifier (String, Integer) —

    the name or id of the package to add to this policy

  • position (Symbol, Integer) —

    where to add this pkg among the list of pkgs. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end

  • action (String) —

    One of the values of PACKAGE_ACTIONS

  • feu (Boolean) —

    Overrides the setting for the pkg itself Defaults to false

  • fut (Boolean) —

    Overrides the setting for the pkg itself Defaults to false

  • update_autorun (Boolean) —

    Defaults to false

Returns:

  • (Array, nil) —

    the new @packages array, nil if pkg was already in the policy



1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1369

def add_package(identifier, **opts)
  id = validate_package_opts(identifier, opts)

  return nil if @packages.map { |p| p[:id] }.include? id

  name = Jamf::Package.map_all_ids_to(:name, cnx: @cnx)[id]

  pkg_data = {
    id: id,
    name: name,
    action: PACKAGE_ACTIONS[opts[:action]],
    feu: opts[:feu],
    fut: opts[:feu],
    update_autorun: opts[:update_autorun]
  }

  @packages.insert opts[:position], pkg_data

  @need_to_update = true
  @packages
end

#add_printer(identifier, **opts) ⇒ String

Add a specific printer object to the policy.

Parameters:

  • newvalue (String, Integer) —

    The name or the id of the printer to be added to this policy.

  • position (Symbol, Integer) —

    where to add this printer object among the list of printer objects. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end

  • action (Symbol) —

    One of the PRINTER_ACTIONS symbols. What you want done with the printer object upon policy execution.

  • make_default (TrueClass, FalseClass) —

    Should this printer object be set to default. Defaults to false

Returns:

  • (String) —

    The new printers array or nil if the printer was already in the policy

Author:

  • Tyler Morgan



1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1626

def add_printer(identifier, **opts)
  id = validate_printer_opts identifier, opts

  return nil if @printers.map { |p| p[:id] }.include? id

  name = Jamf::Printer.map_all_ids_to(:name, cnx: @cnx)[id]

  printer_data = {
    id: id,
    name: name,
    action: PRINTER_ACTIONS[opts[:action]],
    make_default: opts[:make_default]
  }

  @printers.insert opts[:position], printer_data

  @need_to_update = true
  @printers
end

#add_script(identifier, **opts) ⇒ Array?

Add a script to the list of SCRIPT_PRIORITIESipts run by this policy. If the script already exists in the policy, nil is returned and no changes are made.

Parameters:

  • identifier (String, Integer) —

    the name or id of the script to add to this policy

  • opts (Hash) —

    the options for this script

  • [Symbol, (Hash) —

    a customizable set of options

  • [Symbol] (Hash) —

    a customizable set of options

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Array, nil) —

    the new @scripts array, nil if script was already in the policy



1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1454

def add_script(identifier, **opts)
  id = validate_script_opts(identifier, opts)

  return nil if @scripts.map { |s| s[:id] }.include? id

  name = Jamf::Script.map_all_ids_to(:name, cnx: @cnx)[id]

  script_data = {
    id: id,
    name: name,
    priority: SCRIPT_PRIORITIES[opts[:priority]],
    parameter4: opts[:parameter4],
    parameter5: opts[:parameter5],
    parameter6: opts[:parameter6],
    parameter7: opts[:parameter7],
    parameter8: opts[:parameter8],
    parameter9: opts[:parameter9],
    parameter10: opts[:parameter10],
    parameter11: opts[:parameter11]
  }

  @scripts.insert opts[:position], script_data

  @need_to_update = true
  @scripts
end

#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_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Add this object to self service if not already there.

#apply_encryption_configuration(identifier) ⇒ Void

Sets the Disk Encryption application to “Apply” and sets the correct disk encryption configuration ID using either the name or id.

Returns:

  • (Void)

Author:

  • Tyler Morgan



1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1740

def apply_encryption_configuration(identifier)

  id = Jamf::DiskEncryptionConfiguration.valid_id identifier

  return if id.nil?

  hash = {
    action: DISK_ENCRYPTION_ACTIONS[:apply],
    disk_encryption_configuration_id: id,
    auth_restart: false
  }

  @disk_encryption = hash
  @need_to_update = true
end

#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

Parameters:

  • new_cat (Integer, String) —

    The new category

Raises:

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

Does this object have a category assigned?

Returns:

  • (Boolean) —

    Does this object have a category assigned?

#category_id ⇒ Integer Originally defined in module Categorizable

The id of the category for this object.

Returns:

  • (Integer) —

    The id of the category for this object.

#category_name ⇒ String 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'

Returns:

  • (String) —

    The name of the category for this object.

#category_object ⇒ Jamf::Category Originally defined in module Categorizable

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

Returns:

  • (Jamf::Category) —

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

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

#create ⇒ Object Originally defined in module SelfServable

HACK: ity hack hack… remove when jamf fixes these bugs

#delete_file? ⇒ Boolean Also known as: delete_path?

Returns Should the searched-for path be deleted if found?.

Returns:

  • (Boolean) —

    Should the searched-for path be deleted if found?



1273
1274
1275
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1273

def delete_file?
  @files_processes[:delete_file]
end

#directory_binding_ids ⇒ Array

Returns the id's of the directory_bindings handled by the policy.

Returns:

  • (Array) —

    the id's of the directory_bindings handled by the policy



1543
1544
1545
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1543

def directory_binding_ids
  @directory_bindings.map { |p| p[:id] }
end

#directory_binding_names ⇒ Array

Returns the names of the directory_bindings handled by the policy.

Returns:

  • (Array) —

    the names of the directory_bindings handled by the policy



1548
1549
1550
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1548

def directory_binding_names
  @directory_bindings.map { |p| p[:name] }
end

#disable ⇒ Object

Shortcut for endabled = false



828
829
830
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 828

def disable
  self.enabled = false
end

#do_not_reboot ⇒ void

This method returns an undefined value.

Reboot Options Do Not Reboot Shortcut method to suppress Reboot Options



1160
1161
1162
1163
1164
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1160

def do_not_reboot
  @reboot_options[:user_logged_in] = 'Do not restart'
  @reboot_options[:no_user_logged_in] = 'Do not restart'
  @need_to_update = true
end

#dock_item_ids ⇒ Array

Returns the id's of the dock_items handled by the policy.

Returns:

  • (Array) —

    the id's of the dock_items handled by the policy



1598
1599
1600
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1598

def dock_item_ids
  @dock_items.map { |p| p[:id] }
end

#dock_item_names ⇒ Array

Returns the names of the dock_items handled by the policy.

Returns:

  • (Array) —

    the names of the dock_items handled by the policy



1603
1604
1605
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1603

def dock_item_names
  @dock_items.map { |p| p[:name] }
end

#enable ⇒ Object

Shortcut for enabled = true



823
824
825
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 823

def enable
  self.enabled = true
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

Parameters:

  • new_cat (String, Integer) —

    The name or id of a possible category

Returns:

  • (Array<String, Integer>) —

    The matching name and id, which may be nil.

#file_vault_2_reboot=(fv_bool) ⇒ void

This method returns an undefined value.

Reboot Options FileVault Authenticated Reboot

Parameters:

  • fv_bool (Boolean) —

    true or false

Raises:



1186
1187
1188
1189
1190
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1186

def file_vault_2_reboot=(fv_bool)
  raise Jamf::InvalidDataError, 'FileVault 2 Reboot must be a Boolean' unless fv_bool.jss_boolean?
  @reboot_options[:file_vault_2_reboot] = fv_bool
  @need_to_update = true
end

#flush_logs(older_than: 0, period: :days, computers: []) ⇒ void

This method returns an undefined value.

Flush logs for this policy older than some number of days, weeks, months or years, possibly limited to one or more computers

With no parameters, flushes all logs for all computers

NOTE: Currently the API doesn't have a way to flush only failed policies.

WARNING: Log flushing can take a long time, and the API call doesnt return until its finished. The connection timeout will be temporarily raised to 30 minutes, unless it's already higher.

Parameters:

  • older_than (Integer) (defaults to: 0) —

    0, 1, 2, 3, or 6

  • period (Symbol) (defaults to: :days) —

    :days, :weeks, :months, or :years

  • computers (Array<Integer,String>) (defaults to: []) —

    Identifiers of the target computers either ids, names, SNs, macaddrs, or UDIDs

Raises:



1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1868

def flush_logs(older_than: 0, period: :days, computers: [])
  raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #create first." unless @in_jss

  Jamf::Policy.flush_logs(
    @id,
    older_than: older_than,
    period: period,
    computers: computers, cnx: @cnx
  )
end

#kill_process? ⇒ Boolean

Returns Should the searched-for process be killed if found.

Returns:

  • (Boolean) —

    Should the searched-for process be killed if found.



1239
1240
1241
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1239

def kill_process?
  @files_processes[:kill_process]
end

#locate_file ⇒ String

Returns The term to seach for using the locate command.

Returns:

  • (String) —

    The term to seach for using the locate command



1317
1318
1319
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1317

def locate_file
  @files_processes[:locate_file]
end

#locate_file=(term) ⇒ void

This method returns an undefined value.

Set the term to seach for using the locate command

Parameters:

  • term (String) —

    the term to seach for using the locate command

Raises:



1327
1328
1329
1330
1331
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1327

def locate_file=(term)
  raise Jamf::InvalidDataError, 'Term to locate must be a String' unless term.is_a? String
  @files_processes[:locate_file] = term
  @need_to_update = true
end

#minutes_until_reboot=(minutes) ⇒ void

This method returns an undefined value.

Reboot Options Minutes Until Reboot

Parameters:

  • minutes (String) —

    The number of minutes to delay prior to reboot

Raises:



1173
1174
1175
1176
1177
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1173

def minutes_until_reboot=(minutes)
  raise Jamf::InvalidDataError, 'Minutes until reboot must be an Integer' unless minutes.is_a? Integer
  @reboot_options[:minutes_until_reboot] = minutes
  @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:

#no_user_logged_in=(no_user_option) ⇒ void

This method returns an undefined value.

What to do at reboot when No User Logged In

Parameters:

  • no_user_option (String) —

    Any one of the Strings from NO_USER_LOGGED_IN

Raises:



1072
1073
1074
1075
1076
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1072

def no_user_logged_in=(no_user_option)
  raise Jamf::InvalidDataError, "no_user_logged_in options: #{NO_USER_LOGGED_IN.join(', ')}" unless NO_USER_LOGGED_IN.include? no_user_option
  @reboot_options[:no_user_logged_in] = no_user_option
  @need_to_update = true
end

#notify_failed_retries=(bool) ⇒ void

This method returns an undefined value.

Parameters:

  • bool (Boolean) —

    Should admins be notified of failed retry attempts



920
921
922
923
924
925
926
927
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 920

def notify_failed_retries=(bool)
  validate_retry_opt
  bool = Jamf::Validate.boolean bool
  return if @notify_failed_retries == bool

  @notify_failed_retries = bool
  @need_to_update = true
end

#notify_failed_retries? ⇒ Boolean Also known as: notify_failed_retries, notify_on_each_failed_retry

Returns Should admins be notified of failed retry attempts.

Returns:

  • (Boolean) —

    Should admins be notified of failed retry attempts



910
911
912
913
914
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 910

def notify_failed_retries?
  return false unless FREQUENCIES[:once_per_computer] == @frequency

  @notify_failed_retries
end

#package_ids ⇒ Array

Returns the id's of the packages handled by the policy.

Returns:

  • (Array) —

    the id's of the packages handled by the policy



1340
1341
1342
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1340

def package_ids
  @packages.map { |p| p[:id] }
end

#package_names ⇒ Array

Returns the names of the packages handled by the policy.

Returns:

  • (Array) —

    the names of the packages handled by the policy



1345
1346
1347
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1345

def package_names
  @packages.map { |p| p[:name] }
end

#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

#printer_ids ⇒ Array

Returns the id's of the printers handled by the policy.

Returns:

  • (Array) —

    the id's of the printers handled by the policy



1688
1689
1690
1691
1692
1693
1694
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1688

def printer_ids
    begin
        @printers.map { |p| p[:id] }
        rescue TypeError
        return []
    end
end

#printer_names ⇒ Array

Returns the names of the printers handled by the policy.

Returns:

  • (Array) —

    the names of the printers handled by the policy



1697
1698
1699
1700
1701
1702
1703
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1697

def printer_names
    begin
        @printers.map { |p| p[:name] }
        rescue TypeError
        return []
    end
end

#reboot_message=(message) ⇒ void Also known as: message=

This method returns an undefined value.

Set Reboot Message

Parameters:

  • reboot_message (String) —

    Text of Reboot Message

Raises:



1096
1097
1098
1099
1100
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1096

def reboot_message=(message)
  raise Jamf::InvalidDataError, 'Reboot message must be a String' unless message.is_a? String
  @reboot_options[:message] = message
  @need_to_update = true
end

#reissue_key ⇒ Void

Sets the Disk Encryption application to “Remediate” and sets the remediation key type to individual.

Returns:

  • (Void)

Author:

  • Tyler Morgan



1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1715

def reissue_key()
  if @disk_encryption[:action] != DISK_ENCRYPTION_ACTIONS[:remediate]
    # Setting New Action
    hash = {
      action: DISK_ENCRYPTION_ACTIONS[:remediate],
      remediate_key_type: "Individual"
    }

    @disk_encryption = hash
    @need_to_update = true

  else
    # Update
    return
  end

end

#remove_directory_binding(identifier) ⇒ Array?

Remove a directory binding from this policy by name or id

Parameters:

  • identifier (String, Integer) —

    the name or id of the directory binding to remove

Returns:

  • (Array, nil) —

    the new directory bindings array or nil if no change



1589
1590
1591
1592
1593
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1589

def remove_directory_binding(identifier)
  removed = @directory_bindings.delete_if { |s| s[:id] == identifier || s[:name] == identifier }
  @need_to_update = true if removed
  removed
end

#remove_dock_item(identifier) ⇒ Object

Remove a dock item from the policy



1680
1681
1682
1683
1684
1685
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1680

def remove_dock_item(identifier)
  # TODO: Add validation against Jamf::DockItem
  removed = @dock_items.delete_if { |d| d[:id] == identifier || d[:name] == identifier }
  @need_to_update = true if removed
  removed
end

#remove_encryption_configuration ⇒ Void

Removes the Disk Encryption settings associated with this specific policy.

Returns:

  • (Void)

Author:

  • Tyler Morgan



1763
1764
1765
1766
1767
1768
1769
1770
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1763

def remove_encryption_configuration()
  hash = {
    action: DISK_ENCRYPTION_ACTIONS[:none]
  }

  @disk_encryption = hash
  @need_to_update = true
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_package(identifier) ⇒ Array?

Remove a package from this policy by name or id

Parameters:

  • identifier (String, Integer) —

    the name or id of the package to remove

Returns:

  • (Array, nil) —

    the new packages array or nil if no change



1397
1398
1399
1400
1401
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1397

def remove_package(identifier)
  removed = @packages.delete_if { |p| p[:id] == identifier || p[:name] == identifier }
  @need_to_update = true if removed
  removed
end

#remove_printer(identifier) ⇒ Array?

Remove a specific printer object from the policy.

Parameters:

  • identifier (String, Integer) —

    The name or id of the printer to be removed.

Returns:

  • (Array, nil) —

    The new printers array or nil if no change.

Author:

  • Tyler Morgan



1654
1655
1656
1657
1658
1659
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1654

def remove_printer(identifier)
  removed = @printers.delete_if { |p| p[:id] == identifier || p[:name] == identifier }

  @need_to_update = true
  removed
end

#remove_script(identifier) ⇒ Array?

Remove a script from this policy by name or id

Parameters:

  • identifier (String, Integer) —

    the name or id of the script to remove

Returns:

  • (Array, nil) —

    the new scripts array or nil if no change



1487
1488
1489
1490
1491
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1487

def remove_script(identifier)
  removed = @scripts.delete_if { |s| s[:id] == identifier || s[:name] == identifier }
  @need_to_update = true if removed
  removed
end

#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

#retry_attempts ⇒ Integer

Returns How many times wil the policy be retried if it fails. -1 means no retries, otherwise, an integer from 1 to 10.

Returns:

  • (Integer) —

    How many times wil the policy be retried if it fails. -1 means no retries, otherwise, an integer from 1 to 10



881
882
883
884
885
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 881

def retry_attempts
  return 0 unless FREQUENCIES[:once_per_computer] == @frequency

  @retry_attempts
end

#retry_attempts=(int) ⇒ void

This method returns an undefined value.

Set the number of times to retry if the policy fails. One of the ways to turn off policy retry is to set this to 0 or -1 The other is to set retry_event to :none

Parameters:

  • From (Integer) —

    -1 to 10

Raises:



894
895
896
897
898
899
900
901
902
903
904
905
906
907
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 894

def retry_attempts=(int)
  validate_retry_opt
  raise Jamf::InvalidDataError, 'Retry attempts must be an integer from 0-10' unless int.is_a?(Integer) && (-1..10).include?(int)

  # if zero or -1, turn off retries
  if int <= 0
    @retry_event = RETRY_EVENTS[:none]
    int = -1
  end
  return if @retry_attempts == int

  @retry_attempts = int
  @need_to_update = true
end

#retry_event ⇒ String

Returns The event that causes a policy retry.

Returns:

  • (String) —

    The event that causes a policy retry



849
850
851
852
853
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 849

def retry_event
  return RETRY_EVENTS[:none] unless FREQUENCIES[:once_per_computer] == @frequency

  @retry_event
end

#retry_event=(evt) ⇒ void

This method returns an undefined value.

Set the event that causes a retry if the policy fails. One of the ways to turn off policy retry is to set this to :none The other is to set the retry_attempts to 0

Parameters:

  • A (Symbol, String) —

    key or value from RETRY_EVENTS

Raises:



862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 862

def retry_event=(evt)
  validate_retry_opt
  raise Jamf::InvalidDataError, "Retry event must be one of :#{RETRY_EVENTS.keys.join ', :'}" unless RETRY_EVENTS.key?(evt) || RETRY_EVENTS.value?(evt)

  evt = evt.is_a?(Symbol) ? RETRY_EVENTS[evt] : evt
  return if evt == @retry_event

  # if the event is not 'none' and attempts is <= 0,
  # set events to 1, or the API won't accept it
  unless evt == RETRY_EVENTS[:none]
    @retry_attempts = 1 unless @retry_attempts.positive?
  end

  @retry_event = evt
  @need_to_update = true
end

#run(show_output = false) ⇒ Boolean? Also known as: execute

Try to execute this policy on this machine.

Parameters:

  • show_output (Boolean) (defaults to: false) —

    should the stdout and stderr of the 'jamf policy' command be sent to stdout in realtime?

Returns:

  • (Boolean, nil) —

    The success of the 'jamf policy' command, or nil if the policy couldn't be executed (out of scope, policy disabled, etc)



1839
1840
1841
1842
1843
1844
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1839

def run(show_output = false)
  return nil unless enabled?
  output = Jamf::Client.run_jamf('policy', "-id #{id}", show_output)
  return nil if output.include? 'No policies were found for the ID'
  $CHILD_STATUS.exitstatus.zero? ? true : false
end

#run_command ⇒ String Also known as: command_to_run

Returns The unix shell command to run on ths client.

Returns:

  • (String) —

    The unix shell command to run on ths client.



1196
1197
1198
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1196

def run_command
  @files_processes[:run_command]
end

#run_command=(command) ⇒ void Also known as: command_to_run=

This method returns an undefined value.

Set the unix shell command to be run on the client

Parameters:

  • command (String) —

    the unix shell command to be run on the client

Raises:



1207
1208
1209
1210
1211
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1207

def run_command=(command)
  raise Jamf::InvalidDataError, 'Command to run must be a String' unless command.is_a? String
  @files_processes[:run_command] = command
  @need_to_update = true
end

#script_ids ⇒ Array

Returns the id's of the scripts handled by the policy.

Returns:

  • (Array) —

    the id's of the scripts handled by the policy



1406
1407
1408
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1406

def script_ids
  @scripts.map { |p| p[:id] }
end

#script_names ⇒ Array

Returns the names of the scripts handled by the policy.

Returns:

  • (Array) —

    the names of the scripts handled by the policy



1411
1412
1413
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1411

def script_names
  @scripts.map { |p| p[:name] }
end

#search_by_path ⇒ Pathname

Returns The path to search for.

Returns:



1263
1264
1265
1266
1267
1268
1269
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1263

def search_by_path
  if @files_processes[:search_by_path].nil?
    return nil
  else
    Pathname.new @files_processes[:search_by_path]
  end
end

#search_for_process ⇒ String

Returns The process name to search for on the client.

Returns:

  • (String) —

    The process name to search for on the client



1233
1234
1235
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1233

def search_for_process
  @files_processes[:search_for_process]
end

#self_service_execute_url ⇒ String 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_payload ⇒ Symbol Originally defined in module SelfServable

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

Returns:

  • (Symbol) —

    :profile, :app, or :policy

#self_service_targets ⇒ Array<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_url ⇒ String 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

#server_side_activation=(activation) ⇒ void

This method returns an undefined value.

Set Server Side Activation

Parameters:

  • activation (Time) —

    Activation date and time

Raises:



978
979
980
981
982
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 978

def server_side_activation=(activation)
  raise Jamf::InvalidDataError, 'Activation must be a Time' unless activation.is_a? Time
  @server_side_limitations[:activation] = activation
  @need_to_update = true
end

#server_side_expiration=(expiration) ⇒ void

This method returns an undefined value.

Set Server Side Expiration

Parameters:

  • expiration (Time) —

    Expiration date and time

Raises:



990
991
992
993
994
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 990

def server_side_expiration=(expiration)
  raise Jamf::InvalidDataError, 'Expiration must be a Time' unless expiration.is_a? Time
  @server_side_limitations[:expiration] = expiration
  @need_to_update = true
end

#set_management_account(action, **opts) ⇒ Object

Interact with management account settings

Reference: developer.jamf.com/documentation#resources-with-passwords

Parameters:

  • action (Key) —

    one of the MGMT_ACCOUNT_ACTIONS keys

Returns:

  • The current specified management settings.

Raises:



1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1780

def (action, **opts)
  # TODO: Add proper error handling
  raise Jamf::InvalidDataError, "Action must be one of: :#{MGMT_ACCOUNT_ACTIONS.keys.join ', :'}" unless MGMT_ACCOUNT_ACTIONS.include? action

  management_data = {}

  if action == :change_pw || action == :reset_pw
    raise Jamf::MissingDataError, ":password must be provided when changing management account password" if opts[:password].nil?

    management_data = {
      action: MGMT_ACCOUNT_ACTIONS[action],
      managed_password: opts[:password]
    }
  elsif action == :reset_random || action == :generate_pw
    raise Jamf::MissingDataError, ":password_length must be provided when setting a random password" if opts[:password_length].nil?
    raise Jamf::InvalidDataError, ":password_length must be an Integer" unless opts[:password_length].is_a? Integer

    management_data = {
      action: MGMT_ACCOUNT_ACTIONS[action],
      managed_password_length: opts[:password_length]
    }
  else
    management_data = {
      action: MGMT_ACCOUNT_ACTIONS[action]
    }
  end

  @management_account = management_data

  @need_to_update = true

  @management_account

end

#set_script_parameters(identifier, **opts) ⇒ Array

Set a script parameter

Parameters:

  • identifier (Integer, String) —

    identifier the id or name of a script in this policy

  • opts (Hash) —

    opts the options to alter for this script

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Array) —

    the scripts array

Raises:



1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1525

def set_script_parameters(identifier, **opts)
  id = Jamf::Script.valid_id identifier, cnx: @cnx
  raise Jamf::NoSuchItemError, "No script matches '#{identifier}'" unless id

  script_data = @scripts.select { |s| s[:id] == id }[0]
  raise Jamf::InvalidDataError, "Script #{id} is not configured. Use add_script method." unless script_data

  opts.each do |parameter, value|
    script_data[parameter] = value if SCRIPT_PARAMETERS_AVAILABLE.include? parameter
  end

  @need_to_update = true
  @scripts
end

#set_search_by_path(path, delete = false) ⇒ void

This method returns an undefined value.

Set the path to search for, a String or Pathname, and whether or not to delete it if found.

Setter methods (which end with =) can't easily take multiple arguments, so we instead name them “set_blah_blah” rather than “blah_blah=”

Parameters:

  • path (String, Pathname) —

    the path to search for

  • delete (Boolean) (defaults to: false) —

    should the path be deleted if found

Raises:



1290
1291
1292
1293
1294
1295
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1290

def set_search_by_path(path, delete = false)
  raise Jamf::InvalidDataError, 'Path to search for must be a String or a Pathname' unless path.is_a?(String) || path.is_a?(Pathname)
  @files_processes[:search_by_path] = path.to_s
  @files_processes[:delete_file] = delete ? true : false
  @need_to_update = true
end

#set_search_for_process(process, kill = false) ⇒ void

This method returns an undefined value.

Set the process name to search for, and if it should be killed if found.

Setter methods (which end with =) can't easily take multiple arguments, so we instead name them “set_blah_blah” rather than “blah_blah=”

Parameters:

  • process (String) —

    the process name to search for

  • kill (Boolean) (defaults to: false) —

    should be process be killed if found



1255
1256
1257
1258
1259
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1255

def set_search_for_process(process, kill = false)
  @files_processes[:search_for_process] = process.to_s
  @files_processes[:kill_process] = kill ? true : false
  @need_to_update = true
end

#set_trigger_event(type, new_val) ⇒ void

This method returns an undefined value.

Change a trigger event

Parameters:

  • type (Symbol) —

    the type of trigger, one of the keys of TRIGGER_EVENTS

  • new_val (Boolean) —

    whether the type of trigger is active or not.

Raises:



961
962
963
964
965
966
967
968
969
970
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 961

def set_trigger_event(type, new_val)
  raise Jamf::InvalidDataError, "Trigger type must be one of #{TRIGGER_EVENTS.keys.join(', ')}" unless TRIGGER_EVENTS.key?(type)
  if type == :custom
    raise Jamf::InvalidDataError, 'Custom triggers must be Strings' unless new_val.is_a? String
  else
    raise Jamf::InvalidDataError, 'Non-custom triggers must be true or false' unless Jamf::TRUE_FALSE.include? new_val
  end
  @trigger_events[TRIGGER_EVENTS[type]] = new_val
  @need_to_update = true
end

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

#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

Parameters:

  • new_site (Integer, String) —

    The new site

Raises:

#site_assigned? ⇒ Boolean Originally defined in module Sitable

Does this object have a site assigned?

Returns:

  • (Boolean) —

    Does this object have a site assigned?

#site_id ⇒ Integer Originally defined in module Sitable

The id of the site for this object.

Returns:

  • (Integer) —

    The id of the site for this object.

#site_name ⇒ String 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'

Returns:

  • (String) —

    The name of the site for this object.

#site_object ⇒ Jamf::Site Originally defined in module Sitable

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

Returns:

  • (Jamf::Site) —

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

#specify_startup=(startup_volume) ⇒ void

This method returns an undefined value.

Specify Startup Volume Only Supports “Specify Local Startup Disk”

Parameters:

  • startup_volume (String) —

    a Volume to reboot to

Raises:



1148
1149
1150
1151
1152
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1148

def specify_startup=(startup_volume)
  raise Jamf::InvalidDataError, "#{startup_volume} is not a valid Startup Disk" unless startup_volume.is_a? String
  @reboot_options[:specify_startup] = startup_volume
  @need_to_update = true
end

#spotlight_search ⇒ String

Returns The term to search for using spotlight.

Returns:

  • (String) —

    The term to search for using spotlight



1299
1300
1301
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1299

def spotlight_search
  @files_processes[:spotlight_search]
end

#spotlight_search=(term) ⇒ void

This method returns an undefined value.

Set the term to seach for using spotlight

Parameters:

  • term (String) —

    the term to seach for using spotlight

Raises:



1309
1310
1311
1312
1313
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1309

def spotlight_search=(term)
  raise Jamf::InvalidDataError, 'Spotlight search term must be a String' unless term.is_a? String
  @files_processes[:spotlight_search] = term
  @need_to_update = true
end

#startup_disk=(startup_disk_option) ⇒ void

This method returns an undefined value.

Set Startup Disk Only Supports 'Specify Local Startup Disk' at the moment

Parameters:

  • startup_disk_option (String)

Raises:



1134
1135
1136
1137
1138
1139
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1134

def startup_disk=(startup_disk_option)
  raise Jamf::InvalidDataError, "#{startup_disk_option} is not a valid Startup Disk" unless startup_disk_option.is_a? String
  @reboot_options[:startup_disk] = 'Specify Local Startup Disk'
  self.specify_startup = startup_disk_option
  @need_to_update = true
end

#unset_category ⇒ void Originally defined in module Categorizable

This method returns an undefined value.

Set the category to nothing

#unset_site ⇒ void Originally defined in module Sitable

This method returns an undefined value.

Set the site to nothing

#update ⇒ Object Originally defined in module SelfServable

HACK: ity hack hack… remove when jamf fixes these bugs

#update_locate_database=(bool) ⇒ void

This method returns an undefined value.

Set whether or not to update the database used by the locate command.

Parameters:

  • bool (Boolean) —

    whether or not to update the database used by the locate command.



1226
1227
1228
1229
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1226

def update_locate_database=(bool)
  @files_processes[:update_locate_database] = Jamf::Validate.boolean bool
  @need_to_update = true
end

#update_locate_database? ⇒ Boolean

Returns Should we update the database used by the locate command?.

Returns:

  • (Boolean) —

    Should we update the database used by the locate command?



1216
1217
1218
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1216

def update_locate_database?
  @files_processes[:update_locate_database]
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_logged_in=(logged_in_option) ⇒ void

This method returns an undefined value.

What to do at reboot when there is a User Logged In

Parameters:

  • logged_in_option (String) —

    Any one of the Strings from USER_LOGGED_IN

Raises:



1084
1085
1086
1087
1088
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1084

def user_logged_in=(logged_in_option)
  raise Jamf::InvalidDataError, "user_logged_in options: #{USER_LOGGED_IN.join(', ')}" unless USER_LOGGED_IN.include? logged_in_option
  @reboot_options[:user_logged_in] = logged_in_option
  @need_to_update = true
end

#user_message_end=(message) ⇒ void Also known as: user_message_finish=

This method returns an undefined value.

Set User Finish Message

Parameters:

  • user_message (String) —

    Text of User Message

Raises:



1119
1120
1121
1122
1123
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1119

def user_message_end=(message)
  raise Jamf::InvalidDataError, 'User message must be a String' unless message.is_a? String
  @user_message_finish = message
  @need_to_update = true
end

#user_removable? ⇒ Boolean? Originally defined in module SelfServable

Can this thing be removed by the user?

Returns:

  • (Boolean, nil) —

    nil means 'not applicable'

#verify_management_password(password) ⇒ Boolean

Check if management password matches provided password

Parameters:

  • password (String) —

    the password that is SHA256'ed to compare to the one from the API.

Returns:

  • (Boolean) —

    The result of the comparison of the management password and provided text.

Raises:



1821
1822
1823
1824
1825
1826
1827
 
# File 'lib/jamf/api/classic/api_objects/policy.rb', line 1821

def verify_management_password(password)
  raise Jamf::InvalidDataError, "Management password must be a string." unless password.is_a? String

  raise Jamf::UnsupportedError, "'#{@management_account[:action].to_s}' does not support management passwords." unless @management_account[:action] == MGMT_ACCOUNT_ACTIONS[:change_pw] || @management_account[:action] == MGMT_ACCOUNT_ACTIONS[:reset_pw]

  return Digest::SHA256.hexdigest(password).to_s == @management_account[:managed_password_sha256].to_s
end