Module: Jamf::ChangeLog
- Included in:
- Building, Category, Department, DeviceEnrollment, InventoryPreloadRecord, MobileDevicePrestage, Script
- Defined in:
- lib/jamf/api/mixins/change_log.rb
Overview
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:
-
instances of a CollectionResources (e.g. individual policies)
-
mix-in this module by including it, to get instance methods
-
-
CollectionResources as a whole (e.g. Inventory Preload Records)
-
mix-in this module by extending it, to get class methods
-
-
SingletonResources (e.g. Client Checkin Settings )
-
mix-in this module by including AND extending, to get both
-
##### NON-STANDARD 'history' Paths For most classes, the change log path is the #rsrc_path with '/history' appended, and in that case it will be determined automatically. If the object has some other path for the change log, e.g. InventoryPreloadRecord, the class can define a constant CHANGE_LOG_RSRC with the non-standard path. If that constant is defined, it will be used.
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.
Instance Method Summary collapse
-
#add_change_log_note(note, cnx: Jamf.cnx) ⇒ void
Add a note to this resource's change log.
-
#change_log(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::ChangeLogEntry>
The change and note history for this resource.
-
#change_log_count(cnx: Jamf.cnx) ⇒ Integer
how many change log entries are there? needed when using paged #change_log calls.
-
#next_page_of_change_log ⇒ Array<Jamf::ChangeHistoryEntry>
Fetch the next page of a paged #change_log request Returns an empty array if there's been no paged request or if the last one has no more pages.
Instance Method Details
#add_change_log_note(note, cnx: Jamf.cnx) ⇒ void
This method returns an undefined value.
Add a note to this resource's change log.
If the change history has been cached already, the cache is flushed after adding the note.
83 84 85 86 87 88 89 90 91 92 93 |
# File 'lib/jamf/api/mixins/change_log.rb', line 83 def add_change_log_note(note, cnx: Jamf.cnx) # this should only be true for instances of CollectionResources cnx = @cnx if @cnx note = Jamf::Validate.non_empty_string note note_to_send = { note: note } cnx.post change_log_rsrc, note_to_send # flush the cached data, force reload when next accessed, to get new note @change_log = nil end |
#change_log(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, cnx: Jamf.cnx) ⇒ Array<Jamf::ChangeLogEntry>
The change and note history for this resource. This is a collection of objects as a sub-resource of some primary resource. As such, retriving the change log returns an array of objects, and can be paged, sorted and filtered.
This method is very similar to CollectionResource.all, see the docs for that method for more details
successive page.
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 |
# File 'lib/jamf/api/mixins/change_log.rb', line 129 def change_log(sort: nil, filter: nil, paged: nil, page_size: nil, refresh: false, cnx: Jamf.cnx) # this should only be true for instances of CollectionResources cnx = @cnx if @cnx # use the cache if not paging, filtering or sorting return cached_change_log(refresh, cnx) if !paged && !sort && !filter sort = parse_change_log_sort(sort) filter &&= "&filter=#{CGI.escape filter.to_s}" return first_change_log_page(page_size, sort, filter, cnx) if paged fetch_all_change_log_entries(sort, filter, cnx) end |
#change_log_count(cnx: Jamf.cnx) ⇒ Integer
how many change log entries are there? needed when using paged #change_log calls
186 187 188 189 |
# File 'lib/jamf/api/mixins/change_log.rb', line 186 def change_log_count(cnx: Jamf.cnx) cnx = @cnx if @cnx cnx.get("#{change_log_rsrc}?page=0&page-size=1")[:totalCount] end |
#next_page_of_change_log ⇒ Array<Jamf::ChangeHistoryEntry>
Fetch the next page of a paged #change_log request Returns an empty array if there's been no paged request or if the last one has no more pages.
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 |
# File 'lib/jamf/api/mixins/change_log.rb', line 152 def next_page_of_change_log case @change_log_page when :first @change_log_page = 0 when Integer @change_log_page += 1 else # if here, we haven't initiated a paged request, or # all pages have already been delivered return [] end raw = @change_log_paged_cnx.get "#{change_log_rsrc}?page=#{@change_log_page}&page-size=#{@change_log_page_size}#{@change_log_sort}#{@change_log_filter}" @change_log_paged_fetched_count += raw[:results].size @change_log_paged_total_count = raw[:totalCount] # did we get the last of them in the this page? # if so, clear all the paging data clear_change_log_paging_data if @change_log_paged_fetched_count >= @change_log_paged_total_count # return the page results raw[:results].map { |le| Jamf::ChangeLogEntry.new le } end |