Class: JSS::Policy

Inherits:
APIObject show all
Includes:
Categorizable, Creatable, Scopable, SelfServable, Updatable, Uploadable
Defined in:
lib/jss/api_object/policy.rb,
lib/jss.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:

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
VALID_DATA_KEYS =

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

[:scope, :user_interaction, :files_processes].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 = 
[
  :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',
  daily: 'Once every day',
  weekly: 'Once every week',
  monthly: 'Once every month'
}.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'
}.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
PRINTER_ACTIIONS = 
{
  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: 'Day',
  days: 'Day',
  week: 'Week',
  weeks: 'Week',
  month: 'Month',
  months: 'Month',
  year: 'Year',
  years: 'Year'
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Policy

Returns a new instance of Policy.

See Also:



565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
 
# File 'lib/jss/api_object/policy.rb', line 565

def initialize(args = {})
  super

  if @in_jss
    gen = @init_data[:general]
    @frequency = gen[:frequency]
    @target_drive = gen[:target_drive]
    @offline = gen[:offline]
    @enabled = gen[:enabled]
    @site = JSS::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]
    }

    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]
     = 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 = JSS.parse_datetime 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]

    ### 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 ||= {}
   ||= {}
  @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 ||= JSS::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



451
452
453
 
# File 'lib/jss/api_object/policy.rb', line 451

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



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

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



414
415
416
 
# File 'lib/jss/api_object/policy.rb', line 414

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”}



550
551
552
 
# File 'lib/jss/api_object/policy.rb', line 550

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”}



543
544
545
 
# File 'lib/jss/api_object/policy.rb', line 543

def dock_items
  @dock_items
end

#enabled ⇒ Boolean Also known as: enabled? 



267
268
269
 
# File 'lib/jss/api_object/policy.rb', line 267

def enabled
  @enabled
end

#fix_byhost ⇒ Boolean (readonly) 



394
395
396
 
# File 'lib/jss/api_object/policy.rb', line 394

def fix_byhost
  @fix_byhost
end

#flush_system_cache ⇒ Boolean (readonly) 



400
401
402
 
# File 'lib/jss/api_object/policy.rb', line 400

def flush_system_cache
  @flush_system_cache
end

#flush_user_cache ⇒ Boolean (readonly) 



406
407
408
 
# File 'lib/jss/api_object/policy.rb', line 406

def flush_user_cache
  @flush_user_cache
end

#frequency ⇒ String 



258
259
260
 
# File 'lib/jss/api_object/policy.rb', line 258

def frequency
  @frequency
end

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

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

#install_cached_pkgs ⇒ Boolean (readonly) 



403
404
405
 
# File 'lib/jss/api_object/policy.rb', line 403

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



431
432
433
 
# File 'lib/jss/api_object/policy.rb', line 431

def 
  
end

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

#offline ⇒ Boolean 



264
265
266
 
# File 'lib/jss/api_object/policy.rb', line 264

def offline
  @offline
end

#open_firmware_efi_password ⇒ Hash (readonly) 



417
418
419
 
# File 'lib/jss/api_object/policy.rb', line 417

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”



293
294
295
 
# File 'lib/jss/api_object/policy.rb', line 293

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



464
465
466
 
# File 'lib/jss/api_object/policy.rb', line 464

def packages
  @packages
end

#permissions_repair ⇒ Boolean (readonly) 



388
389
390
 
# File 'lib/jss/api_object/policy.rb', line 388

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”}



557
558
559
 
# File 'lib/jss/api_object/policy.rb', line 557

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

TODO: make individial getters/setters as for @files_processes



521
522
523
 
# File 'lib/jss/api_object/policy.rb', line 521

def reboot_options
  @reboot_options
end

#recon ⇒ Boolean (readonly) 



391
392
393
 
# File 'lib/jss/api_object/policy.rb', line 391

def recon
  @recon
end

#reset_name ⇒ Boolean (readonly) 



397
398
399
 
# File 'lib/jss/api_object/policy.rb', line 397

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”



483
484
485
 
# File 'lib/jss/api_object/policy.rb', line 483

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)

#self_service_description ⇒ String Originally defined in module SelfServable

#self_service_feature_on_main_page ⇒ Boolean Originally defined in module SelfServable

Only applicable to macOS targets

#self_service_force_users_to_view_description ⇒ Boolean Originally defined in module SelfServable

#self_service_install_button_text ⇒ String Originally defined in module SelfServable

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

#self_service_user_removable ⇒ Symbol Originally defined in module SelfServable

#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



330
331
332
 
