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:

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

accounts[R]

@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

client_side_limitations[R]

@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

directory_bindings[R]

@return [Array<Hash>]

The directory bindings applied

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

disk_encryption[R]

@return [Hash]

Disk encryption options for this policy

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

dock_items[R]

@return [Array<Hash>]

The dock items handled by this policy

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

enabled[R]

@return [Boolean] is the policy enabled?

enabled?[R]

@return [Boolean] is the policy enabled?

fix_byhost[R]

Should this policy fix the ByHost prefs? @return [Boolean] client maintenance task

flush_system_cache[R]

Should this policy flush the system cache? @return [Boolean] client maintenance task

flush_user_cache[R]

Should this policy flush the user cache? @return [Boolean] client maintenance task

frequency[R]

@return [String] how often to run the policy on each computer

install_cached_pkgs[R]

Should this policy install any cached JSS packages? @return [Boolean] client maintenance task

management_account[R]

@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

offline[R]

@return [Boolean] should be policy be available offline

open_firmware_efi_password[R]

@return [Hash] the open firmware mode and password

override_default_settings[R]

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

packages[R]

@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

permissions_repair[R]

Should this policy run a permission repair? @return [Boolean] client maintenance task

pkgs[R]

@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

printers[R]

@return [Array<Hash>]

The printers handled by this policy

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

reboot_options[R]

@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

recon[R]

Should this policy run a recon? @return [Boolean] client maintenance task

reset_name[R]

Should this policy reset the local hostname? @return [Boolean] client maintenance task

scripts[R]

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

server_side_limitations[R]

@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

site[R]

@return [String] a string with the site name

target_drive[R]

@return [String] which drive should the policy target

trigger[R]

@return [String]

Either EVENT or USER_INITIATED

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

trigger_events[R]

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

update_inventory[R]

Should this policy run a recon? @return [Boolean] client maintenance task

user_may_defer[R]

@return [Boolean] can the user defer the policy?

user_may_defer_until[R]

@return [Time] when is the user no longer allowed to defer?

user_message_end[R]

@return [String] the message shown the user at policy end

user_message_finish[R]

@return [String] the message shown the user at policy end

user_message_start[R]

@return [String] the message shown the user at policy start

verify_startup_disk[R]

Should this policy verify the startup disk? @return [Boolean] client maintenance task

Public Class Methods

flush_logs(policy, older_than: 0, period: :days, api: nil, cnx: Jamf.cnx) click to toggle source

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_logs_for_computers(computers = [], older_than: 0, period: :days, api: nil, cnx: Jamf.cnx) click to toggle source

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
new(**args) click to toggle source

@see APIObject#initialize

Calls superclass method 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_log_flush_params(older_than, period) click to toggle source

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_directory_binding(identifier, **opts) click to toggle source

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_dock_item(identifier, action) click to toggle source

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_package(identifier, **opts) click to toggle source

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_printer(identifier, **opts) click to toggle source

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_script(identifier, **opts) click to toggle source

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
apply_encryption_configuration(identifier) click to toggle source

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
command_to_run()
Alias for: run_command
command_to_run=(command)
Alias for: run_command=
delete_file?() click to toggle source

@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
Also aliased as: delete_path?
delete_path?()
Alias for: delete_file?
directory_binding_ids() click to toggle source

@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
directory_binding_names() click to toggle source

@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
disable() click to toggle source

Shortcut for endabled = false

    # File lib/jamf/api/classic/api_objects/policy.rb
888 def disable
889   self.enabled = false
890 end
do_not_reboot() click to toggle source

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
dock_item_ids() click to toggle source

@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
dock_item_names() click to toggle source

@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
enable() click to toggle source

Shortcut for enabled = true

    # File lib/jamf/api/classic/api_objects/policy.rb
883 def enable
884   self.enabled = true
885 end
enabled=(new_val) click to toggle source

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
execute(show_output = false)
Alias for: run
file_vault_2_reboot=(fv_bool) click to toggle source

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
fix_byhost=(bool) click to toggle source

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(older_than: 0, period: :days) click to toggle source

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
flush_system_cache=(bool) click to toggle source

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
flush_user_cache=(bool) click to toggle source

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
frequency=(freq) click to toggle source

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
install_cached_pkgs=(bool) click to toggle source

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
kill_process?() click to toggle source

@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
locate_file() click to toggle source

@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
locate_file=(term) click to toggle source

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
message=(message)
Alias for: reboot_message=
minutes_until_reboot=(minutes) click to toggle source

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
no_user_logged_in=(no_user_option) click to toggle source

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
notify_failed_retries()
notify_failed_retries=(bool) click to toggle source

@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
notify_failed_retries?() click to toggle source

@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
notify_on_each_failed_retry()
offline=(new_val) click to toggle source

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
package_ids() click to toggle source

@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
package_names() click to toggle source

@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
permissions_repair=(bool) click to toggle source

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
printer_ids() click to toggle source

@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
printer_names() click to toggle source

@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
reboot_message=(message) click to toggle source

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
Also aliased as: message=
recon=(bool) click to toggle source

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
Also aliased as: update_inventory=
reissue_key() click to toggle source

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_directory_binding(identifier) click to toggle source

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_dock_item(identifier) click to toggle source

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
remove_encryption_configuration() click to toggle source

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_package(identifier) click to toggle source

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_printer(identifier) click to toggle source

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_script(identifier) click to toggle source

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
reset_name=(bool) click to toggle source

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
retry_attempts() click to toggle source

@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
retry_attempts=(int) click to toggle source

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
retry_event() click to toggle source

@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
retry_event=(evt) click to toggle source

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
run(show_output = false) click to toggle source

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
Also aliased as: execute
run_command() click to toggle source

@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
Also aliased as: command_to_run
run_command=(command) click to toggle source

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
Also aliased as: command_to_run=
script_ids() click to toggle source

@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
script_names() click to toggle source

@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
search_by_path() click to toggle source

@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
search_for_process() click to toggle source

@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
server_side_activation=(activation) click to toggle source

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
server_side_expiration=(expiration) click to toggle source

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
set_management_account(action, **opts) click to toggle source

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_script_parameters(identifier, **opts) click to toggle source

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_search_by_path(path, delete = false) click to toggle source

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_search_for_process(process, kill = false) click to toggle source

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
set_trigger_event(type, new_val) click to toggle source

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=(startup_volume) click to toggle source

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
spotlight_search=(term) click to toggle source

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
startup_disk=(startup_disk_option) click to toggle source

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
target_drive=(path_to_drive) click to toggle source

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
update_inventory=(bool)
Alias for: recon=
update_locate_database=(bool) click to toggle source

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
update_locate_database?() click to toggle source

@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
user_logged_in=(logged_in_option) click to toggle source

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
user_message_end=(message) click to toggle source

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
Also aliased as: user_message_finish=
user_message_finish=(message)
Alias for: user_message_end=
user_message_start=(message) click to toggle source

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
verify_management_password(_password = nil) click to toggle source

@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
verify_startup_disk=(bool) click to toggle source

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

rest_xml() click to toggle source
     # 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
validate_directory_binding_opts(identifier, opts) click to toggle source

raise an error if the directory binding being added isn’t valid

@see add_directory_binding

@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
validate_package_opts(identifier, opts) click to toggle source

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
validate_printer_opts(identifier, opts) click to toggle source

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
validate_retry_opt() click to toggle source

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
validate_script_opts(identifier, opts) click to toggle source

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