Class: JSS::Policy

Inherits:
APIObject show all
Includes:
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
SCOPE_TARGET_KEY = 
:computers

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Policy

Returns a new instance of Policy.

See Also:



530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
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
 
# File 'lib/jss/api_object/policy.rb', line 530

def initialize(args = {})
  super

  if @in_jss
    gen = @init_data[:general]
    @category = JSS::APIObject.get_name(gen[:category])
    @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]

    parse_scope
    parse_self_service
    @in_self_service = @init_data[:self_service][:use_for_self_service]

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



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

def accounts
  @accounts
end

#category ⇒ String 



220
221
222
 
# File 'lib/jss/api_object/policy.rb', line 220

def category
  @category
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



313
314
315
 
# File 'lib/jss/api_object/policy.rb', line 313

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



379
380
381
 
# File 'lib/jss/api_object/policy.rb', line 379

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



515
516
517
 
# File 'lib/jss/api_object/policy.rb', line 515

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



508
509
510
 
# File 'lib/jss/api_object/policy.rb', line 508

def dock_items
  @dock_items
end

#enabled ⇒ Boolean Also known as: enabled? 



232
233
234
 
# File 'lib/jss/api_object/policy.rb', line 232

def enabled
  @enabled
end

#fix_byhost ⇒ Boolean (readonly) 



359
360
361
 
# File 'lib/jss/api_object/policy.rb', line 359

def fix_byhost
  @fix_byhost
end

#flush_system_cache ⇒ Boolean (readonly) 



365
366
367
 
# File 'lib/jss/api_object/policy.rb', line 365

def flush_system_cache
  @flush_system_cache
end

#flush_user_cache ⇒ Boolean (readonly) 



371
372
373
 
# File 'lib/jss/api_object/policy.rb', line 371

def flush_user_cache
  @flush_user_cache
end

#frequency ⇒ String 



223
224
225
 
# File 'lib/jss/api_object/policy.rb', line 223

def frequency
  @frequency
end

#install_cached_pkgs ⇒ Boolean (readonly) 



368
369
370
 
# File 'lib/jss/api_object/policy.rb', line 368

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



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

def 
  
end

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

#offline ⇒ Boolean 



229
230
231
 
# File 'lib/jss/api_object/policy.rb', line 229

def offline
  @offline
end

#open_firmware_efi_password ⇒ Hash (readonly) 



382
383
384
 
# File 'lib/jss/api_object/policy.rb', line 382

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”



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

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



429
430
431
 
# File 'lib/jss/api_object/policy.rb', line 429

def packages
  @packages
end

#permissions_repair ⇒ Boolean (readonly) 



353
354
355
 
# File 'lib/jss/api_object/policy.rb', line 353

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



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

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



486
487
488
 
# File 'lib/jss/api_object/policy.rb', line 486

def reboot_options
  @reboot_options
end

#recon ⇒ Boolean (readonly) 



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

def recon
  @recon
end

#reset_name ⇒ Boolean (readonly) 



362
363
364
 
# File 'lib/jss/api_object/policy.rb', line 362

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”



448
449
450
 
# File 'lib/jss/api_object/policy.rb', line 448

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? (OSX SSvc only)

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

NOTE: as of Casper 9.61 there’s a bug in the JSON output from the API, and only the last category is returned, if more than one are set.

#self_service_description ⇒ String Originally defined in module SelfServable

#self_service_feature_on_main_page ⇒ Boolean Originally defined in module SelfServable

#self_service_force_users_to_view_description ⇒ Boolean Originally defined in module SelfServable

#self_service_icon ⇒ Hash (readonly) Originally defined in module SelfServable

The Hash contains these keys with info about the icon:

  • :uri => [String] the URI for retriving the icon

  • :id => [Integer] the JSS id number for the icon (not all SSvc items have this)

  • :data => [String] the icon image encoded as Base64 (not all SSvc items have this)

  • :filename => [String] The name of the image file uploaded to the JSS, if applicable

#self_service_install_button_text ⇒ String Originally defined in module SelfServable

#self_service_user_removable ⇒ Hash (readonly) Originally defined in module SelfServable

The keys are

  • :removal_disallowed => [String] one of the items in PROFILE_REMOVAL_OPTIONS

  • :password => [String] if :removal_disallowed is “With Authorization”, this contains the passwd (in plaintext) needed to remove the profile.

NOTE that the key should be called :removal_allowed, since ‘Never’ means it can’t be removed.

#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



295
296
297
 
# File 'lib/jss/api_object/policy.rb', line 295

def server_side_limitations
  @server_side_limitations
end

#site ⇒ String (readonly) 



235
236
237
 
# File 'lib/jss/api_object/policy.rb', line 235

def site
  @site
end

#target_drive ⇒ String 



226
227
228
 
# File 'lib/jss/api_object/policy.rb', line 226

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.



320
321
322
 
# File 'lib/jss/api_object/policy.rb', line 320

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)



341
342
343
 
# File 'lib/jss/api_object/policy.rb', line 341

def trigger_events
  @trigger_events
end

#user_may_defer ⇒ Boolean (readonly) 



461
462
463
 
# File 'lib/jss/api_object/policy.rb', line 461

def user_may_defer
  @user_may_defer
end

#user_may_defer_until ⇒ Time (readonly) 



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

def user_may_defer_until
  @user_may_defer_until
end

#user_message_finish ⇒ String (readonly) 



470
471
472
 
# File 'lib/jss/api_object/policy.rb', line 470

def user_message_finish
  @user_message_finish
end

#user_message_start ⇒ String (readonly) 



467
468
469
 
# File 'lib/jss/api_object/policy.rb', line 467

def user_message_start
  @user_message_start
