Module: Jamf::ChangeLog

Included in:

InventoryPreloadRecord, JpBuilding

Defined in:

lib/jamf/api/jamf_pro/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:

• 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.

Defined Under Namespace

Modules: ClassMethods

Constant Summary

DFT_HISTORY_PATH =

'history'.freeze

SEARCH_RESULTS_OBJECT =

Jamf::OAPISchemas::HistorySearchResultsV1

HISTORY_ENTRY_OBJECT =

Jamf::ChangeLogEntry

POST_NOTE_OBJECT =

Jamf::OAPISchemas::ObjectHistoryNote

Class Method Summary

• .included(includer) ⇒ Object

  when this module is included, also extend our Class Methods.

Instance Method Summary

• #add_change_log_note(note) ⇒ Object

  Instance Methods.

• #change_log(sort: nil, filter: nil) ⇒ Object
• #change_log_count ⇒ Object
• #change_log_pager(page_size: Jamf::Pager::DEFAULT_PAGE_SIZE, sort: nil, filter: nil) ⇒ Object
• #history_path ⇒ Object

Class Method Details

.included(includer) ⇒ Object

when this module is included, also extend our Class Methods

# File 'lib/jamf/api/jamf_pro/mixins/change_log.rb', line 93

def self.included(includer)
  Jamf.load_msg "--> #{includer} is including Jamf::ChangeLog"
  includer.extend(ClassMethods)
end

Instance Method Details

#add_change_log_note(note) ⇒ Object

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', line 218

def add_change_log_note(note)
  self.class.add_change_log_note(note, id: @id, cnx: @cnx)
end

#change_log(sort: nil, filter: nil) ⇒ Object

# File 'lib/jamf/api/jamf_pro/mixins/change_log.rb', line 222

def change_log(sort: nil, filter: nil)
  self.class.change_log(id: @id, sort: sort, filter: filter, cnx: @cnx)
end

#change_log_count ⇒ Object

# File 'lib/jamf/api/jamf_pro/mixins/change_log.rb', line 236

def change_log_count
  self.class.change_log_count(id: @id, cnx: @cnx)
end

#change_log_pager(page_size: Jamf::Pager::DEFAULT_PAGE_SIZE, sort: nil, filter: nil) ⇒ Object

# File 'lib/jamf/api/jamf_pro/mixins/change_log.rb', line 226

def change_log_pager(page_size: Jamf::Pager::DEFAULT_PAGE_SIZE, sort: nil, filter: nil)
  self.class.change_log_pager(
    page_size: page_size,
    id: @id,
    sort: sort,
    filter: filter,
    cnx: @cnx
  )
end

#history_path ⇒ Object

# File 'lib/jamf/api/jamf_pro/mixins/change_log.rb', line 240

def history_path
  self.class.history_path(@id)
end