# File 'lib/jss/api_object/policy.rb', line 330

def server_side_limitations
  @server_side_limitations
end

#site ⇒ String (readonly) 



270
271
272
 
# File 'lib/jss/api_object/policy.rb', line 270

def site
  @site
end

#target_drive ⇒ String 



261
262
263
 
# File 'lib/jss/api_object/policy.rb', line 261

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.



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

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)



376
377
378
 
# File 'lib/jss/api_object/policy.rb', line 376

def trigger_events
  @trigger_events
end

#user_may_defer ⇒ Boolean (readonly) 



496
497
498
 
# File 'lib/jss/api_object/policy.rb', line 496

def user_may_defer
  @user_may_defer
end

#user_may_defer_until ⇒ Time (readonly) 



499
500
501
 
# File 'lib/jss/api_object/policy.rb', line 499

def user_may_defer_until
  @user_may_defer_until
end

#user_message_finish ⇒ String (readonly) 



505
506
507
 
# File 'lib/jss/api_object/policy.rb', line 505

def user_message_finish
  @user_message_finish
end

#user_message_start ⇒ String (readonly) 



502
503
504
 
# File 'lib/jss/api_object/policy.rb', line 502

def user_message_start
  @user_message_start
end

#verify_startup_disk ⇒ Boolean (readonly) 



385
386
387
 
# File 'lib/jss/api_object/policy.rb', line 385

def verify_startup_disk
  @verify_startup_disk
end

Instance Method Details

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

Raises:



1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
 
# File 'lib/jss/api_object/policy.rb', line 1051

def add_package(identifier, opts = {})
  opts[:position] ||= -1
  opts[:action] ||= :install
  opts[:feu] = false if opts[:feu].nil?
  opts[:fut] = false if opts[:fut].nil?
  opts[:update_autorun] = false if opts[:update_autorun].nil?

  id = JSS::Package.valid_id identifier
  raise JSS::NoSuchItemError, "No package matches '#{identifier}'" unless id

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

  name = JSS::Package.map_all_ids_to(:name)[id]

  position = case opts[:position]
             when :start then 0
             when :end then -1
             else opts[:position]
             end

  raise JSS::InvalidDataError, "action must be one of: :#{PACKAGE_ACTIONS.keys.join ', :'}" unless \
    PACKAGE_ACTIONS.include? opts[:action]
  raise JSS::InvalidDataError, 'feu must be true or false' unless \
    JSS::TRUE_FALSE.include? opts[:feu]
  raise JSS::InvalidDataError, 'fut must be true or false' unless \
    JSS::TRUE_FALSE.include? opts[:fut]
  raise JSS::InvalidDataError, 'update_autorun must be true or false' unless \
    JSS::TRUE_FALSE.include? opts[:update_autorun]

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

  @packages.insert position, pkg_data

  ### if the user gave a large number for position, it created nil entries in the array, they need
  ### to be removed.
  @packages.compact!

  @need_to_update = true
  @packages
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.

Raises:



1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
 
# File 'lib/jss/api_object/policy.rb', line 1162

def add_script(identifier, opts = {})
  opts[:position] ||= -1
  opts[:priority] ||= :after

  raise JSS::NoSuchItemError, "No script matches '#{identifier}'" unless (id = JSS::Script.valid_id(identifier))

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

  name = JSS::Script.map_all_ids_to(:name)[id]

  position = case opts[:position]
             when :start then 0
             when :end then -1
             else opts[:position]
             end

  raise JSS::InvalidDataError, "priority must be one of: :#{SCRIPT_PRIORITIES.keys.join ', :'}" unless \
    SCRIPT_PRIORITIES.include? opts[:priority]

  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 position, script_data

  ### if the user gave a large number for position, it created nil entries in the array, they need
  ### to be removed.
  @scripts.compact!

  @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

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.

#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

Raises:

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

Does this object have a category assigned?

#category_id ⇒ Integer Originally defined in module Categorizable

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’

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

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

#clone(new_name) ⇒ APIObject Originally defined in module Creatable

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

Raises:

#create ⇒ Integer Originally defined in module Creatable

Create a new object in the JSS.

Raises:

#delete_file? ⇒ Boolean Also known as: delete_path? 



955
956
957
 
# File 'lib/jss/api_object/policy.rb', line 955

def delete_file?
  @files_processes[:delete_file]
end

#directory_binding_ids ⇒ Array 



1220
1221
1222
 
# File 'lib/jss/api_object/policy.rb', line 1220

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

#directory_binding_names ⇒ Array 



