Class: JSS::Policy

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

  • New policies cannot be created via this class, please use the WebApp.

  • Only a few attributes can be changed and updated via the Policy class:

    • name

    • frequency

    • target_drive

    • offline

    • enabled

    • category

    • triggers

    • files and processes

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

Policies may be deleted via this class

See Also:

Constant Summary collapse

RSRC_BASE =

The base for REST resources of this class

"policies"
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 ]
SECTIONS =
[
  :general,
  :maintenance,
  :account_maintenance,
  :scripts,
  :self_service,
  :package_configuration,
  :scope,
  :user_interaction,
  :reboot,
  :files_processes,
  :dock_items,
  :disk_encryption,
  :printers
]
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"
}
RESTART_WHEN =
{
  :if_pkg_requires => "Restart if a package or update requires it",
  :now => "Restart immediately",
  :delayed => "Restart",
  :dont => "Do not restart"
}
RESTART_DISKS =
{
  :current => "Current Startup Disk",
  :selected => "Currently Selected Startup Disk (No Bless)",
  :netboot => "NetBoot",
  :os_installer => "inPlaceOSUpgradeDirectory"
}
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"
}
MGMT_ACCOUNT_ACTIONS =
{
  :no_change => "doNotChange",
  :change_pw => "specified",
  :generate_pw => "random",
  :enable_fv2 => "fileVaultEnable",
  :disable_fv2 => "fileVaultDisable"
}
PACKAGE_ACTIONS =
{
  :install => "Install",
  :remove => "Uninstall",
  :cache =>"Cache",
  :install_cache => "Install Cached"
}
SCRIPT_PRIORITIES =
{:pre => "Before", :post => "After"}
PRINTER_ACTIIONS =
{:map => "install", :unmap => "uninstall"}
DOCK_ITEM_ACTIONS =
{:add_start => "Add To Beginning", :add_end => "Add To End", :remove => "Remove"}
NETWORK_REQUIREMENTS =
{:any => "Any", :ethernet => "EtherNet"}
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
}
TRIGGER_TYPES =
{:event => "EVENT", :user => "USER_INITIATED"}
SCOPE_TARGET_KEY =
:computers

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Policy

Returns a new instance of Policy.



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
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
# File 'lib/jss-api/api_object/policy.rb', line 512

def initialize(args = {})

  super


  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]

  @self_service = @init_data[:self_service]

  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

end

Instance Attribute Details

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



383
384
385
# File 'lib/jss-api/api_object/policy.rb', line 383

def accounts
  @accounts
end

#categoryString



199
200
201
# File 'lib/jss-api/api_object/policy.rb', line 199

def category
  @category
end

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



277
278
279
# File 'lib/jss-api/api_object/policy.rb', line 277

def client_side_limitations
  @client_side_limitations
end

#directory_bindingsArray<Hash> (readonly)

The directory bindings applied

each hash is like: {:name => “LDAP”, :id => 4}



347
348
349
# File 'lib/jss-api/api_object/policy.rb', line 347

def directory_bindings
  @directory_bindings
end

#disk_encryptionHash (readonly)

Disk encryption options for this policy

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



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

def disk_encryption
  @disk_encryption
end

#dock_itemsArray<Hash> (readonly)

The dock items handled by this policy

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



489
490
491
# File 'lib/jss-api/api_object/policy.rb', line 489

def dock_items
  @dock_items
end

#enabledBoolean Also known as: enabled?



211
212
213
# File 'lib/jss-api/api_object/policy.rb', line 211

def enabled
  @enabled
end

#fix_byhostBoolean (readonly)



322
323
324
# File 'lib/jss-api/api_object/policy.rb', line 322

def fix_byhost
  @fix_byhost
end

#flush_system_cacheBoolean (readonly)



328
329
330
# File 'lib/jss-api/api_object/policy.rb', line 328

def flush_system_cache
  @flush_system_cache
end

#flush_user_cacheBoolean (readonly)



334
335
336
# File 'lib/jss-api/api_object/policy.rb', line 334

def flush_user_cache
  @flush_user_cache
end

#frequencyString



202
203
204
# File 'lib/jss-api/api_object/policy.rb', line 202

def frequency
  @frequency
end

#install_cached_pkgsBoolean (readonly)



331
332
333
# File 'lib/jss-api/api_object/policy.rb', line 331

def install_cached_pkgs
  @install_cached_pkgs
end

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



364
365
366
# File 'lib/jss-api/api_object/policy.rb', line 364

def 
  
end

#need_to_updateBoolean (readonly) Originally defined in module Updatable

#offlineBoolean



208
209
210
# File 'lib/jss-api/api_object/policy.rb', line 208

def offline
  @offline
end

#open_firmware_efi_passwordHash (readonly)



351
352
353
# File 'lib/jss-api/api_object/policy.rb', line 351

def open_firmware_efi_password
  @open_firmware_efi_password
end

#override_default_settingsHash (readonly)

Overrides for various defaults

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



222
223
224
# File 'lib/jss-api/api_object/policy.rb', line 222

def override_default_settings
  @override_default_settings
end

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



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

def packages
  @packages
end

#permissions_repairBoolean (readonly)



316
317
318
# File 'lib/jss-api/api_object/policy.rb', line 316

def permissions_repair
  @permissions_repair
end

#printersArray<Hash> (readonly)

The printers handled by this policy

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



503
504
505
# File 'lib/jss-api/api_object/policy.rb', line 503

def printers
  @printers
end

#reboot_optionsHash (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. Please save anything you are working on and log out by choosing Log Out from the bottom of the Apple menu.”,

  • :startup_disk => “Current Startup Disk”,

  • :specify_startup => “”,

  • :no_user_logged_in => “Do not restart”



