module Jamf::CollectionResource

A Collection Resource in Jamf Pro

See {Jamf::Resource} for general info about API resources.

Collection resources have more than one resource within them, and those can (usually) be created and deleted as well as fetched and updated. The entire collection (or a part of it) can also be retrieved as an Array. When the whole collection is retrieved, the result may be cached for future use.

# Subclassing

## Creatability, & Deletability

Sometimes the API doesn’t support creation of new members of the collection. If that’s the case, just extend the subclass with Jamf::Uncreatable and the ‘.create’ class method will raise an error.

Similarly for deletion of members: if the API doesn’t have a way to delete them, extend the subclass with Jamf::Undeletable

See also Jamf::JSONObject, which talks about extending subclasses with Jamf::Immutable

## Bulk Deletion

Some collection resources have a resource for bulk deletion, passing in a JSON array of ids to delete.

If so, just define a BULK_DELETE_RSRC, and the .delete class method will use it, rather than making multiple calls to delete individual items. See Jamf::Category::BULK_DELETE_RSRC for an example

@abstract

Attributes

delete_path[R]

@return [String] The path for deleting a this item from the collection

in the JPAPI
post_path[R]

@return [String] The path for creating a new item in the collection

in the JPAPI

Public Class Methods

included(includer) click to toggle source

when this module is included, also extend our Class Methods

   # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
68 def self.included(includer)
69   Jamf.load_msg "--> #{includer} is including Jamf::CollectionResource"
70   includer.extend(ClassMethods)
71 end
new(**data) click to toggle source

Constructor

Calls superclass method Jamf::JPAPIResource::new
    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
667 def initialize(**data)
668   super
669   set_api_paths
670 end

Public Instance Methods

delete() click to toggle source
    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
681 def delete
682   raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless self.class.deletable?
683 
684   @cnx.jp_delete delete_path
685 end
exist?() click to toggle source
    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
676 def exist?
677   !@id.nil?
678 end
to_s() click to toggle source

A meaningful string representation of this object

@return [String]

    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
691 def to_s
692   "#{self.class}@#{cnx.host}, id: #{@id}"
693 end

Private Instance Methods

create_in_jamf() click to toggle source
    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
723 def create_in_jamf
724   unless defined?(self.class::POST_OBJECT)
725     raise Jamf::MissingDataError,
726           "Class #{self.class} has not defined a POST_OBJECT"
727   end
728 
729   validate_for_create
730 
731   post_object = self.class::POST_OBJECT.new(to_jamf)
732 
733   result = @cnx.jp_post post_path, post_object.to_jamf
734 
735   @id = result[:id]
736 
737   # reset the API  paths now that we exist
738   set_api_paths
739 
740   # return the id
741   @id
742 end
set_api_paths() click to toggle source
    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
700 def set_api_paths
701   if exist?
702     @get_path = "#{self.class.get_path}/#{id}"
703 
704     @update_path =
705       if defined?(self.class::PUT_PATH)
706         "#{self.class::PUT_PATH}/#{id}"
707       elsif defined?(self.class::PATCH_PATH)
708         "#{self.class::PATCH_PATH}/#{id}"
709       else
710         "#{self.class::LIST_PATH}/#{id}"
711       end
712 
713     @delete_path = defined?(self.class::DELETE_PATH) ? "#{self.class::DELETE_PATH}/#{id}" : "#{self.class::LIST_PATH}/#{id}"
714 
715     @post_path = nil
716 
717   else
718     @post_path = defined?(self.class::POST_PATH) ? self.class::POST_PATH : self.class::LIST_PATH
719   end
720 end
validate_for_create() click to toggle source

make sure that required values are not nil

    # File lib/jamf/api/jamf_pro/mixins/collection_resource.rb
746 def validate_for_create
747   self.class::POST_OBJECT::OAPI_PROPERTIES.each do |attr_name, attr_def|
748     next unless attr_def[:required]
749     next unless send(attr_name).nil?
750 
751     raise Jamf::MissingDataError, "Attribute '#{attr_name}' cannot be nil, must be a #{attr_def[:class]}"
752   end
753 end