Module: Jamf::ChangeLog

Included in:
Building, Category, ClientCheckInSettings, ClientCheckInSettings, Department, DeviceEnrollment, InventoryPreloadRecord, MobileDevicePrestage, ReEnrollmentSettings, Script, Site
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’

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

This module will add two methods:

1) #change_log,  will fetch and cache an Array of readonly
  Jamf::ChangeLogEntry instances. passing any truthy parameter will
  cause it to re-fetch the Array from the server.

2) #add_history_note(note), which takes a string and adds it to the
  object's change history as a note and re-fetches & caches the history.

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, it is recached after adding the note.

Parameters:

  • note (String) —

    The note to add. It cannot be empty.



100
101
102
103
104
105
106
107
108
109
 
# File 'lib/jamf/api/mixins/change_log.rb', line 100

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(refresh = false, cnx: Jamf.cnx) ⇒ Array<Jamf::ChangeHistoryEntry>

The change and note history for this resource.

The history is cached internally and only re-fetched when a truthy parameter is given.

Parameters:

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

    re-fetch and re-cache the history

Returns:

  • (Array<Jamf::ChangeHistoryEntry>) —

    The change and note history for this resource



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/jamf/api/mixins/change_log.rb', line 75

def change_log(refresh = false, cnx: Jamf.cnx)
  # this should only be true for instances of CollectionResources
  cnx = @cnx if @cnx

  @change_log = nil if refresh
  @change_log ||= cnx.get(change_log_rsrc)[:results].map! do |l|
    #
    # TODO: Report bug in jamf data, sometimes there's no details in the JSON
    # so add an empty string if needed. DO it for note too, just in case
    l[:details] ||= Jamf::BLANK
    l[:note] ||= Jamf::BLANK

    Jamf::ChangeLogEntry.new l
  end # map!
end