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

app_store_country_code(country, msg: nil) click to toggle source

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
doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx) click to toggle source

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
email_address(email, msg: nil) click to toggle source

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
ibeacon_major_minor(val, msg: nil) click to toggle source

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
ip_address(val, msg: nil) click to toggle source

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
j_id(val, attr_name: nil, msg: nil) click to toggle source

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
mac_address(val, msg: nil) click to toggle source

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
non_empty_string(val, attr_name: nil, msg: nil) click to toggle source

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

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
uuid(val, msg: nil) click to toggle source

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