class Jamf::Policy
A class implementing a JSS
Policy
.
Like many API objects, the data comes from the API in sections, and the items in the :general section are mapped to direct attributes of this Class.
Policy
instances are partially read-only:
-
Due to limitations in the API implementation of policies, as well as the complexity of policy objects, only these attributes can be set and updated via the
Policy
class: -
name
-
-
frequency
-
-
offline
-
-
enabled
-
-
category
-
-
triggers
-
-
client maintenance tasks
-
-
scope, see {Jamf::Scopable} and {Jamf::Scopable::Scope}
-
-
files and processes
-
-
packages, see {#add_package} and {#remove_package}
-
-
scripts see {#add_script} and {#remove_script}
-
-
self service, see {Jamf::SelfServable}
-
-
reboot options
-
All other values and sections must be edited via the Web App.
Policies may be deleted via this class
Constants
- ACCOUNT_ACTIONS
- CATEGORY_DATA_TYPE
How is the category stored in the API data?
- CATEGORY_SUBSET
Where is the
Category
in the API JSON?- DISK_ENCRYPTION_ACTIONS
- DOCK_ITEM_ACTIONS
- FREQUENCIES
- LOG_FLUSH_INTERVAL_INTEGERS
- LOG_FLUSH_INTERVAL_PERIODS
- LOG_FLUSH_RSRC
Log Flushing
- MGMT_ACCOUNT_ACTIONS
- NETWORK_REQUIREMENTS
- NO_USER_LOGGED_IN
- OBJECT_HISTORY_OBJECT_TYPE
the object type for this object in the object history table. See {APIObject#add_object_history_entry}
- PACKAGE_ACTIONS
- PRINTER_ACTIONS
- RESTART_DISKS
- RESTART_WHEN
- RETRY_EVENTS
- RSRC_BASE
The base for REST resources of this class
- RSRC_LIST_KEY
the hash key used for the JSON list output of all objects in the
JSS
- RSRC_OBJECT_KEY
The hash key used for the JSON object output. It’s also used in various error messages
- SCOPE_TARGET_KEY
- SCRIPT_PARAMETERS_AVAILABLE
All valid script parameters
- SCRIPT_PRIORITIES
- SECTIONS
- SELF_SERVICE_PAYLOAD
policies via self services are still polcies
- SELF_SERVICE_TARGET
policies are available in macOS self Serviec
- SITE_SUBSET
Where is the
Site
data in the API JSON?- SUBSETS
subsets available for fetching TODO: FilesProcesses and Maintenance don’t seem to work
- TRIGGER_EVENTS
- TRIGGER_TYPES
- UPLOAD_TYPES
policies can take uploaded icons
- USER_LOGGED_IN
Attributes
@return [Array<Hash>]
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
@return [Hash]
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
@return [Array<Hash>]
The directory bindings applied
each hash is like: !{:name => “LDAP”, :id => 4} TODO: handle as for packages & scripts
@return [Hash]
Disk encryption options for this policy
The hash looks like !{:disk_encryption_configuration_id => 3, :action => “apply”}
@return [Array<Hash>]
The dock items handled by this policy
each item hash looks like: !{:name => “Mail”, :id => 14, :action => “Add To Beginning”}
@return [Boolean] is the policy enabled?
@return [Boolean] is the policy enabled?
Should this policy fix the ByHost prefs? @return [Boolean] client maintenance task
Should this policy flush the system cache? @return [Boolean] client maintenance task
Should this policy flush the user cache? @return [Boolean] client maintenance task
@return [String] how often to run the policy on each computer
Should this policy install any cached JSS
packages? @return [Boolean] client maintenance task
@return [Hash]
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
@return [Boolean] should be policy be available offline
@return [Hash] the open firmware mode and password
@return [Hash]
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”
@return [Array<Hash>]
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
Should this policy run a permission repair? @return [Boolean] client maintenance task
@return [Array<Hash>]
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
@return [Array<Hash>]
The printers handled by this policy
Each Hash
looks like: !{:make_default => false, :name => “torlan”, :id => 3, :action => “install”}
@return [Hash]
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
Should this policy run a recon? @return [Boolean] client maintenance task
Should this policy reset the local hostname? @return [Boolean] client maintenance task
@return [Array<Hash>]
The scripts run by this policy
Hash
keys are:
-
:name => “chromegetter.sh”,
-
:parameter4 => “”,
-
:parameter5 => “”,
-
:parameter6 => “”,
-
:parameter7 => “”,
-
:parameter8 => “”,
-
:parameter9 => “”,
-
:parameter10 => “”,
-
:parameter11 => “”,
-
:id => 1428,
-
:priority => “After”
@return [Hash]
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
@return [String] a string with the site name
@return [String] which drive should the policy target
@return [String]
Either EVENT or USER_INITIATED
If it’s EVENT, then one or more of the members @trigger_events must true.
@return [Hash]
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)
Should this policy run a recon? @return [Boolean] client maintenance task
@return [Boolean] can the user defer the policy?
@return [Time] when is the user no longer allowed to defer?
@return [String] the message shown the user at policy end
@return [String] the message shown the user at policy end
@return [String] the message shown the user at policy start
Should this policy verify the startup disk? @return [Boolean] client maintenance task
Public Class Methods
Flush logs for a given policy older than a given time period. This flushes the logs of the given policy for all computers.
IMPORTANT: from the Jamf
Developer Site:
The ability to flush logs is currently only supported for flushing all logs for a given policy or all logs for a given computer. There is no support for flushing logs for a given policy and computer combination.
(See .flush_logs_for_computers to to flush all logs for given computers)
With no parameters, flushes all logs for the policy.
Without older_than: and period:, will flush all logs for the policy
NOTE: Currently the API doesn’t have a way to flush only failed policies.
WARNING: Log flushing can take a long time, and the API call doesnt return until its finished. The connection timeout will be temporarily raised to 30 minutes, unless it’s already higher.
@param policy The id or name of the policy to flush
@param older_than 0, 1, 2, 3, or 6, defaults to 0
@param period :days, :weeks, :months, or :years, defaults to :days
@param cnx [Jamf::Connection] the API connection to use.
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 326 def self.flush_logs(policy, older_than: 0, period: :days, api: nil, cnx: Jamf.cnx) 327 cnx = api if api 328 329 pol_id = valid_id policy, cnx: cnx 330 raise Jamf::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id 331 332 older_than, period = validate_log_flush_params(older_than, period) 333 334 # log flushes can be really slow 335 orig_timeout = cnx.timeout 336 cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800 337 338 cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}" 339 ensure 340 cnx.timeout = orig_timeout 341 end
Flush policy logs for specific computers older than a given time period. This flushes the logs for all policies for these computers.
IMPORTANT: from the Jamf
Developer Site:
The ability to flush logs is currently only supported for flushing all logs for a given policy or all logs for a given computer. There is no support for flushing logs for a given policy and computer combination.
(See .flush_logs to to flush all logs for a given policy)
Without older_than: and period:, will flush all logs for the computers
NOTE: Currently the API doesn’t have a way to flush only failed policies.
WARNING: Log flushing can take a long time, and the API call doesnt return until its finished. The connection timeout will be temporarily raised to 30 minutes, unless it’s already higher.
@param computers Identifiers of the target computers
either ids, names, SNs, macaddrs, or UDIDs.
@param older_than 0, 1, 2, 3, or 6, defaults to 0
@param period :days, :weeks, :months, or :years, defaults to :days
@param cnx [Jamf::Connection] the API connection to use.
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 372 def self.flush_logs_for_computers(computers = [], older_than: 0, period: :days, api: nil, cnx: Jamf.cnx) 373 cnx = api if api 374 375 computers = [computers] unless computers.is_a? Array 376 raise JSS::InvalidDataError, 'One or more computers must be specified' if computers.empty? 377 378 older_than, period = validate_log_flush_params(older_than, period) 379 380 # build the xml body for a DELETE request 381 xml_doc = REXML::Document.new Jamf::Connection::XML_HEADER 382 lf = xml_doc.add_element 'logflush' 383 lf.add_element('log').text = 'policy' 384 lf.add_element('interval').text = "#{older_than} #{period}" 385 386 comps_elem = lf.add_element 'computers' 387 computers.each do |c| 388 id = Jamf::Computer.valid_id c, cnx: cnx 389 next unless id 390 391 ce = comps_elem.add_element 'computer' 392 ce.add_element('id').text = id.to_s 393 end 394 395 # for debugging the xml... 396 # 397 # formatter = REXML::Formatters::Pretty.new(2) 398 # formatter.compact = true 399 # formatter.write(xml_doc, $stdout) 400 # puts 401 # return 402 403 # log flushes can be really slow 404 orig_timeout = cnx.timeout 405 cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800 406 407 # Do a DELETE request with a body. 408 resp = cnx.c_cnx.delete(LOG_FLUSH_RSRC) do |req| 409 req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML 410 req.body = xml_doc.to_s 411 end 412 413 resp.body 414 ensure 415 cnx.timeout = orig_timeout 416 end
@see APIObject#initialize
Jamf::APIObject::new
# File lib/jamf/api/classic/api_objects/policy.rb 758 def initialize(**args) 759 super 760 761 if @in_jss 762 gen = @init_data[:general] 763 @target_drive = gen[:target_drive] 764 @offline = gen[:offline] 765 @enabled = gen[:enabled] 766 @site = Jamf::APIObject.get_name(gen[:site][:name]) 767 @override_default_settings = gen[:override_default_settings] 768 @trigger = gen[:trigger] 769 @trigger_events = { 770 trigger_startup: gen[:trigger_startup], 771 trigger_login: gen[:trigger_login], 772 trigger_logout: gen[:trigger_logout], 773 trigger_checkin: gen[:trigger_checkin], 774 trigger_network_state_changed: gen[:trigger_network_state_changed], 775 trigger_enrollment_complete: gen[:trigger_enrollment_complete], 776 trigger_other: gen[:trigger_other] 777 } 778 @frequency = gen[:frequency] 779 @retry_event = gen[:retry_event] 780 @retry_attempts = gen[:retry_attempts] 781 @notify_failed_retries = gen[:notify_on_each_failed_retry] 782 783 dtl = gen[:date_time_limitations] 784 785 @server_side_limitations = { 786 activation: JSS.epoch_to_time(dtl[:activation_date_epoch]), 787 expiration: JSS.epoch_to_time(dtl[:expiration_date_epoch]) 788 } 789 790 @client_side_limitations = { 791 no_execute_on: dtl[:no_execute_on], # NOTE- there's a bug in the JSON output, it's been reported to JAMF. 792 no_execute_start: dtl[:no_execute_start], # String like "1:01 AM" 793 no_execute_end: dtl[:no_execute_end], # String like "2:02 PM" 794 network_requirements: gen[:network_requirements] 795 } 796 797 maint = @init_data[:maintenance] 798 @verify_startup_disk = maint[:verify] 799 @permissions_repair = maint[:permissions] 800 @recon = maint[:recon] 801 @fix_byhost = maint[:byhost] 802 @reset_name = maint[:reset_name] 803 @flush_system_cache = maint[:system_cache] 804 @install_cached_pkgs = maint[:install_all_cached_packages] 805 @flush_user_cache = maint[:user_cache] 806 807 amaint = @init_data[:account_maintenance] 808 @directory_bindings = amaint[:directory_bindings] 809 @open_firmware_efi_password = amaint[:open_firmware_efi_password] 810 @management_account = amaint[:management_account] 811 @accounts = amaint[:accounts] 812 813 @packages = @init_data[:package_configuration][:packages] || [] 814 815 @scripts = @init_data[:scripts] 816 817 uint = @init_data[:user_interaction] 818 @user_may_defer = uint[:allow_users_to_defer] 819 @user_may_defer_until = Jamf.parse_time uint[:allow_deferral_until_utc] 820 @user_message_start = uint[:message_start] 821 @user_message_finish = uint[:message_finish] 822 823 @reboot_options = @init_data[:reboot] 824 825 @files_processes = @init_data[:files_processes] 826 827 @dock_items = @init_data[:dock_items] 828 829 @disk_encryption = @init_data[:disk_encryption] 830 831 @printers = @init_data[:printers] 832 @printers.shift 833 834 # Not in jss yet 835 end 836 837 # set non-nil defaults 838 @enabled ||= false 839 @frequency ||= 'Once per computer' 840 @target_drive ||= '/' 841 @offline ||= false 842 @override_default_settings ||= {} 843 @scripts ||= [] 844 @server_side_limitations ||= {} 845 @client_side_limitiations ||= {} 846 @trigger_events ||= {} 847 @directory_bindings ||= [] 848 @open_firmware_efi_password ||= {} 849 @management_account ||= {} 850 @accounts ||= [] 851 @packages ||= [] 852 @scripts ||= [] 853 @self_service ||= {} 854 @dock_items ||= [] 855 @disk_encryption ||= {} 856 @printers ||= [] 857 @files_processes ||= {} 858 unless @reboot_options 859 @reboot_options = {} 860 @reboot_options[:user_logged_in] = 'Do not restart' 861 @reboot_options[:no_user_logged_in] = 'Do not restart' 862 end 863 864 @scope ||= Jamf::Scopable::Scope.new(:computers, all_computers: false) 865 end
Private Class Methods
validate the logflush params @return [Array<String>]
# File lib/jamf/api/classic/api_objects/policy.rb 420 def self.validate_log_flush_params(older_than, period) 421 older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than] 422 raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than 423 424 period = LOG_FLUSH_INTERVAL_PERIODS[period] 425 raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period 426 427 [older_than, period] 428 end
Public Instance Methods
Add a Directory Bidning to the list of directory_bindings
handled by this policy. If the directory binding already exists in the policy, nil is returned and no changes are made.
@param [String,Integer] identifier the name or id of the directory binding to add to this policy
@param position [Symbol, Integer] where to add this directory binding among the list of
directory_bindings. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end
@return [Array, nil] the new @directory_bindings array, nil if directory_binding was already in the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1640 def add_directory_binding(identifier, **opts) 1641 id = validate_directory_binding_opts identifier, opts 1642 1643 return nil if @directory_bindings.map { |s| s[:id] }.include? id 1644 1645 name = Jamf::DirectoryBinding.map_all_ids_to(:name, cnx: @cnx)[id] 1646 1647 directory_binding_data = { 1648 id: id, 1649 name: name 1650 } 1651 1652 @directory_bindings.insert opts[:position], directory_binding_data 1653 1654 @need_to_update = true 1655 @directory_bindings 1656 end
Add a dock item to the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1735 def add_dock_item(identifier, action) 1736 id = Jamf::DockItem.valid_id identifier, cnx: @cnx 1737 1738 raise Jamf::NoSuchItemError, "No Dock Item matches '#{identifier}'" unless id 1739 1740 raise Jamf::InvalidDataError, "Action must be one of: :#{DOCK_ITEM_ACTIONS.keys.join ', :'}" unless DOCK_ITEM_ACTIONS.include? action 1741 1742 return nil if @dock_items.map { |d| d[:id] }.include? id 1743 1744 name = Jamf::DockItem.map_all_ids_to(:name, cnx: @cnx)[id] 1745 1746 @dock_items << { id: id, name: name, action: DOCK_ITEM_ACTIONS[action] } 1747 1748 @need_to_update = true 1749 @dock_items 1750 end
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.
@param [String,Integer] identifier the name or id of the package to add to this policy
@param position [Symbol, Integer] where to add this pkg among the list of
pkgs. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end
@param action [String] One of the values of PACKAGE_ACTIONS
@param feu [Boolean] Overrides the setting for the pkg itself Defaults to false
@param fut [Boolean] Overrides the setting for the pkg itself Defaults to false
@param update_autorun [Boolean] Defaults to false
@return [Array, nil] the new @packages array, nil if pkg was already in the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1453 def add_package(identifier, **opts) 1454 id = validate_package_opts(identifier, opts) 1455 1456 return nil if @packages.map { |p| p[:id] }.include? id 1457 1458 name = Jamf::Package.map_all_ids_to(:name, cnx: @cnx)[id] 1459 1460 pkg_data = { 1461 id: id, 1462 name: name, 1463 action: PACKAGE_ACTIONS[opts[:action]], 1464 feu: opts[:feu], 1465 fut: opts[:feu], 1466 update_autorun: opts[:update_autorun] 1467 } 1468 1469 @packages.insert opts[:position], pkg_data 1470 1471 @need_to_update = true 1472 @packages 1473 end
Add a specific printer object to the policy.
@author Tyler Morgan
@param newvalue [String,Integer] The name or the id of the printer to be added to this policy.
@param position [Symbol, Integer] where to add this printer object among the list of printer
objects. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end
@param action [Symbol] One of the PRINTER_ACTIONS
symbols. What you want done with the printer object upon policy execution.
@param make_default [TrueClass,FalseClass] Should this printer object be set to default.
Defaults to false
@return [String] The new printers array or nil if the printer was already in the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1700 def add_printer(identifier, **opts) 1701 id = validate_printer_opts identifier, opts 1702 1703 return nil if @printers.map { |p| p[:id] }.include? id 1704 1705 name = Jamf::Printer.map_all_ids_to(:name, cnx: @cnx)[id] 1706 1707 printer_data = { 1708 id: id, 1709 name: name, 1710 action: PRINTER_ACTIONS[opts[:action]], 1711 make_default: opts[:make_default] 1712 } 1713 1714 @printers.insert opts[:position], printer_data 1715 1716 @need_to_update = true 1717 @printers 1718 end
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.
@param [String,Integer] identifier the name or id of the script to add to this policy
@param [Hash] opts the options for this script
@option [Symbol, Integer] position: where to add this script among the list of
scripts. Zero-based, :start and 0 are the same, as are :end and -1. Defaults to :end
@option [Symbol] priority: either :before or :after
@option [String] parameter4: the value of the 4th parameter passed to the script.
@option [String] parameter5: the value of the 5th parameter passed to the script.
@option [String] parameter6: the value of the 6th parameter passed to the script.
@option [String] parameter7: the value of the 7th parameter passed to the script.
@option [String] parameter8: the value of the 8th parameter passed to the script.
@option [String] parameter9: the value of the 9th parameter passed to the script.
@option [String] parameter10: the value of the 10th parameter passed to the script.
@option [String] parameter11: the value of the 11th parameter passed to the script.
@return [Array, nil] the new @scripts array, nil if script was already in the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1530 def add_script(identifier, **opts) 1531 id = validate_script_opts(identifier, opts) 1532 1533 return nil if @scripts.map { |s| s[:id] }.include? id 1534 1535 name = Jamf::Script.map_all_ids_to(:name, cnx: @cnx)[id] 1536 1537 script_data = { 1538 id: id, 1539 name: name, 1540 priority: SCRIPT_PRIORITIES[opts[:priority]], 1541 parameter4: opts[:parameter4], 1542 parameter5: opts[:parameter5], 1543 parameter6: opts[:parameter6], 1544 parameter7: opts[:parameter7], 1545 parameter8: opts[:parameter8], 1546 parameter9: opts[:parameter9], 1547 parameter10: opts[:parameter10], 1548 parameter11: opts[:parameter11] 1549 } 1550 1551 @scripts.insert opts[:position], script_data 1552 1553 @need_to_update = true 1554 @scripts 1555 end
Sets the Disk Encryption application to “Apply” and sets the correct disk encryption configuration ID using either the name or id.
@author Tyler Morgan
@return [Void]
# File lib/jamf/api/classic/api_objects/policy.rb 1805 def apply_encryption_configuration(identifier) 1806 id = Jamf::DiskEncryptionConfiguration.valid_id identifier 1807 1808 return if id.nil? 1809 1810 hash = { 1811 action: DISK_ENCRYPTION_ACTIONS[:apply], 1812 disk_encryption_configuration_id: id, 1813 auth_restart: false 1814 } 1815 1816 @disk_encryption = hash 1817 @need_to_update = true 1818 end
@return [Boolean] Should the searched-for path be deleted if found?
# File lib/jamf/api/classic/api_objects/policy.rb 1354 def delete_file? 1355 @files_processes[:delete_file] 1356 end
@return [Array] the id’s of the directory_bindings
handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1619 def directory_binding_ids 1620 @directory_bindings.map { |p| p[:id] } 1621 end
@return [Array] the names of the directory_bindings
handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1624 def directory_binding_names 1625 @directory_bindings.map { |p| p[:name] } 1626 end
Shortcut for endabled = false
# File lib/jamf/api/classic/api_objects/policy.rb 888 def disable 889 self.enabled = false 890 end
Reboot Options Do Not Reboot Shortcut method to suppress Reboot Options
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1238 def do_not_reboot 1239 @reboot_options[:user_logged_in] = 'Do not restart' 1240 @reboot_options[:no_user_logged_in] = 'Do not restart' 1241 @need_to_update = true 1242 end
@return [Array] the id’s of the dock_items
handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1673 def dock_item_ids 1674 @dock_items.map { |p| p[:id] } 1675 end
@return [Array] the names of the dock_items
handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1678 def dock_item_names 1679 @dock_items.map { |p| p[:name] } 1680 end
Shortcut for enabled = true
# File lib/jamf/api/classic/api_objects/policy.rb 883 def enable 884 self.enabled = true 885 end
Change the enabled state of this item
@param new_val the new state.
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 875 def enabled=(new_val) 876 return if @enabled == new_val 877 878 @enabled = Jamf::Validate.boolean new_val 879 @need_to_update = true 880 end
Reboot Options FileVault
Authenticated Reboot
@param fv_bool true or false
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1265 def file_vault_2_reboot=(fv_bool) 1266 raise Jamf::InvalidDataError, 'FileVault 2 Reboot must be a Boolean' unless fv_bool.jss_boolean? 1267 1268 @reboot_options[:file_vault_2_reboot] = fv_bool 1269 @need_to_update = true 1270 end
see attr_reader :fix_byhost
# File lib/jamf/api/classic/api_objects/policy.rb 1091 def fix_byhost=(bool) 1092 return if @fix_byhost == bool 1093 1094 @fix_byhost = Jamf::Validate.boolean bool 1095 @need_to_update = true 1096 end
Flush logs for this policy older than a given time period.
IMPORTANT: from the Jamf
Developer Site:
The ability to flush logs is currently only supported for flushing all logs for a given policy or all logs for a given computer. There is no support for flushing logs for a given policy and computer combination.
With no parameters, will flush all logs for the policy
NOTE: Currently the API doesn’t have a way to flush only failed policies.
WARNING: Log flushing can take a long time, and the API call doesnt return until its finished. The connection timeout will be temporarily raised to 30 minutes, unless it’s already higher.
@param older_than 0, 1, 2, 3, or 6
@param period :days, :weeks, :months, or :years
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1935 def flush_logs(older_than: 0, period: :days) 1936 raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #save first." unless @in_jss 1937 1938 Jamf::Policy.flush_logs( 1939 @id, 1940 older_than: older_than, 1941 period: period, 1942 cnx: @cnx 1943 ) 1944 end
see attr_reader :flush_system_cache
# File lib/jamf/api/classic/api_objects/policy.rb 1109 def flush_system_cache=(bool) 1110 return if @flush_system_cache == bool 1111 1112 @flush_system_cache = Jamf::Validate.boolean bool 1113 @need_to_update = true 1114 end
see attr_reader :flush_user_cache
# File lib/jamf/api/classic/api_objects/policy.rb 1127 def flush_user_cache=(bool) 1128 return if @flush_user_cache == bool 1129 1130 @flush_user_cache = Jamf::Validate.boolean bool 1131 @need_to_update = true 1132 end
Set a new frequency for this policy.
@param freq the desired frequency, must be one of the keys of {FREQUENCIES}
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 898 def frequency=(freq) 899 raise Jamf::InvalidDataError, "New frequency must be one of :#{FREQUENCIES.keys.join ', :'}" unless FREQUENCIES.key?(freq) || FREQUENCIES.value?(freq) 900 901 freq = freq.is_a?(Symbol) ? FREQUENCIES[freq] : freq 902 return if freq == @frequency 903 904 @frequency = freq 905 @need_to_update = true 906 end
see attr_reader :install_cached_pkgs
# File lib/jamf/api/classic/api_objects/policy.rb 1118 def install_cached_pkgs=(bool) 1119 return if @install_cached_pkgs == bool 1120 1121 @install_cached_pkgs = Jamf::Validate.boolean bool 1122 @need_to_update = true 1123 end
@return [Boolean] Should the searched-for process be killed if found.
# File lib/jamf/api/classic/api_objects/policy.rb 1320 def kill_process? 1321 @files_processes[:kill_process] 1322 end
@return [String] The term to seach for using the locate command
# File lib/jamf/api/classic/api_objects/policy.rb 1400 def locate_file 1401 @files_processes[:locate_file] 1402 end
Set the term to seach for using the locate command
@param term the term to seach for using the locate command
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1410 def locate_file=(term) 1411 raise Jamf::InvalidDataError, 'Term to locate must be a String' unless term.is_a? String 1412 1413 @files_processes[:locate_file] = term 1414 @need_to_update = true 1415 end
Reboot Options Minutes Until Reboot
@param minutes The number of minutes to delay prior to reboot
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1251 def minutes_until_reboot=(minutes) 1252 raise Jamf::InvalidDataError, 'Minutes until reboot must be an Integer' unless minutes.is_a? Integer 1253 1254 @reboot_options[:minutes_until_reboot] = minutes 1255 @need_to_update = true 1256 end
What to do at reboot when No User
Logged In
@param no_user_option Any one of the Strings from NO_USER_LOGGED_IN
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1143 def no_user_logged_in=(no_user_option) 1144 raise Jamf::InvalidDataError, "no_user_logged_in options: #{NO_USER_LOGGED_IN.join(', ')}" unless NO_USER_LOGGED_IN.include? no_user_option 1145 1146 @reboot_options[:no_user_logged_in] = no_user_option 1147 @need_to_update = true 1148 end
@param bool Should admins be notified of failed retry attempts @return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 978 def notify_failed_retries=(bool) 979 validate_retry_opt 980 bool = Jamf::Validate.boolean bool 981 return if @notify_failed_retries == bool 982 983 @notify_failed_retries = bool 984 @need_to_update = true 985 end
@return [Boolean] Should admins be notified of failed retry attempts
# File lib/jamf/api/classic/api_objects/policy.rb 968 def notify_failed_retries? 969 return false unless FREQUENCIES[:once_per_computer] == @frequency 970 971 @notify_failed_retries 972 end
Set whether this policy is available offline.
@param new_val
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1006 def offline=(new_val) 1007 raise Jamf::InvalidDataError, 'New value must be boolean true or false' unless Jamf::TRUE_FALSE.include? new_val 1008 1009 @offline = new_val 1010 @need_to_update = true 1011 end
@return [Array] the id’s of the packages handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1424 def package_ids 1425 @packages.map { |p| p[:id] } 1426 end
@return [Array] the names of the packages handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1429 def package_names 1430 @packages.map { |p| p[:name] } 1431 end
see attr_reader :permissions_repair
# File lib/jamf/api/classic/api_objects/policy.rb 1072 def permissions_repair=(bool) 1073 return if @permissions_repair == bool 1074 1075 @permissions_repair = Jamf::Validate.boolean bool 1076 @need_to_update = true 1077 end
@return [Array] the id’s of the printers handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1761 def printer_ids 1762 @printers.map { |p| p[:id] } 1763 rescue TypeError 1764 [] 1765 end
@return [Array] the names of the printers handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1768 def printer_names 1769 @printers.map { |p| p[:name] } 1770 rescue TypeError 1771 [] 1772 end
Set Reboot Message
@param reboot_message Text of Reboot Message
@return [void] description of returned object
# File lib/jamf/api/classic/api_objects/policy.rb 1169 def reboot_message=(message) 1170 raise Jamf::InvalidDataError, 'Reboot message must be a String' unless message.is_a? String 1171 1172 @reboot_options[:message] = message 1173 @need_to_update = true 1174 end
see attr_reader :recon
# File lib/jamf/api/classic/api_objects/policy.rb 1081 def recon=(bool) 1082 return if @recon == bool 1083 1084 @recon = Jamf::Validate.boolean bool 1085 @need_to_update = true 1086 end
Sets the Disk Encryption application to “Remediate” and sets the remediation key type to individual.
@author Tyler Morgan
@return [Void]
# File lib/jamf/api/classic/api_objects/policy.rb 1782 def reissue_key 1783 if @disk_encryption[:action] != DISK_ENCRYPTION_ACTIONS[:remediate] 1784 # Setting New Action 1785 hash = { 1786 action: DISK_ENCRYPTION_ACTIONS[:remediate], 1787 remediate_key_type: 'Individual' 1788 } 1789 1790 @disk_encryption = hash 1791 @need_to_update = true 1792 1793 else 1794 # Update 1795 nil 1796 end 1797 end
Remove a directory binding from this policy by name or id
@param identifier [String,Integer] the name or id of the directory binding to remove
@return [Array, nil] the new directory bindings array or nil if no change
# File lib/jamf/api/classic/api_objects/policy.rb 1664 def remove_directory_binding(identifier) 1665 removed = @directory_bindings.delete_if { |s| s[:id] == identifier || s[:name] == identifier } 1666 @need_to_update = true if removed 1667 removed 1668 end
Remove a dock item from the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1753 def remove_dock_item(identifier) 1754 # TODO: Add validation against Jamf::DockItem 1755 removed = @dock_items.delete_if { |d| d[:id] == identifier || d[:name] == identifier } 1756 @need_to_update = true if removed 1757 removed 1758 end
Removes the Disk Encryption settings associated with this specific policy.
@author Tyler Morgan
@return [Void]
# File lib/jamf/api/classic/api_objects/policy.rb 1826 def remove_encryption_configuration 1827 hash = { 1828 action: DISK_ENCRYPTION_ACTIONS[:none] 1829 } 1830 1831 @disk_encryption = hash 1832 @need_to_update = true 1833 end
Remove a package from this policy by name or id
@param identifier [String,Integer] the name or id of the package to remove
@return [Array, nil] the new packages array or nil if no change
# File lib/jamf/api/classic/api_objects/policy.rb 1481 def remove_package(identifier) 1482 removed = @packages.delete_if { |p| p[:id] == identifier || p[:name] == identifier } 1483 @need_to_update = true if removed 1484 removed 1485 end
Remove a specific printer object from the policy.
@author Tyler Morgan
@param identifier [String,Integer] The name or id of the printer to be removed.
@return [Array, nil] The new printers array or nil if no change.
# File lib/jamf/api/classic/api_objects/policy.rb 1727 def remove_printer(identifier) 1728 removed = @printers.delete_if { |p| p[:id] == identifier || p[:name] == identifier } 1729 1730 @need_to_update = true 1731 removed 1732 end
Remove a script from this policy by name or id
@param identifier [String,Integer] the name or id of the script to remove
@return [Array, nil] the new scripts array or nil if no change
# File lib/jamf/api/classic/api_objects/policy.rb 1563 def remove_script(identifier) 1564 removed = @scripts.delete_if { |s| s[:id] == identifier || s[:name] == identifier } 1565 @need_to_update = true if removed 1566 removed 1567 end
see attr_reader :reset_name
# File lib/jamf/api/classic/api_objects/policy.rb 1100 def reset_name=(bool) 1101 return if @reset_name == bool 1102 1103 @reset_name = Jamf::Validate.boolean bool 1104 @need_to_update = true 1105 end
@return [Integer] How many times wil the policy be retried if it fails.
-1 means no retries, otherwise, an integer from 1 to 10
# File lib/jamf/api/classic/api_objects/policy.rb 939 def retry_attempts 940 return 0 unless FREQUENCIES[:once_per_computer] == @frequency 941 942 @retry_attempts 943 end
Set the number of times to retry if the policy fails. One of the ways to turn off policy retry is to set this to 0 or -1 The other is to set retry_event
to :none
@param [Integer] From -1 to 10 @return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 952 def retry_attempts=(int) 953 validate_retry_opt 954 raise Jamf::InvalidDataError, 'Retry attempts must be an integer from 0-10' unless int.is_a?(Integer) && (-1..10).include?(int) 955 956 # if zero or -1, turn off retries 957 if int <= 0 958 @retry_event = RETRY_EVENTS[:none] 959 int = -1 960 end 961 return if @retry_attempts == int 962 963 @retry_attempts = int 964 @need_to_update = true 965 end
@return [String] The event that causes a policy retry
# File lib/jamf/api/classic/api_objects/policy.rb 909 def retry_event 910 return RETRY_EVENTS[:none] unless FREQUENCIES[:once_per_computer] == @frequency 911 912 @retry_event 913 end
Set the event that causes a retry if the policy fails. One of the ways to turn off policy retry is to set this to :none The other is to set the retry_attempts
to 0
@param [Symbol, String] A key or value from RETRY_EVENTS
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 922 def retry_event=(evt) 923 validate_retry_opt 924 raise Jamf::InvalidDataError, "Retry event must be one of :#{RETRY_EVENTS.keys.join ', :'}" unless RETRY_EVENTS.key?(evt) || RETRY_EVENTS.value?(evt) 925 926 evt = evt.is_a?(Symbol) ? RETRY_EVENTS[evt] : evt 927 return if evt == @retry_event 928 929 # if the event is not 'none' and attempts is <= 0, 930 # set events to 1, or the API won't accept it 931 @retry_attempts = 1 if !(evt == RETRY_EVENTS[:none]) && !@retry_attempts.positive? 932 933 @retry_event = evt 934 @need_to_update = true 935 end
Try to execute this policy on this machine.
@param show_output should the stdout and stderr of the
'jamf policy' command be sent to stdout in realtime?
@return [Boolean, nil] The success of the ‘jamf policy’ command, or nil
if the policy couldn't be executed (out of scope, policy disabled, etc)
# File lib/jamf/api/classic/api_objects/policy.rb 1904 def run(show_output = false) 1905 return nil unless enabled? 1906 1907 output = Jamf::Client.run_jamf('policy', "-id #{id}", show_output) 1908 return nil if output.include? 'No policies were found for the ID' 1909 1910 $CHILD_STATUS.exitstatus.zero? ? true : false 1911 end
@return [String] The unix shell command to run on ths client.
# File lib/jamf/api/classic/api_objects/policy.rb 1276 def run_command 1277 @files_processes[:run_command] 1278 end
Set the unix shell command to be run on the client
@param command the unix shell command to be run on the client
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1287 def run_command=(command) 1288 raise Jamf::InvalidDataError, 'Command to run must be a String' unless command.is_a? String 1289 1290 @files_processes[:run_command] = command 1291 @need_to_update = true 1292 end
@return [Array] the id’s of the scripts handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1490 def script_ids 1491 @scripts.map { |p| p[:id] } 1492 end
@return [Array] the names of the scripts handled by the policy
# File lib/jamf/api/classic/api_objects/policy.rb 1495 def script_names 1496 @scripts.map { |p| p[:name] } 1497 end
@return [Pathname] The path to search for
# File lib/jamf/api/classic/api_objects/policy.rb 1344 def search_by_path 1345 if @files_processes[:search_by_path].nil? 1346 nil 1347 else 1348 Pathname.new @files_processes[:search_by_path] 1349 end 1350 end
@return [String] The process name to search for on the client
# File lib/jamf/api/classic/api_objects/policy.rb 1314 def search_for_process 1315 @files_processes[:search_for_process] 1316 end
Set Server Side Activation
@param activation Activation date and time
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1039 def server_side_activation=(activation) 1040 raise Jamf::InvalidDataError, 'Activation must be a Time' unless activation.is_a? Time 1041 1042 @server_side_limitations[:activation] = activation 1043 @need_to_update = true 1044 end
Set Server Side Expiration
@param expiration Expiration date and time
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1052 def server_side_expiration=(expiration) 1053 raise Jamf::InvalidDataError, 'Expiration must be a Time' unless expiration.is_a? Time 1054 1055 @server_side_limitations[:expiration] = expiration 1056 @need_to_update = true 1057 end
Interact with management account settings
@param action [Key] one of the MGMT_ACCOUNT_ACTIONS
keys
@return The current specified management settings.
Reference: developer.jamf.com/documentation#resources-with-passwords
# File lib/jamf/api/classic/api_objects/policy.rb 1843 def set_management_account(action, **opts) 1844 # TODO: Add proper error handling 1845 raise Jamf::InvalidDataError, "Action must be one of: :#{MGMT_ACCOUNT_ACTIONS.keys.join ', :'}" unless MGMT_ACCOUNT_ACTIONS.include? action 1846 1847 management_data = {} 1848 1849 if %i[change_pw reset_pw].include?(action) 1850 raise Jamf::MissingDataError, ':password must be provided when changing management account password' if opts[:password].nil? 1851 1852 management_data = { 1853 action: MGMT_ACCOUNT_ACTIONS[action], 1854 managed_password: opts[:password] 1855 } 1856 elsif %i[reset_random generate_pw].include?(action) 1857 raise Jamf::MissingDataError, ':password_length must be provided when setting a random password' if opts[:password_length].nil? 1858 raise Jamf::InvalidDataError, ':password_length must be an Integer' unless opts[:password_length].is_a? Integer 1859 1860 management_data = { 1861 action: MGMT_ACCOUNT_ACTIONS[action], 1862 managed_password_length: opts[:password_length] 1863 } 1864 else 1865 management_data = { 1866 action: MGMT_ACCOUNT_ACTIONS[action] 1867 } 1868 end 1869 1870 @management_account = management_data 1871 1872 @need_to_update = true 1873 1874 @management_account 1875 end
Set a script parameter
@param identifier [Integer,String] identifier the id or name of a script in this policy
@param opts [Hash] opts the options to alter for this script
@option [String] parameter4: the value of the 4th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter5: the value of the 5th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter6: the value of the 6th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter7: the value of the 7th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter8: the value of the 8th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter9: the value of the 9th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter10: the value of the 10th parameter passed to the script. this
overrides the same parameter in the script object itself.
@option [String] parameter11: the value of the 11th parameter passed to the script. this
overrides the same parameter in the script object itself.
@return [Array] the scripts array
# File lib/jamf/api/classic/api_objects/policy.rb 1601 def set_script_parameters(identifier, **opts) 1602 id = Jamf::Script.valid_id identifier, cnx: @cnx 1603 raise Jamf::NoSuchItemError, "No script matches '#{identifier}'" unless id 1604 1605 script_data = @scripts.select { |s| s[:id] == id }[0] 1606 raise Jamf::InvalidDataError, "Script #{id} is not configured. Use add_script method." unless script_data 1607 1608 opts.each do |parameter, value| 1609 script_data[parameter] = value if SCRIPT_PARAMETERS_AVAILABLE.include? parameter 1610 end 1611 1612 @need_to_update = true 1613 @scripts 1614 end
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=”
@param path the path to search for
@param delete should the path be deleted if found
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1371 def set_search_by_path(path, delete = false) 1372 raise Jamf::InvalidDataError, 'Path to search for must be a String or a Pathname' unless path.is_a?(String) || path.is_a?(Pathname) 1373 1374 @files_processes[:search_by_path] = path.to_s 1375 @files_processes[:delete_file] = delete ? true : false 1376 @need_to_update = true 1377 end
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=”
@param process the process name to search for
@param kill should be process be killed if found
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1336 def set_search_for_process(process, kill = false) 1337 @files_processes[:search_for_process] = process.to_s 1338 @files_processes[:kill_process] = kill ? true : false 1339 @need_to_update = true 1340 end
Change a trigger event
@param type the type of trigger, one of the keys of {TRIGGER_EVENTS}
@param new_val whether the type of trigger is active or not.
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1021 def set_trigger_event(type, new_val) 1022 raise Jamf::InvalidDataError, "Trigger type must be one of #{TRIGGER_EVENTS.keys.join(', ')}" unless TRIGGER_EVENTS.key?(type) 1023 1024 if type == :custom 1025 raise Jamf::InvalidDataError, 'Custom triggers must be Strings' unless new_val.is_a? String 1026 else 1027 raise Jamf::InvalidDataError, 'Non-custom triggers must be true or false' unless Jamf::TRUE_FALSE.include? new_val 1028 end 1029 @trigger_events[TRIGGER_EVENTS[type]] = new_val 1030 @need_to_update = true 1031 end
Specify Startup Volume Only Supports “Specify Local Startup Disk”
@param startup_volume a Volume to reboot to
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1225 def specify_startup=(startup_volume) 1226 raise Jamf::InvalidDataError, "#{startup_volume} is not a valid Startup Disk" unless startup_volume.is_a? String 1227 1228 @reboot_options[:specify_startup] = startup_volume 1229 @need_to_update = true 1230 end
@return [String] The term to search for using spotlight
# File lib/jamf/api/classic/api_objects/policy.rb 1381 def spotlight_search 1382 @files_processes[:spotlight_search] 1383 end
Set the term to seach for using spotlight
@param term the term to seach for using spotlight
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1391 def spotlight_search=(term) 1392 raise Jamf::InvalidDataError, 'Spotlight search term must be a String' unless term.is_a? String 1393 1394 @files_processes[:spotlight_search] = term 1395 @need_to_update = true 1396 end
Set Startup Disk Only Supports ‘Specify Local Startup Disk’ at the moment
@param startup_disk_option
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1210 def startup_disk=(startup_disk_option) 1211 raise Jamf::InvalidDataError, "#{startup_disk_option} is not a valid Startup Disk" unless startup_disk_option.is_a? String 1212 1213 @reboot_options[:startup_disk] = 'Specify Local Startup Disk' 1214 self.specify_startup = startup_disk_option 1215 @need_to_update = true 1216 end
Set a new target drive for this policy.
@param path_to_drive the full path to the target drive, must start with a ‘/’
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 993 def target_drive=(path_to_drive) 994 raise Jamf::InvalidDataError, 'Path to target drive must be absolute' unless path_to_drive.to_s.start_with? '/' 995 996 @target_drive = path_to_drive.to_s 997 @need_to_update = true 998 end
Set whether or not to update the database used by the locate command.
@param bool [Boolean] whether or not to update the database used by the locate command.
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1307 def update_locate_database=(bool) 1308 @files_processes[:update_locate_database] = Jamf::Validate.boolean bool 1309 @need_to_update = true 1310 end
@return [Boolean] Should we update the database used by the locate command?
# File lib/jamf/api/classic/api_objects/policy.rb 1297 def update_locate_database? 1298 @files_processes[:update_locate_database] 1299 end
What to do at reboot when there is a User
Logged In
@param logged_in_option Any one of the Strings from USER_LOGGED_IN
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1156 def user_logged_in=(logged_in_option) 1157 raise Jamf::InvalidDataError, "user_logged_in options: #{USER_LOGGED_IN.join(', ')}" unless USER_LOGGED_IN.include? logged_in_option 1158 1159 @reboot_options[:user_logged_in] = logged_in_option 1160 @need_to_update = true 1161 end
Set User
Finish Message
@param user_message Text of User
Message
@return [void] description of returned object
# File lib/jamf/api/classic/api_objects/policy.rb 1194 def user_message_end=(message) 1195 raise Jamf::InvalidDataError, 'User message must be a String' unless message.is_a? String 1196 1197 @user_message_finish = message 1198 @need_to_update = true 1199 end
Set User
Start Message
@param user_message Text of User
Message
@return [void] description of returned object
# File lib/jamf/api/classic/api_objects/policy.rb 1182 def user_message_start=(message) 1183 raise Jamf::InvalidDataError, 'User message must be a String' unless message.is_a? String 1184 1185 @user_message_start = message 1186 @need_to_update = true 1187 end
@deprecated The API no longer sends SHA256 hashed password data, and instead
only has a string of asterisks, meaning we can no longer use it to validate passwords before attempting to use them. Instead, the processes that use the password will fail on their own if the pw is not valid. This method remains defined for backward-compatibility with any existing code that calls it. but it will always return true. Itwill be removed in a future version
@param password ignored
@return [TrueClass] Allow the process calling this to continue.
# File lib/jamf/api/classic/api_objects/policy.rb 1890 def verify_management_password(_password = nil) 1891 true 1892 end
see attr_reader :verify_startup_disk
# File lib/jamf/api/classic/api_objects/policy.rb 1063 def verify_startup_disk=(bool) 1064 return if @verify_startup_disk == bool 1065 1066 @verify_startup_disk = Jamf::Validate.boolean bool 1067 @need_to_update = true 1068 end
Private Instance Methods
# File lib/jamf/api/classic/api_objects/policy.rb 2089 def rest_xml 2090 doc = REXML::Document.new Jamf::Connection::XML_HEADER 2091 obj = doc.add_element RSRC_OBJECT_KEY.to_s 2092 2093 general = obj.add_element 'general' 2094 general.add_element('name').text = @name 2095 general.add_element('enabled').text = @enabled 2096 general.add_element('frequency').text = @frequency 2097 general.add_element('retry_event').text = @retry_event 2098 general.add_element('retry_attempts').text = @retry_attempts.to_s 2099 general.add_element('notify_on_each_failed_retry').text = @notify_failed_retries.to_s 2100 2101 general.add_element('target_drive').text = @target_drive 2102 general.add_element('offline').text = @offline 2103 2104 add_category_to_xml(doc) 2105 2106 JSS.hash_to_rexml_array(@trigger_events).each { |t| general << t } 2107 2108 date_time_limitations = general.add_element 'date_time_limitations' 2109 exp = @server_side_limitations[:expiration] 2110 date_time_limitations.add_element('expiration_date_epoch').text = exp.to_jss_epoch if exp 2111 activation = @server_side_limitations[:activation] 2112 date_time_limitations.add_element('activation_date_epoch').text = activation.to_jss_epoch if activation 2113 2114 # always include the scope if we have no id yet - we could be 2115 # a clone of an existing object 2116 obj << @scope.scope_xml if @scope.should_update? || @id.nil? 2117 2118 reboot = obj.add_element 'reboot' 2119 JSS.hash_to_rexml_array(@reboot_options).each { |elem| reboot << elem } 2120 2121 maint = obj.add_element 'maintenance' 2122 maint.add_element('recon').text = @recon.to_s 2123 maint.add_element('reset_name').text = @reset_name.to_s 2124 maint.add_element('install_all_cached_packages').text = @install_cached_pkgs.to_s 2125 maint.add_element('permissions').text = @permissions_repair.to_s 2126 maint.add_element('byhost').text = @fix_byhost.to_s 2127 maint.add_element('system_cache').text = @flush_system_cache.to_s 2128 maint.add_element('user_cache').text = @user_cache.to_s 2129 maint.add_element('verify').text = @verify_startup_disk.to_s 2130 2131 acct_maint = obj.add_element 'account_maintenance' 2132 2133 mgmt_acct = acct_maint.add_element 'management_account' 2134 JSS.hash_to_rexml_array(@management_account).each { |x| mgmt_acct << x } 2135 2136 directory_bindings = acct_maint.add_element 'directory_bindings' 2137 @directory_bindings.each do |b| 2138 directory_binding = directory_bindings.add_element 'binding' 2139 dbdeets = JSS.hash_to_rexml_array b 2140 dbdeets.each { |d| directory_binding << d } 2141 end 2142 2143 user_interaction = obj.add_element 'user_interaction' 2144 user_interaction.add_element('message_start').text = @user_message_start.to_s 2145 user_interaction.add_element('message_finish').text = @user_message_finish.to_s 2146 2147 files_processes = obj.add_element 'files_processes' 2148 JSS.hash_to_rexml_array(@files_processes).each { |f| files_processes << f } 2149 2150 pkg_conf = obj.add_element 'package_configuration' 2151 pkgs = pkg_conf.add_element 'packages' 2152 @packages.each do |p| 2153 pkg = pkgs.add_element 'package' 2154 pdeets = JSS.hash_to_rexml_array p 2155 pdeets.each { |d| pkg << d } 2156 end 2157 2158 scripts = obj.add_element 'scripts' 2159 @scripts.each do |s| 2160 script = scripts.add_element 'script' 2161 sdeets = JSS.hash_to_rexml_array s 2162 sdeets.each { |d| script << d } 2163 end 2164 2165 disk_encryption = obj.add_element 'disk_encryption' 2166 2167 @disk_encryption.each do |k, v| 2168 disk_encryption.add_element(k.to_s).text = v.to_s 2169 end 2170 2171 printers = obj.add_element 'printers' 2172 @printers.each do |pr| 2173 printer = printers.add_element 'printer' 2174 pdeets = JSS.hash_to_rexml_array pr 2175 pdeets.each { |d| printer << d } 2176 end 2177 2178 dock_items = obj.add_element 'dock_items' 2179 @dock_items.each do |d| 2180 dock_item = dock_items.add_element 'dock_item' 2181 ddeets = JSS.hash_to_rexml_array d 2182 ddeets.each { |de| dock_item << de } 2183 end 2184 2185 add_self_service_xml doc 2186 add_site_to_xml doc 2187 2188 doc.to_s 2189 end
raise an error if the directory binding being added isn’t valid
@return [Integer, nil] the valid id for the package
# File lib/jamf/api/classic/api_objects/policy.rb 2033 def validate_directory_binding_opts(identifier, opts) 2034 opts[:position] ||= -1 2035 2036 opts[:position] = 2037 case opts[:position] 2038 when :start then 0 2039 when :end then -1 2040 else Jamf::Validate.integer(opts[:position]) 2041 end 2042 2043 # if the given position is past the end, set it to -1 (the end) 2044 opts[:position] = -1 if opts[:position] > @directory_bindings.size 2045 2046 id = Jamf::DirectoryBinding.valid_id identifier, cnx: @cnx 2047 raise Jamf::NoSuchItemError, "No directory binding matches '#{identifier}'" unless id 2048 2049 id 2050 end
raise an error if a package being added isn’t valid
@see add_package
@return [Integer, nil] the valid id for the package
# File lib/jamf/api/classic/api_objects/policy.rb 1968 def validate_package_opts(identifier, opts) 1969 opts[:position] ||= -1 1970 opts[:action] ||= :install 1971 opts[:feu] ||= false 1972 opts[:fut] ||= false 1973 opts[:update_autorun] ||= false 1974 1975 opts[:position] = 1976 case opts[:position] 1977 when :start then 0 1978 when :end then -1 1979 else Jamf::Validate.integer(opts[:position]) 1980 end 1981 1982 # if the given position is past the end, set it to -1 (the end) 1983 opts[:position] = -1 if opts[:position] > @packages.size 1984 1985 id = Jamf::Package.valid_id identifier, cnx: @cnx 1986 1987 raise Jamf::NoSuchItemError, "No package matches '#{identifier}'" unless id 1988 1989 raise Jamf::InvalidDataError, "action must be one of: :#{PACKAGE_ACTIONS.keys.join ', :'}" unless \ 1990 PACKAGE_ACTIONS.include? opts[:action] 1991 1992 opts[:feu] = Jamf::Validate.boolean opts[:feu] 1993 opts[:fut] = Jamf::Validate.boolean opts[:fut] 1994 opts[:update_autorun] = Jamf::Validate.boolean opts[:update_autorun] 1995 id 1996 end
Raises an error if the printer being added isn’t valid, additionally checks the options and sets defaults where possible.
@see add_printer
@return [Integer, nil] the valid id for the package
# File lib/jamf/api/classic/api_objects/policy.rb 2058 def validate_printer_opts(identifier, opts) 2059 opts[:position] ||= -1 2060 2061 opts[:position] = 2062 case opts[:position] 2063 when :start then 0 2064 when :end then -1 2065 else Jamf::Validate.integer(opts[:position]) 2066 end 2067 2068 # If the given position is past the end, set it to -1 (the end) 2069 opts[:position] = -1 if opts[:position] > @printers.size 2070 2071 # Checks if action to be done with the printer object is provided and valid. 2072 raise Jamf::MissingDataError, "action must be provided, must be one of :#{PRINTER_ACTIONS.keys.join(':,')}." if opts[:action].nil? 2073 raise Jamf::InvalidDataError, "action must be one of :#{PRINTER_ACTIONS.keys.join(',:')}." unless PRINTER_ACTIONS.keys.include? opts[:action] 2074 2075 # Checks if the make_default option is valid, and sets the default if needed. 2076 unless opts[:make_default].is_a?(TrueClass) || opts[:make_default].is_a?(FalseClass) || opts[:make_default].nil? 2077 raise Jamf::InvalidDataError, 2078 'make_default must be either true or false.' 2079 end 2080 2081 opts[:make_default] = false if opts[:make_default].nil? 2082 2083 id = Jamf::Printer.valid_id identifier, cnx: @cnx 2084 raise Jamf::NoSuchItemError, "No printer matches '#{identifier}'" unless id 2085 2086 id 2087 end
raise an error if a trying to set retry options when frequency is not ‘once per comptuer’
@return [void]
# File lib/jamf/api/classic/api_objects/policy.rb 1956 def validate_retry_opt 1957 return if FREQUENCIES[:once_per_computer] == @frequency 1958 1959 raise Jamf::UnsupportedError, 'Policy retry is only available when frequency is set to :once_per_computer' 1960 end
raise an error if a script being added isn’t valid
@see add_script
@return [Integer, nil] the valid id for the package
# File lib/jamf/api/classic/api_objects/policy.rb 2004 def validate_script_opts(identifier, opts) 2005 opts[:position] ||= -1 2006 opts[:priority] ||= :after 2007 2008 raise Jamf::InvalidDataError, "priority must be one of: :#{SCRIPT_PRIORITIES.keys.join ', :'}" unless \ 2009 SCRIPT_PRIORITIES.include? opts[:priority] 2010 2011 opts[:position] = 2012 case opts[:position] 2013 when :start then 0 2014 when :end then -1 2015 else Jamf::Validate.integer(opts[:position]) 2016 end 2017 2018 # if the given position is past the end, set it to -1 (the end) 2019 opts[:position] = -1 if opts[:position] > @packages.size 2020 2021 id = Jamf::Script.valid_id identifier, cnx: @cnx 2022 raise Jamf::NoSuchItemError, "No script matches '#{identifier}'" unless id 2023 2024 id 2025 end