Method: Jamf::APIObject.fetch

Defined in:: lib/jamf/api/classic/base_classes/api_object.rb

.fetch(searchterm = nil, **args) ⇒ `APIObject`

Retrieve an object from the API and return an instance of this APIObject subclass.

Fetching is faster when specifying a lookup key, and that key has a fetch_rsrc_key defined in its OTHER_LOOKUP_KEYS constant, as in the second example above.

When no lookup key is given, as in the first example above, or when that key doesn’t have a defined fetch_rsrc_key, ruby-jss uses the currently cached list resource data to find the id matching the value given, and that id is used to fetch the object. (see ‘List Resources and Lookup Keys’ in the APIObject comments/docs above)

Since that cached list data may be out of date, you can provide the param ‘refrsh: true`, to reload the list from the server. This will cause the fetch to be slower still, so use with caution.

For creating new objects in the JSS, use make

Examples:

# computer where 'xyxyxyxy'  is in any of the lookup key fields
Jamf::Computer.fetch 'xyxyxyxy'

# computer where 'xyxyxyxy' is the serial number
Jamf::Computer.fetch serial_number: 'xyxyxyxy'

Parameters:

searchterm (String, Integer) (defaults to: nil) —

An single value to search for in all the lookup keys for this clsss. This is slower than specifying a lookup key
args (Hash) —

the remaining options for fetching an object. If no searchterm is provided, one of the args must be a valid lookup key and value to find in that key, e.g. ‘serial_number: ’1234567’‘

Options Hash (**args):

cnx (Jamf::Connection) —

an API connection to use for the query. Defaults to the corrently active API. See Connection
refresh (Boolean) —

should the summary list of all objects be reloaded from the API before being used to look for this object.

Returns:

(APIObject) —

The ruby-instance of a JSS object

# File 'lib/jamf/api/classic/base_classes/api_object.rb', line 961

def self.fetch(searchterm = nil, **args)
  validate_not_metaclass(self)

  # which connection?
  cnx = args.delete :cnx
  cnx ||= args.delete :api # backward compatibility, deprecated
  cnx ||= Jamf.cnx

  # refresh the .all list if needed
  if args.delete(:refresh) || searchterm == :random
    all(:refresh, cnx: cnx)
    just_refreshed = true
  else
    just_refreshed = false
  end

  # a random object?
  if searchterm == :random || args[:random]
    rnd_thing = all(cnx: cnx).sample
    raise Jamf::NoSuchItemError, "No #{self::RSRC_LIST_KEY} found" unless rnd_thing

    return new id: rnd_thing[:id], cnx: cnx
  end

  # get the lookup key and value, if given
  fetch_key, fetch_val = args.to_a.first
  fetch_rsrc_key = fetch_rsrc_key(fetch_key)

  # names should raise an error if more than one exists,
  # so we always have to do id_for_identifier, which will do so.
  if fetch_rsrc_key == :name
    id = id_for_identifier fetch_key, fetch_val, !just_refreshed, cnx: cnx
    fetch_rsrc = id ? "#{self::RSRC_BASE}/name/#{CGI.escape fetch_val.to_s}" : nil

  # if the fetch rsrc key exists, it can be used directly in an endpoint path
  # so, use it directly, rather than looking up the id first.
  elsif fetch_rsrc_key
    fetch_rsrc = "#{self::RSRC_BASE}/#{fetch_rsrc_key}/#{CGI.escape fetch_val.to_s}"

  # it has an OTHER_LOOKUP_KEY but that key doesn't have a fetch_rsrc
  # so we look in the .map_all_ids_to_* hash for it.
  elsif fetch_key
    id = id_for_identifier fetch_key, fetch_val, !just_refreshed, cnx: cnx
    fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil

  # no fetch key was given in the args, so try a search term
  elsif searchterm
    id = valid_id searchterm, cnx: cnx
    fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil

  else
    raise ArgumentError, 'Missing searchterm or fetch key'
  end

  new fetch_rsrc: fetch_rsrc, cnx: cnx
end

Method: Jamf::APIObject.fetch

.fetch(searchterm = nil, **args) ⇒ APIObject

Examples:

.fetch(searchterm = nil, **args) ⇒ `APIObject`