module Jamf::ChangeLog
a mix-in module for Jamf::Resource subclasses.
Many Jamf
resources maintain an ‘object history’, available in the WebUI via the ‘History’ button at the bottom of a page. Ad-hoc history entries can be added containing textual notes, which is useful for objects that don’t have a real ‘notes’ or ‘description’ field, like policies.
In the Jamf
Pro API, this history is usually available at a resource path ending with ‘/history’ (see NON-STANDARD ‘history’ Paths below)
Due to the many kinds of history available in Jamf
, like management history, application usage history, and so on, ruby-jss uses the term ‘change log’ to refer to a Jamf
resource’s ‘object history’, and access to the change log is provided by this module.
The change log can be available in different places:
-
CollectionResource
Items (e.g. individual Scripts) -
CollectionResources as a whole (e.g. Inventory Preload Records)
-
SingletonResources (e.g.
Client
Checkin Settings )
To enable change log access in a class, incldude this module after including Jamf::CollectionResource
or Jamf::SingletonResource
##### NON-STANDARD ‘history’ Paths
For most classes, the change log path is the LIST_PATH or the get_path with ‘/history’ appended. LIST_PATH/history is for when the history is available for the class as a whole, e.g. with SingletonResources, and get_path/history is for members of a collection, and will include the item’s id.
This path can be used for GETting history and POSTing new notes to the history.
If some class or instance has a non-standard path, it should override the history_path
class & instance methods defined here, to return the correct path.
As an example, see Jamf::InventoryPreloadRecord
, which is a Collection, but only has history available for the collection as a whole, not for its items, but also, the path for accessing the history is ‘v2/inventory-preload/history’ while the LIST_PATH is ‘v2/inventory-preload/records’
This module will add these public methods:
1) #change_log, will fetch an Array of readonly Jamf::ChangeLogEntry instances. possibly sorted, filtered, paged, or cached 2) #next_page_of_change_log, will retrieve the next page of a paged #change_log call 3) #add_change_log_note(note), which takes a string and adds it to the object's change history as a note and clears the cached the logs.
Constants
- DFT_HISTORY_PATH
- HISTORY_ENTRY_OBJECT
- POST_NOTE_OBJECT
- SEARCH_RESULTS_OBJECT
Public Class Methods
when this module is included, also extend our Class Methods
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 93 def self.included(includer) 94 Jamf.load_msg "--> #{includer} is including Jamf::ChangeLog" 95 includer.extend(ClassMethods) 96 end
Public Instance Methods
Instance Methods
wrappers for the class methods, which pass the id and cnx should work on Singleton Resources since @id will be nil but @cnx will be set.
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 218 def add_change_log_note(note) 219 self.class.add_change_log_note(note, id: @id, cnx: @cnx) 220 end
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 222 def change_log(sort: nil, filter: nil) 223 self.class.change_log(id: @id, sort: sort, filter: filter, cnx: @cnx) 224 end
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 236 def change_log_count 237 self.class.change_log_count(id: @id, cnx: @cnx) 238 end
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 226 def change_log_pager(page_size: Jamf::Pager::DEFAULT_PAGE_SIZE, sort: nil, filter: nil) 227 self.class.change_log_pager( 228 page_size: page_size, 229 id: @id, 230 sort: sort, 231 filter: filter, 232 cnx: @cnx 233 ) 234 end
# File lib/jamf/api/jamf_pro/mixins/change_log.rb 240 def history_path 241 self.class.history_path(@id) 242 end