466
467
468
# File 'lib/jss-api/api_object/policy.rb', line 466

def reboot_options
  @reboot_options
end

#reconBoolean (readonly)



319
320
321
# File 'lib/jss-api/api_object/policy.rb', line 319

def recon
  @recon
end

#reset_nameBoolean (readonly)



325
326
327
# File 'lib/jss-api/api_object/policy.rb', line 325

def reset_name
  @reset_name
end

#scopeObject Originally defined in module Scopable

Attribtues

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



415
416
417
# File 'lib/jss-api/api_object/policy.rb', line 415

def scripts
  @scripts
end

#self_serviceHash (readonly)

Self-service-related data for this policy

The hash keys are:

  • :self_service_icon => {:uri => String,:id => Integer, :filename => String}

  • :use_for_self_service => true,

  • :install_button_text => “Install”,

  • :self_service_description => “Descriptive text”,

  • :force_users_to_view_description => false

Note: we’ll add a ruby-std convenience method below “self_service?”

which returns the :use_for_self_service key.


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

def self_service
  @self_service
end

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



259
260
261
# File 'lib/jss-api/api_object/policy.rb', line 259

def server_side_limitations
  @server_side_limitations
end

#siteString (readonly)



214
215
216
# File 'lib/jss-api/api_object/policy.rb', line 214

def site
  @site
end

#target_driveString



205
206
207
# File 'lib/jss-api/api_object/policy.rb', line 205

def target_drive
  @target_drive
end

#triggerString (readonly)

Either EVENT or USER_INITIATED

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



284
285
286
# File 'lib/jss-api/api_object/policy.rb', line 284

def trigger
  @trigger
end

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



305
306
307
# File 'lib/jss-api/api_object/policy.rb', line 305

def trigger_events
  @trigger_events
end

#user_may_deferBoolean (readonly)



443
444
445
# File 'lib/jss-api/api_object/policy.rb', line 443

def user_may_defer
  @user_may_defer
end

#user_may_defer_untilTime (readonly)



446
447
448
# File 'lib/jss-api/api_object/policy.rb', line 446

def user_may_defer_until
  @user_may_defer_until
end

#user_message_finishString (readonly)



452
453
454
# File 'lib/jss-api/api_object/policy.rb', line 452

def user_message_finish
  @user_message_finish
end

#user_message_startString (readonly)



449
450
451
# File 'lib/jss-api/api_object/policy.rb', line 449

def user_message_start
  @user_message_start
end

#verify_startup_diskBoolean (readonly)



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

def verify_startup_disk
  @verify_startup_disk
end

Instance Method Details

#delete_file?Boolean Also known as: delete_path?



757
# File 'lib/jss-api/api_object/policy.rb', line 757

def delete_file? ; @files_processes[:delete_file] ; end

#directory_binding_idsArray



826
# File 'lib/jss-api/api_object/policy.rb', line 826

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

#directory_binding_namesArray



829
# File 'lib/jss-api/api_object/policy.rb', line 829

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

#dock_item_idsArray



832
# File 'lib/jss-api/api_object/policy.rb', line 832

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

#dock_item_namesArray



835
# File 'lib/jss-api/api_object/policy.rb', line 835

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

#kill_process?Boolean



726
727
728
# File 'lib/jss-api/api_object/policy.rb', line 726

def kill_process?
  @files_processes[:kill_process]
end

#locate_fileString



799
# File 'lib/jss-api/api_object/policy.rb', line 799

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



807
808
809
810
811
# File 'lib/jss-api/api_object/policy.rb', line 807

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.

#package_idsArray



814
# File 'lib/jss-api/api_object/policy.rb', line 814

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

#package_namesArray



817
# File 'lib/jss-api/api_object/policy.rb', line 817

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

#parse_scopevoid Originally defined in module Scopable

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

This method returns an undefined value.

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

#printer_idsArray



838
# File 'lib/jss-api/api_object/policy.rb', line 838

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

#printer_namesArray



841
# File 'lib/jss-api/api_object/policy.rb', line 841

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

#run_commandString Also known as: command_to_run



684
# File 'lib/jss-api/api_object/policy.rb', line 684

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



693
694
695
696
697
# File 'lib/jss-api/api_object/policy.rb', line 693

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_idsArray



820
# File 'lib/jss-api/api_object/policy.rb', line 820

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

#script_namesArray



823
# File 'lib/jss-api/api_object/policy.rb', line 823

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

#search_by_pathPathname



752
# File 'lib/jss-api/api_object/policy.rb', line 752

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

#search_for_processString



719
720
721
# File 'lib/jss-api/api_object/policy.rb', line 719

def search_for_process
  @files_processes[:search_for_process]
end

#self_service?Boolean



844
# File 'lib/jss-api/api_object/policy.rb', line 844

def self_service?; @self_service[:use_for_self_service] ; 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=”



772
773
774
775
776
777
# File 'lib/jss-api/api_object/policy.rb', line 772

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



743
744
745
746
747
# File 'lib/jss-api/api_object/policy.rb', line 743

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



670
671
672
673
674
675
676
677
678
679
# File 'lib/jss-api/api_object/policy.rb', line 670

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.kind_of? 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_updatevoid Originally defined in module Scopable

This method returns an undefined value.

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

#spotlight_searchString



782
# File 'lib/jss-api/api_object/policy.rb', line 782

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



790
791
792
793
794
# File 'lib/jss-api/api_object/policy.rb', line 790

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

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



711
712
713
714
# File 'lib/jss-api/api_object/policy.rb', line 711

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

#update_locate_database?Boolean



702
# File 'lib/jss-api/api_object/policy.rb', line 702

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.