1225
1226
1227
 
# File 'lib/jss/api_object/policy.rb', line 1225

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

#disable ⇒ Object

Shortcut for endabled = false



691
692
693
 
# File 'lib/jss/api_object/policy.rb', line 691

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



848
849
850
851
852
 
# File 'lib/jss/api_object/policy.rb', line 848

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 



1232
1233
1234
 
# File 'lib/jss/api_object/policy.rb', line 1232

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

#dock_item_names ⇒ Array 



1237
1238
1239
 
# File 'lib/jss/api_object/policy.rb', line 1237

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

#enable ⇒ Object

Shortcut for enabled = true



686
687
688
 
# File 'lib/jss/api_object/policy.rb', line 686

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

#file_vault_2_reboot=(fv_bool) ⇒ void

This method returns an undefined value.

Reboot Options FileVault Authenticated Reboot

Raises:



874
875
876
877
878
 
# File 'lib/jss/api_object/policy.rb', line 874

def file_vault_2_reboot=(fv_bool)
  raise JSS::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) ⇒ void

This method returns an undefined value.

Flush all policy logs for this policy older than some number of days, weeks, months or years.

With no parameters, flushes all logs

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

Raises:



1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
 
# File 'lib/jss/api_object/policy.rb', line 1284

def flush_logs(older_than: 0, period: :days)
  raise JSS::NoSuchItemError, "Policy doesn't exist in the JSS. Use #create first." \
    unless @in_jss
  raise JSS::InvalidDataError, "older_than must be one of: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" \
    unless LOG_FLUSH_INTERVAL_INTEGERS.keys.include? older_than
  raise JSS::InvalidDataError, "period must be one of: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" \
    unless LOG_FLUSH_INTERVAL_PERIODS.keys.include? period

  interval = "#{LOG_FLUSH_INTERVAL_INTEGERS[older_than]}+#{LOG_FLUSH_INTERVAL_PERIODS[period]}"

  JSS.api_connection.delete_rsrc "#{LOG_FLUSH_RSRC}/policy/id/#{@id}/interval/#{interval}"
end

#kill_process? ⇒ Boolean 



925
926
927
 
# File 'lib/jss/api_object/policy.rb', line 925

def kill_process?
  @files_processes[:kill_process]
end

#locate_file ⇒ String 



998
999
1000
 
# File 'lib/jss/api_object/policy.rb', line 998

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

Raises:



1008
1009
1010
1011
1012
 
# File 'lib/jss/api_object/policy.rb', line 1008

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

#message=(reboot_message) ⇒ void

This method returns an undefined value.

Reboot Options Set Reboot Message

Raises:



781
782
783
784
785
 
# File 'lib/jss/api_object/policy.rb', line 781

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

#minutes_until_reboot=(minutes) ⇒ void

This method returns an undefined value.

Reboot Options Minutes Until Reboot

Raises:



861
862
863
864
865
 
# File 'lib/jss/api_object/policy.rb', line 861

def minutes_until_reboot=(minutes)
  raise JSS::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.

Raises:

#no_user_logged_in=(no_user_option) ⇒ void

This method returns an undefined value.

Reboot Options No User Logged In

Raises:



823
824
825
826
827
 
# File 'lib/jss/api_object/policy.rb', line 823

def no_user_logged_in=(no_user_option)
  raise JSS::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

#package_ids ⇒ Array 



1021
1022
1023
 
# File 'lib/jss/api_object/policy.rb', line 1021

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

#package_names ⇒ Array 



1026
1027
1028
 
# File 'lib/jss/api_object/policy.rb', line 1026

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 



1244
1245
1246
 
# File 'lib/jss/api_object/policy.rb', line 1244

def printer_ids
  @printers.map { |p| p[:id] }
end

#printer_names ⇒ Array 



1249
1250
1251
 
# File 'lib/jss/api_object/policy.rb', line 1249

def printer_names
  @printers.map { |p| p[:name] }
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



1105
1106
1107
1108
1109
 
# File 'lib/jss/api_object/policy.rb', line 1105

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

#remove_script(identifier) ⇒ Array?

Remove a script from this policy by name or id



1211
1212
1213
1214
1215
 
# File 'lib/jss/api_object/policy.rb', line 1211

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

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

Try to execute this policy on this machine.



1263
1264
1265
1266
1267
1268
 
# File 'lib/jss/api_object/policy.rb', line 1263

def run(show_output = false)
  return nil unless enabled?
  output = JSS::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 



884
885
886
 
# File 'lib/jss/api_object/policy.rb', line 884

