2023 demo D Listing Objects

Hands On, Real-time Jamf APIs Using ruby-jss

Listing Objects

Previous           TOC           Next

---

Realtime Tasks

• Now that we're connected, we'll do some real-time tasks with our JSS

• These tasks are contrived, but will give you an idea of the possibilities

• As we go, we'll take some tangents, looking a little more deeply into ruby & ruby-jss

• I do these kinds of one-off tasks frequently in my day-to-day work

Simple Lists of Static and Smart Computer Groups

• The API provides 'summary-lists' of objects in Jamf Pro

  • These lists give you a little bit of identifying info about all of the objects on the server

• ruby-jss gives you access to these summary-lists like this

Jamf::ComputerGroup.all.sample
# [a hash of info about a group]
# => 0

• Lets talk just a moment about ruby itself by looking at that line bit by bit

• As mentioned before Jamf is the module that holds all of ruby-jss

• The double-colon is a separator between modules & classes and their contents, like the slashes of a file path

• ComputerGroup is a 'class' defined in the Jamf module

  • A 'class' in ruby is a 'kind of thing' - in this case, it represent Computer Groups in Jamf Pro
  • Most of the classes in ruby-jss represent kinds of objects in Jamf Pro

• Those classes have a method called 'all'

  • A 'method' is like a function, a command that you send to an object, usually with a dot between the object and the method
  • Some methods perform actions, all methods return a value of some kind

• The 'all' method returns an array of hashes

  • An 'array' is a collection of things in a given order, like a list
    • You access things in the array by their numeric position in the list
  • A 'hash' is a collection of things that are labeled, a group of key-value pairs
    • You access things in the hash by their label, or 'key'
    • In other languages these are called 'dictionaries', 'records', 'associative arrays', 'maps', or 'objects'

• In ruby, arrays have a method called 'sample' which returns a random item from the array

• So what we see from the above is a hash, randomly chosen from the array of hashes we got from ComputerGroup.all

• As you can see this hash has three things in it, the keys are :id, :name, and :is_smart

  • ids are integers, the same one seen in the URL for the objects page in Jamf Pro
  • names are strings
  • is_smart is boolean true or false

---

• To see the whole array, try this

pp Jamf::ComputerGroup.all ;0
# [ Array of Hashes ]
# => 0

• The pp (prettyprint) at the beginning and the ;0 at the end make it easier to read in irb.
  • In a script, you wouldn't use them

---

• Almost always when you have an array, you'll want to loop through it and do something with the items in it

• While ruby has 'for loops' like most languages, it has easier ways to loop through arrays

• The simplest is the each method

Jamf::ComputerGroup.all.each { |grp_data| puts grp_data[:name] } ;0
# [output of names]
# => 0

• each is an 'iterator' method, it loops through ('iterates over') the items in a collection

  • Each time thru, the next item is put into a temporary variable
  • That variable is used in the block of code you provide

• The block of code we're using is in the curly-braces:

  • { |grp_data| puts grp_data[:name] }

• Between the vertical lines we put the name of the temporary variable we can use inside the block

  • Here, the variable grp_data will hold each hash as we loop thru the array of hashes

• puts is the same as echo in bash, it prints something to standard output followed by a newline character

---

• Now lets be more selective and print out just the static groups, and their ids

Jamf::ComputerGroup.all.each do |grp_data|
  next if grp_data[:is_smart]
  puts "Static Group Name: #{grp_data[:name]}, ID:  #{grp_data[:id]}"
end ;0
# [output of names embedded in strings]
# => 0

• This time the code block that we're passing to each has two lines to execute

  • So instead of curly braces, we use do and end

• Inside our code block, the first line looks at the :is_smart key of the current hash

  • If it's true, next will just skip to the next hash, and nothing is printed

• The second line prints a string containing the group name

  • Note how embedding stuff into strings is similar to bash
    • This happens when the string is double-quoted
    • The embedded value is inside #{}

---

• While that's a totally valid way to do that, ruby-jss has some built-in shortcuts

• Let's list the smart groups:

Jamf::ComputerGroup.all_smart.each { |grp_data| puts grp_data[:name] } ;0
# [lines of output]
# => 0

• The group classes in ruby-jss have shortcut methods all_smart and all_static, which filter the array you get from all

• Other classes have other shortcuts that filter it in different ways

  • For example Jamf::Computer and Jamf::MobileDevice have methods like all_managed, all_laptops, all_ipads

• There are also methods that give you simpler arrays of single values, not entire hashes, like all_ids, and all_names

  • Some classes have others, e.g. all_serial_numbers, all_mac_addresses and so on

---

• Let's have a look:

Jamf::MobileDevice.all_supervised.each { |md| puts md[:serial_number] } ;0
# [array of SNs]
# => 0

pp Jamf::MobileDevice.all_wifi_mac_addresses ;0
# [array of macaddrs]
# => 0

pp Jamf::DistributionPoint.all_names ;0
# [array of names]
# => 0

• These methods are really just manipulating the same array of hashes that you get from all

• If you call one of these list methods more than once, the first time is slow, others are fast

• The all method caches the data in RAM the first time its used on a class

• To refresh the cache and re-read the data from the API, just pass in the :refresh parameter

• Here's a list we just looked at:

  • When we run it again, its fast, because it's using cached data
  • When we provide :refresh, its slower, because it re-reading the data from the API

pp Jamf::MobileDevice.all_wifi_mac_addresses  ;0
# [array of macaddrs appears quickly, from cache]
# => 0

pp Jamf::MobileDevice.all_wifi_mac_addresses :refresh  ;0
# [array of macaddrs is looked up again and re-cached]
# => 0

---

Previous           TOC           Next