module Jamf::Validate
A collection of methods for validating values.
Some of these methods can take multiple input types, such as a String
or an Array
. All of them will either raise an exception if the value isn’t valid, or will return a standardized form of the input (e.g. an Array
, even if given a String
)
Constants
- IPV4_ADDR_RE
The Regexp that matches a valid IPv4 address
- MAC_ADDR_RE
The regular expression that matches a valid MAC address.
- UUID_RE
the regular expression that matches a valid UDID/UUID
Public Class Methods
validate a country name or code from Jamf::APP_STORE_COUNTRY_CODES returning the validated code, or raising an error
@param country The country name or code
@param msg A custom error message when the value is invalid
@return [String] the valid two-letter country code
# File lib/jamf/validate.rb 192 def self.app_store_country_code(country, msg: nil) 193 country = country.to_s.upcase 194 return country if Jamf::APP_STORE_COUNTRY_CODES.value? country 195 196 Jamf::APP_STORE_COUNTRY_CODES.each do |name, code| 197 return code if name.upcase == country 198 end 199 200 raise_invalid_data_error(msg || "Unknown country name or code '#{country}'. See Jamf::APP_STORE_COUNTRY_CODES or JSS.country_code_match(str)") 201 end
Validate
that a value doesn’t already exist for a given identifier of a given class
e.g. when klass = Jamf::Computer
, identifier = :name, and val = ‘foo’ will raise an error when a computer named ‘foo’ exists
Otherwise returns val.
@param klass A subclass of Jamf::APIObject
, e.g. Jamf::Computer
@param identifier One of the keys of an Item of the class’s all Array
@param val The value to check for uniqueness
@param msg A custom error message when the value is invalid
@param cnx [Jamf::Connection] The api connection to use for validation
@return [Object] the validated unique value
# File lib/jamf/validate.rb 101 def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx) 102 cnx = api if api 103 104 return val unless klass.all(:refresh, cnx: cnx).map { |i| i[identifier] }.include? val 105 106 key = klass.real_lookup_key identifier 107 108 # use map_all_ids_to cuz it works with any identifer, even non-existing 109 existing_values = klass.map_all_ids_to(key, cnx: cnx).values 110 matches = existing_values.select { |existing_val| existing_val.casecmp? val } 111 return val if matches.empty? 112 113 raise_invalid_data_error(msg || "A #{klass} already exists with #{identifier} '#{val}'") 114 end
validate an email address - must match the RegEx /^S+@S+.S+$/ i.e.:
1 or more non-whitespace chars, followed by an @ character, followed by 1 or more non-whitespace chars, followed by a dot, followed by 1 or more non-whitespace chars
@param email The email address
@param msg A custom error message when the value is invalid
@return [String] the validly formatted email address
# File lib/jamf/validate.rb 217 def self.email_address(email, msg: nil) 218 email = email.to_s 219 return email if email =~ /^\S+@\S+\.\S+$/ 220 221 raise_invalid_data_error(msg || "'#{email}' is not formatted as a valid email address") 222 end
validate that the given value is an integer in the Jamf::IBeacon::MAJOR_MINOR_RANGE
@param val [Object] the thing to validate
@param msg A custom error message when the value is invalid
@return [String] the valid integer
# File lib/jamf/validate.rb 174 def self.ibeacon_major_minor(val, msg: nil) 175 val = val.to_i if val.is_a?(String) && val.jss_integer? 176 ok = val.is_a? Integer 177 ok = Jamf::IBeacon::MAJOR_MINOR_RANGE.include? val if ok 178 return val if ok 179 180 raise_invalid_data_error(msg || "value must be an integer in the range #{Jamf::IBeacon::MAJOR_MINOR_RANGE}") 181 end
Validate
the format and content of an IPv4 address
@param val The value to validate
@param msg A custom error message when the value is invalid
@return [String] The valid value
# File lib/jamf/validate.rb 74 def self.ip_address(val, msg: nil) 75 val = val.strip 76 return val if val =~ IPV4_ADDR_RE 77 78 raise_invalid_data_error(msg || "Not a valid IPv4 address: '#{val}'") 79 end
Confirm that a value provided is an integer or a string version of an integer, and return the string version
The JPAPI specs say that all IDs are integers in strings tho, some endpoints are still using actual integers.
@param val the value to validate
@param msg A custom error message when the value is invalid
@return [String] the valid integer-in-a-string
# File lib/jamf/validate.rb 142 def self.j_id(val, attr_name: nil, msg: nil) 143 case val 144 when Integer 145 return val.to_s 146 when String 147 return val if val.j_integer? 148 end 149 raise_invalid_data_error(msg || "#{attr_name} value must be an Integer or an Integer in a String, e.g. \"42\"") 150 end
Validate
the format and content of a MAC address
@param val The value to validate
@param msg A custom error message when the value is invalid
@return [String] The valid value
# File lib/jamf/validate.rb 60 def self.mac_address(val, msg: nil) 61 return val if val =~ MAC_ADDR_RE 62 63 raise_invalid_data_error(msg || "Not a valid MAC address: '#{val}'") 64 end
validate that the given value is a non-empty string
@param val [Object] the thing to validate
@param msg A custom error message when the value is invalid
@return [String] the valid non-empty string
# File lib/jamf/validate.rb 124 def self.non_empty_string(val, attr_name: nil, msg: nil) 125 return val if val.is_a?(String) && !val.empty? 126 127 raise_invalid_data_error(msg || "#{attr_name} value must be a non-empty String") 128 end
Raise an invalid data error
# File lib/jamf/validate.rb 37 def self.raise_invalid_data_error(msg) 38 raise Jamf::InvalidDataError, msg.strip 39 end
validate that the given value is a valid uuid string
@param val [Object] the thing to validate
@param msg A custom error message when the value is invalid
@return [String] the valid uuid string
# File lib/jamf/validate.rb 160 def self.uuid(val, msg: nil) 161 return val if val.is_a?(String) && val =~ UUID_RE 162 163 raise_invalid_data_error(msg || 'value must be valid uuid') 164 end