def run_command
  @files_processes[:run_command]
end

#run_command=(command) ⇒ void

This method returns an undefined value.

Set the unix shell command to be run on the client

Raises:



894
895
896
897
898
 
# File 'lib/jss/api_object/policy.rb', line 894

def run_command=(command)
  raise JSS::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 



1114
1115
1116
 
# File 'lib/jss/api_object/policy.rb', line 1114

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

#script_names ⇒ Array 



1119
1120
1121
 
# File 'lib/jss/api_object/policy.rb', line 1119

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

#search_by_path ⇒ Pathname 



949
950
951
 
# File 'lib/jss/api_object/policy.rb', line 949

def search_by_path
  Pathname.new @files_processes[:search_by_path]
end

#search_for_process ⇒ String 



919
920
921
 
# File 'lib/jss/api_object/policy.rb', line 919

def search_for_process
  @files_processes[:search_for_process]
end

#self_service_payload ⇒ Symbol Originally defined in module SelfServable

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

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

What devices types can get this thing in Self Service

#server_side_activation=(activation) ⇒ void

This method returns an undefined value.

Set Server Side Activation

Raises:



756
757
758
759
760
 
# File 'lib/jss/api_object/policy.rb', line 756

def server_side_activation=(activation)
  raise JSS::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

Raises:



768
769
770
771
772
 
# File 'lib/jss/api_object/policy.rb', line 768

def server_side_expiration=(expiration)
  raise JSS::InvalidDataError, 'Expiration must be a Time' unless expiration.is_a? Time
  @server_side_limitations[:expiration] = expiration
  @need_to_update = true
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=”

Raises:



971
972
973
974
975
976
 
# File 'lib/jss/api_object/policy.rb', line 971

def set_search_by_path(path, delete = false)
  raise JSS::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=”



941
942
943
944
945
 
# File 'lib/jss/api_object/policy.rb', line 941

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

Raises:



739
740
741
742
743
744
745
746
747
748
 
# File 'lib/jss/api_object/policy.rb', line 739

def set_trigger_event(type, new_val)
  raise JSS::InvalidDataError, "Trigger type must be one of #{TRIGGER_EVENTS.keys.join(', ')}" unless TRIGGER_EVENTS.keys.include? type
  if type == :custom
    raise JSS::InvalidDataError, 'Custom triggers must be Strings' unless new_val.is_a? String
  else
    raise JSS::InvalidDataError, 'Non-custom triggers must be true or false' unless JSS::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.

#specify_startup=(startup_volume) ⇒ void

This method returns an undefined value.

Reboot Options Specify Startup Volume Only Supports “Specify Local Startup Disk”

Raises:



810
811
812
813
814
 
# File 'lib/jss/api_object/policy.rb', line 810

def specify_startup=(startup_volume)
  raise JSS::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 



980
981
982
 
# File 'lib/jss/api_object/policy.rb', line 980

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

Raises:



990
991
992
993
994
 
# File 'lib/jss/api_object/policy.rb', line 990

def spotlight_search=(term)
  raise JSS::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.

Reboot Options Set Startup Disk Only Supports ‘Specify Local Startup Disk’ at the moment

Raises:



795
796
797
798
799
800
 
# File 'lib/jss/api_object/policy.rb', line 795

def startup_disk=(startup_disk_option)
  raise JSS::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

#update ⇒ Object Originally defined in module Scopable

A wrapper around the update method, to try catching RestClient::Conflict 409 errors when we couldn’t verify all ldap users/groups due to lack of ldap connections

#update_locate_database=(tf) ⇒ void

This method returns an undefined value.

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



912
913
914
915
 
# File 'lib/jss/api_object/policy.rb', line 912

def update_locate_database=(tf)
  @files_processes[:update_locate_database] = tf ? true : false
  @need_to_update = true
end

#update_locate_database? ⇒ Boolean 



902
903
904
 
# File 'lib/jss/api_object/policy.rb', line 902

def update_locate_database?
  @files_processes[:update_locate_database]
end

#upload(type, local_file) ⇒ String Originally defined in module Uploadable

Upload a file to the JSS via the REST Resource of the object to which this module is mixed in.

Raises:

#user_logged_in=(logged_in_option) ⇒ void

This method returns an undefined value.

Reboot Options User Logged In

Raises:



836
837
838
839
840
 
# File 'lib/jss/api_object/policy.rb', line 836

def user_logged_in=(logged_in_option)
  raise JSS::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_removable? ⇒ Boolean? Originally defined in module SelfServable

Can this thing be removed by the user?