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

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.

Parameters:

  • note (String) —

    The note to add. It cannot be empty.



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.

Parameters:

  • sort (String, Array<String>) (defaults to: nil) —

    Server-side sorting criteria in the format: property:direction, where direction is 'asc' or 'desc'. Multiple properties are supported, either as separate strings in an Array, or a single string, comma separated.

  • filter (String) (defaults to: nil) —

    An RSQL filter string. Not all change_log resources currently support filters, and if they don't, this will be ignored.

  • paged (Boolean) (defaults to: nil) —

    Defaults to false. Returns only the first page of `page_size` log entries. Use #next_page_of_change_log to retrieve each

  • page_size (Integer) (defaults to: nil) —

    How many log entries are returned per page? Minimum is 1, maximum is 2000, default is 100. Ignored unless paged: is truthy. Note: the final page may contain fewer entries than the page_size

  • refresh (Boolean) (defaults to: false) —

    re-fetch and re-cache the full list of all entries. Ignored if paged:, page_size:, sort:, or filter: are used.

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use, default: Jamf.cnx. If this is an instance of a Collection Resource, this is always the connection from which it was fetched.

Returns:



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

Parameters:

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use, default: Jamf.cnx This is ignored for instances of Collection Resources, which always use the same connection from which they were fetched.

Returns:

  • (Integer) —

    How many changelog entries exist?



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.

Returns:

  • (Array<Jamf::ChangeHistoryEntry>) —

    The next page of the change and note history for this resource



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