end

#verify_startup_disk ⇒ Boolean (readonly) 



350
351
352
 
# File 'lib/jss/api_object/policy.rb', line 350

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:



906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
 
# File 'lib/jss/api_object/policy.rb', line 906

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:



1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
 
# File 'lib/jss/api_object/policy.rb', line 1017

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: 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 SSvc.

Raises:

#add_to_self_service ⇒ void

This method returns an undefined value.

Add this policy to Self Service



1129
1130
1131
1132
 
# File 'lib/jss/api_object/policy.rb', line 1129

def add_to_self_service
  @need_to_update = (@in_self_service == false)
  @in_self_service = true
end

#assign_icon(icon) ⇒ void

This method returns an undefined value.

Select or upload an image file to be the self service icon. The policy must already exist in the JSS to upload an image.

NOTE: There is no way to verify the validity of an icon id, as they are not

available via the API. Caveat Emptor.

NOTE: When setting by id, Scopable#update or #APIObject#save must be used to save the change.



1155
1156
1157
1158
1159
1160
1161
1162
 
# File 'lib/jss/api_object/policy.rb', line 1155

def assign_icon(icon)
  if icon.is_a? Integer
    @self_service_icon = { id: icon }
    @need_to_update = true
    return
  end
  upload(:icon, icon)
end

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



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

def delete_file?
  @files_processes[:delete_file]
end

#directory_binding_ids ⇒ Array 



1075
1076
1077
 
# File 'lib/jss/api_object/policy.rb', line 1075

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

#directory_binding_names ⇒ Array 



1080
1081
1082
 
# File 'lib/jss/api_object/policy.rb', line 1080

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

#disable ⇒ Object

Shortcut for endabled = false



661
662
663
 
# File 'lib/jss/api_object/policy.rb', line 661

def disable
  self.enabled = false
end

#dock_item_ids ⇒ Array 



1087
1088
1089
 
# File 'lib/jss/api_object/policy.rb', line 1087

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

#dock_item_names ⇒ Array 



1092
1093
1094
 
# File 'lib/jss/api_object/policy.rb', line 1092

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

#enable ⇒ Object

Shortcut for enabled = true



656
657
658
 
# File 'lib/jss/api_object/policy.rb', line 656

def enable
  self.enabled = true
end

#in_self_service? ⇒ Boolean Also known as: self_service?

SelfService Is this policy in self service?



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

def in_self_service?
  @in_self_service
end

#kill_process? ⇒ Boolean 



780
781
782
 
# File 'lib/jss/api_object/policy.rb', line 780

def kill_process?
  @files_processes[:kill_process]
end

#locate_file ⇒ String 



853
854
855
 
# File 'lib/jss/api_object/policy.rb', line 853

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:



863
864
865
866
867
 
# File 'lib/jss/api_object/policy.rb', line 863

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

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

#package_ids ⇒ Array 



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

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

#package_names ⇒ Array 



881
882
883
 
# File 'lib/jss/api_object/policy.rb', line 881

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

#parse_self_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Call this during initialization of objects that have a self_service subset and the self_service attributes will be populated (as primary attributes) from @init_data

#printer_ids ⇒ Array 



1099
1100
1101
 
# File 'lib/jss/api_object/policy.rb', line 1099

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

#printer_names ⇒ Array 



1104
1105
1106
 
# File 'lib/jss/api_object/policy.rb', line 1104

def printer_names
  @printers.map { |p| p[:name] }
end

#remove_from_self_service ⇒ void

This method returns an undefined value.

Remove this policy from Self Service



1137
1138
1139
1140
 
# File 'lib/jss/api_object/policy.rb', line 1137

def remove_from_self_service
  @need_to_update = (@in_self_service == true)
  @in_self_service = false
end

#remove_package(identifier) ⇒ Array?

Remove a package from this policy by name or id



960
961
962
963
964
 
# File 'lib/jss/api_object/policy.rb', line 960

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



1066
1067
1068
1069
1070
 
# File 'lib/jss/api_object/policy.rb', line 1066

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.



1174
1175
1176
1177
1178
1179
 
# File 'lib/jss/api_object/policy.rb', line 1174

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 



739
740
741
 
# File 'lib/jss/api_object/policy.rb', line 739

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:



749
750
751
752
753
 
# File 'lib/jss/api_object/policy.rb', line 749

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 



969
970
971
 
# File 'lib/jss/api_object/policy.rb', line 969

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

#script_names ⇒ Array 



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

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

#search_by_path ⇒ Pathname 



804
805
806
 
# File 'lib/jss/api_object/policy.rb', line 804

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

#search_for_process ⇒ String 



774
775
776
 
# File 'lib/jss/api_object/policy.rb', line 774

def search_for_process
  @files_processes[:search_for_process]
end

#self_service_xml ⇒ REXML::Element Originally defined in module SelfServable

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.

Return a REXML <location> element to be included in the rest_xml of objects that have a Location subset

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



826
827
828
829
830
831
 
# File 'lib/jss/api_object/policy.rb', line 826

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



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

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:



724
725
726
727
728
729
730
731
732
733
 
# File 'lib/jss/api_object/policy.rb', line 724

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.

#spotlight_search ⇒ String 



835
836
837
 
# File 'lib/jss/api_object/policy.rb', line 835

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:



845
846
847
848
849
 
# File 'lib/jss/api_object/policy.rb', line 845

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

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



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

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

#update_locate_database? ⇒ Boolean 



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

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_removable? ⇒ FalseClass Also known as: user_removable=

policies in self service aren’t ‘removable’



1121
1122
1123
 
# File 'lib/jss/api_object/policy.rb', line 1121

def user_removable?
  false
end