ruby-jss 1.6.0 → 2.0.0a11

data/lib/jamf/api/jamf_pro/mixins/collection_resource.rb

@@ -0,0 +1,762 @@
+# Copyright 2022 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+  # 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
+  ######################################
+  module CollectionResource
+    include Jamf::JPAPIResource
+
+    # when this module is included, also extend our Class Methods
+    def self.included(includer)
+      Jamf.load_msg "--> #{includer} is including Jamf::CollectionResource"
+      includer.extend(ClassMethods)
+    end
+
+    # Class Methods
+    #####################################
+    module ClassMethods
+      # 'include' all of these, so their methods become defined in this
+      # module, and will become Class Methods when this module
+      # is extended.
+      # since this module will be extended into a class
+
+      # It seems that all current collections are pageable and sortable
+      #
+      # Filterable must be extended as needed in Colection Resources
+
+      include Jamf::JPAPIResource::ClassMethods
+
+      # when this module is included, also extend our 'parent' class methods
+      ######################################
+      def self.extended(extender)
+        Jamf.load_msg "--> #{extender} is extending Jamf::CollectionResource::ClassMethods"
+      end
+
+      # All Classes including CollectionResource MUST define 'LIST_PATH', which
+      # is the URL path for GETting the list of all objects in the collection,
+      # possibly filtered, sorted, and/or paged
+
+      # The path for GETting a single object. The desired object id will be appended
+      # to the end, e.g. if this value is 'v1/buildings' and you want to GET the
+      # record for building id 23, then we will GET from 'v1/buildings/23'
+      #
+      # Classes including CollectionResource really need to define GET_PATH if it
+      # is not the same as the LIST_PATH.
+      # rubocop:disable Naming/AccessorMethodName
+      ######################################
+      def get_path
+        @get_path ||= defined?(self::GET_PATH) ? self::GET_PATH : self::LIST_PATH
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      # The path for PUTting (replacing) a single object. The desired object id will
+      # be appended to the end, e.g. if this value is 'v1/buildings' and you want
+      # to PUT the record for building id 23, then we will PUT to 'v1/buildings/23'
+      #
+      # Classes including CollectionResource really need to define PUT_PATH if it
+      # is not the same as the LIST_PATH.
+      ######################################
+      def put_path
+        @put_path ||= defined?(self::PUT_PATH) ? self::PUT_PATH : self::LIST_PATH
+      end
+
+      # The path for PATCHing (updating in-place) a single object. The desired
+      # object id will be appended to the end, e.g. if this value is 'v1/buildings'
+      # and you want to PATCH the record for building id 23, then we will PATCH to
+      # 'v1/buildings/23'
+      #
+      # Classes including CollectionResource really need to define PATCH_PATH if it
+      # is not the same as the LIST_PATH.
+      ######################################
+      def patch_path
+        @patch_path ||= defined?(self::PATCH_PATH) ? self::PATCH_PATH : self::LIST_PATH
+      end
+
+
+      # The path for POSTing to create a single object in the collection.
+      #
+      # Classes including CollectionResource really need to define POST_PATH if it
+      # is not the same as the LIST_PATH.
+      ######################################
+      def post_path
+        @post_path ||= defined?(self::POST_PATH) ? self::POST_PATH : self::LIST_PATH
+      end
+
+      # The path for DELETEing a single object from the collection.
+      #
+      # Classes including CollectionResource really need to define DELETE_PATH if it
+      # is not the same as the LIST_PATH.
+      ######################################
+      def delete_path
+        @delete_path ||= defined?(self::DELETE_PATH) ? self::DELETE_PATH : self::LIST_PATH
+      end
+
+      # @return [Array<Symbol>] the attribute names that are marked as identifiers
+      #
+      ######################################
+      def identifiers
+        idents = self::OAPI_PROPERTIES.select { |_attr, deets| deets[:identifier] }.keys
+        idents += self::ALT_IDENTIFIERS if defined? self::ALT_IDENTIFIERS
+        idents += self::NON_UNIQUE_IDENTIFIERS if defined? self::NON_UNIQUE_IDENTIFIERS
+        idents.delete_if { |i| !self::OAPI_PROPERTIES.key?(i) }
+        idents
+      end
+
+      # Get all instances of a CollectionResource, possibly sorted or limited by
+      # a filter.
+      #
+      # By default, this method will return a single Array data about all items
+      # in the CollectionResouce, in the server's default sort order, or a sort
+      # order you specify.
+      # As long as you don't request a filtered result, this full list is cached
+      # for future use (see Caching, below)
+      #
+      # If you specify a filter, the Array returned by the server will contain
+      # only matching objects, and it will not be cached.
+      #
+      # #### Server-side Sorting
+      #
+      # Sorting criteria can be provided using the 'sort:' parameter, which is
+      # a String of the format 'property:direction',
+      # where direction is 'asc' or 'desc' E.g.
+      #   "username:asc"
+      #
+      # Multiple properties are supported, either as separate strings in an Array,
+      # or a single string, comma separated. E.g.
+      #
+      #    "username:asc,timestamp:desc"
+      # is the same as
+      #    ["username:asc", "timestamp:desc"]
+      #
+      # which will sort by username alphabetically, and within each username,
+      # sort by timestamp newest first.
+      #
+      # Please see the JamfPro API documentation for the resource for details
+      # about available sorting properties and default sorting criteria
+      #
+      # When the sort: param is provided, the server is always queried, and
+      # the results will be cached, as long as the results were not filtered.
+      # See Caching, below.
+      #
+      # #### Filtering
+      #
+      # Some CollectionResouces support RSQL filters to limit which objects
+      # are returned by the server. These filters can be applied using the filter:
+      # parameter, in which case this `all` method will return "all that match
+      # the filter".
+      #
+      # The filter parameter is a string, as it would be provided in the API URL
+      # manually, e.g. 'categoryName=="Category"' (be careful about inner quoting)
+      #
+      # If the resource doesn't support filters, the filter parameter is ignored.
+      #
+      # Please see the JamfPro API documentation for the resource to see if
+      # filters are supported, and a list of available fields.
+      # See also https://developer.jamf.com/jamf-pro/docs/filtering-with-rsql
+      #
+      # #### Instantiation
+      #
+      # All data from the API comes from the server in JSON format, mostly as
+      # JSON 'objects', which are the equivalent of ruby Hashes.
+      # When fetching an individual instance of an object from the API, ruby-jss
+      # uses the JSON Hash to create the ruby object, i.e. to 'instantiate' it as
+      # an instance of its ruby class. Doing this for many objects can slow
+      # things down.
+      #
+      # Because of this, the 'all' method defaults to returning an Array of the
+      # minimally-processed JSON Hashes it gets from the API. If you can get your
+      # desired data from these Hashes, it may be more efficient to do so.
+      #
+      # However sometimes you really need the fully instantiated ruby objects for
+      # all items returned - especially if you're using filters and not actually
+      #  processing all items of the class.  In such cases you can pass a truthy
+      # value to the instantiate: parameter, and the Array will contain fully
+      # instantiated ruby objects, not Hashes of API data.
+      #
+      # #### Caching - none for Jamf Pro API objects.
+      #
+      # Unlike the Classic APIObjects, Objects from the Jamf Pro API
+      # are not cached and any call to 'all' or methods that use it, will
+      # always query the API. If you need to use the resulting array for multiple
+      # tasks, save it into a variable and use that.
+      #
+      #######
+      #
+      # @param sort [String, Array<String>] 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.
+      #
+      # @param filter [String] An RSQL filter string. Not all collection resources
+      #   currently support filters, and if they don't, this will be ignored.
+      #
+      # @param instantiate [Boolean] Defaults to false. Should the items in the
+      #   returned Array be ruby instances of the CollectionObject subclass, or
+      #   plain Hashes of data as returned by the API?
+      #
+      # @param cnx [Jamf::Connection] The API connection to use, default: Jamf.cnx
+      #
+      # @return [Array<Hash, Jamf::CollectionResource>] The objects in the collection
+      #
+      ######################################
+      def all(sort: nil, filter: nil, instantiate: false, cnx: Jamf.cnx, refresh: nil)
+
+        # if we are here, we need to query for all items, possibly filtered and
+        # sorted
+        sort = Jamf::Sortable.parse_url_sort_param(sort)
+        filter = filterable? ? Jamf::Filterable.parse_url_filter_param(filter) : nil
+        instantiate &&= self
+
+        # always use a pager to get all pages, because even if you don't ask for
+        # paged data, it comes in pages or 2000
+        Jamf::Pager.all_pages(
+          list_path: self::LIST_PATH,
+          sort: sort,
+          filter: filter,
+          instantiate: instantiate,
+          cnx: cnx
+        )
+      end
+
+      # Return a Jamf::Pager object for retrieving all collection items in smaller
+      # groups.
+      #
+      # For other parameters, see CollectionResource.all
+      #
+      # @param page_size [Integer] The pager object returns results in groups of
+      #   this many items. Minimum is 1, maximum is 2000, default is 100
+      #   Note: the final page of data may contain fewer items than the page_size
+      #
+      # @return [Jamf::Pager] An object from which you can retrieve sequential or
+      #   arbitrary pages from the collection.
+      #
+      def pager(page_size: Jamf::Pager::DEFAULT_PAGE_SIZE, sort: nil, filter: nil, instantiate: false, cnx: Jamf.cnx)
+
+        sort = Jamf::Sortable.parse_url_sort_param(sort)
+        filter = filterable? ? Jamf::Filterable.parse_url_filter_param(filter) : nil
+
+        Jamf::Pager.new(
+          page_size: page_size,
+          list_path: self::LIST_PATH,
+          sort: sort,
+          filter: filter,
+          instantiate: instantiate,
+          cnx: cnx
+        )
+      end
+
+      # A Hash of all members of this collection where the keys are some
+      # identifier and values are any other attribute.
+      #
+      # @param ident [Symbol] An identifier of this Class, used as the key
+      #   for the mapping Hash. Aliases are acceptable, e.g. :sn for :serialNumber
+      #
+      # @param to [Symbol] The attribute to which the ident will be mapped.
+      #   Aliases are acceptable, e.g. :name for :displayName
+      #
+      # @param cached_list [Array<Hash>] The result of a previous call to .all
+      #   can be passed in here, to prevent calling .all again to generate a
+      #   fresh list.
+      #
+      # @param cnx (see .all)
+      #
+      # @return [Hash {Symbol: Object}] A Hash of identifier mapped to attribute
+      #
+      ######################################
+      def map_all(ident, to:, cnx: Jamf.cnx, cached_list: nil, refresh: nil)
+        raise Jamf::InvalidDataError, "No identifier :#{ident} for class #{self}" unless
+        identifiers.include? ident
+
+        raise Jamf::NoSuchItemError, "No attribute :#{to} for class #{self}" unless self::OAPI_PROPERTIES.key? to
+
+
+        list = cached_list || all(cnx: cnx)
+        to_class = self::OAPI_PROPERTIES[to][:class]
+        to_multi = self::OAPI_PROPERTIES[to][:multi]
+        mapped = list.map do |i|
+          mapped_val =
+            if to_class.is_a?(Symbol)
+              i[to]
+            elsif to_multi
+              i[to].map { |sub_i| to_class.new(sub_i) }
+            else
+              to_class.new(i[to])
+            end
+
+          [i[ident], mapped_val]
+        end # do i
+        mapped.to_h
+      end
+
+      # Given a key (identifier) and value for this collection, return the raw data
+      # Hash (the JSON object) for the matching API object or nil if there's no
+      # match for the given value.
+      #
+      # In general you should use this if the form:
+      #
+      #    raw_data identifier: value
+      #
+      # where identifier is one of the available identifiers for this class
+      # like id:, name:, serialNumber: etc.
+      #
+      # In the unlikely event that you dont know which identifier a value is for
+      # or want to be able to take any of them without specifying, then
+      # you can use
+      #
+      #   raw_data some_value
+      #
+      # If some_value is an integer or a string containing an integer, it
+      # is assumed to be an :id otherwise all the available identifers
+      # are searched, in the order you see them when you call <class>.identifiers
+      #
+      # If no matching object is found, nil is returned.
+      #
+      # Everything except :id is treated as a case-insensitive String
+      #
+      # @param value [String, Integer] The identifier value to search fors
+      #
+      # @param key: [Symbol] The identifier being used for the search.
+      #  E.g. if :serialNumber, then the value must be a known serial number, it
+      #  is not checked against other identifiers. Defaults to :id
+      #
+      # @param cnx: (see .all)
+      #
+      # @return [Hash, nil] the basic dataset of the matching object,
+      #   or nil if it doesn't exist
+      #
+      ######################################
+      def raw_data(searchterm = nil, ident: nil, value: nil, cnx: Jamf.cnx)
+
+
+        # given a value with no ident key
+        return raw_data_by_searchterm_only(searchterm, cnx: cnx) if searchterm
+
+        # if we're here, we should know our ident key and value
+        raise ArgumentError, 'Required parameter "identifier: value", where identifier is id:, name: etc.' unless ident && value
+
+        return raw_data_by_id(value, cnx: cnx) if ident == :id
+        return unless identifiers.include? ident
+
+        raw_data_by_other_identifier(ident, value, cnx: cnx)
+      end
+
+      # Match the given value in all possibly identifiers
+      def raw_data_by_searchterm_only(searchterm, cnx: Jamf.cnx)
+        # if this is an integer or j_integer, assume its an ID
+        return raw_data_by_id(searchterm, cnx: cnx) if searchterm.to_s.j_integer?
+
+        identifiers.each do |ident|
+          next if ident == :id
+
+          data = raw_data_by_other_identifier(ident, searchterm, cnx: cnx)
+          return data if data
+        end # identifiers.each
+
+        nil
+      end
+
+      # get the basic dataset by id, with optional
+      # request params to get more than basic data
+      ######################################
+      def raw_data_by_id(id, cnx: Jamf.cnx)
+        cnx.jp_get "#{get_path}/#{id}"
+      rescue Jamf::Connection::JamfProAPIError => e
+        return nil if e.errors.any? { |err| err.code == 'INVALID_ID' }
+
+        raise e
+      end
+
+      # Given an indentier attr. key, and a value,
+      # return the raw data where that ident has that value, or nil
+      #
+      ######################################
+      def raw_data_by_other_identifier(identifier, value, cnx: Jamf.cnx)
+        # if the API supports filtering by this identifier, just use that
+        return pager(filter: "#{identifier}==\"#{value}\"", page_size: 1, cnx: cnx).page(:first).first if filterable? && filter_keys.include?(identifier)
+
+        # otherwise we have to loop thru all the objects looking for the value
+        cmp_val = value.to_s
+        all(cnx: cnx).each do |data|
+          return data if data[identifier].to_s.casecmp? cmp_val
+        end
+
+        nil
+      end
+
+      # Look up the valid ID for any arbitrary identifier.
+      # In general you should use this if the form:
+      #
+      #    valid_id identifier: value
+      #
+      # where identifier is one of the available identifiers for this class
+      # like id:, name:, serialNumber: etc.
+      #
+      # In the unlikely event that you dont know which identifier a value is for
+      # or want to be able to take any of them without specifying, then
+      # you can use
+      #
+      #   valid_id some_value
+      #
+      # If some_value is an integer or a string containing an integer, it
+      # is assumed to be an id: otherwise all the available identifers
+      # are searched, in the order you see them when you call <class>.identifiers
+      #
+      # If no matching object is found, nil is returned.
+      #
+      # WARNING: Do not use this to look up ids for getting the
+      # raw API data for an object. Since this calls .raw_data
+      # itself, it is redundant to use .valid_id to get an id
+      # to then pass on to .raw_data
+      # Use raw_data directly like this:
+      #    data = raw_data(ident: val)
+      #
+      #
+      # @param value [String,Integer] A value for an arbitrary identifier
+      #
+      # @param cnx [Jamf::Connection] The connection to use. default: Jamf.cnx
+      #
+      # @param ident_and_val [Hash{Symbol: String}] The identifier key and the value
+      #   to look for in that key, e.g. name: 'foo' or serialNumber: 'ASDFGH'
+      #
+      # @return [String, nil] The id (integer-in-string) of the object, or nil
+      #    if no match found
+      #
+      ######################################
+      def valid_id(searchterm = nil, cnx: Jamf.cnx, **ident_and_val)
+        raw_data(searchterm, cnx: cnx, **ident_and_val)&.dig(:id)
+      end
+
+      # By default, Collection Resources are creatable,
+      # i.e. new instances can be created
+      # with .create, and added to the JSS with .save
+      # If a subclass is NOT creatble for any reason, just add
+      #   extend Jamf::Uncreatable
+      # and this method will return false
+      #
+      # @return [Boolean]
+      ######################################
+       def creatable?
+        true
+      end
+
+      # Make a new thing to be added to the API
+      ######################################
+      def create(**params)
+
+
+        # no such animal when .creating
+        params.delete :id
+
+        # Which connection to use
+        params[:cnx] ||= Jamf.cnx
+
+        # So the super constructor knows we are instantiating an object that
+        # isn't from the API, and will do validation on all params.
+        params[:creating_from_create] = true
+
+        new(**params)
+      end
+
+      # Retrieve a member of a CollectionResource from the API
+      #
+      # To create new members to be added to the JSS, use
+      # {Jamf::CollectionResource.create}
+      #
+      # You must know the specific identifier attribute you're looking up, e.g.
+      # :id or :name or :udid, (or an aliase thereof) then you can specify it like
+      # `.fetch name: 'somename'`, or `.fetch udid: 'someudid'`
+      #
+      # @param cnx[Jamf::Connection] the connection to use to fetch the object
+      #
+      # @param ident_and_val[Hash] an identifier attribute key and a search value
+      #
+      # @return [CollectionResource] The ruby-instance of a Jamf object
+      #
+      ######################################
+      def fetch(searchterm = nil, random: false, cnx: Jamf.cnx, **ident_and_val)
+        if searchterm == :random
+          random = true
+          searchterm = nil
+        end
+
+        data =
+          if searchterm
+            raw_data searchterm, cnx: cnx
+          elsif random
+            all.sample
+          else
+            ident, value = ident_and_val.first
+            ident && value ? raw_data(ident: ident, value: value, cnx: cnx) : nil
+          end
+
+        raise Jamf::NoSuchItemError, "No matching #{self}" unless data
+
+        data[:cnx] = cnx
+        new(**data)
+      end # fetch
+
+      # By default, CollectionResource instances are deletable.
+      # If not, just extend the subclass with Jamf::Undeletable, and this
+      # will return false, and .delete & #delete will raise errors
+      ######################################
+      def deletable?
+        true
+      end
+
+      def filterable?
+        singleton_class.ancestors.include? Jamf::Filterable
+      end
+
+      def bulk_deletable?
+        singleton_class.ancestors.include? Jamf::BulkDeletable
+      end
+
+      # Delete one or more objects by id
+      # TODO: fix this return value, no more ErrorInfo
+      #
+      # @param ids [Array<String,Integer>] The ids to delete
+      #
+      # @param cnx [Jamf::Connection] The connection to use, default: Jamf.cnx
+      #
+      #
+      # @return [Array<Jamf::Connection::APIError::ErrorInfo] Info about any ids
+      #   that failed to be deleted.
+      #
+      ######################################
+      def delete(*ids, cnx: Jamf.cnx)
+        raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
+
+        return bulk_delete(ids, cnx: Jamf.cnx) if self.bulk_deletable?
+
+        errs = []
+        ids.each do |id_to_delete|
+          cnx.jp_delete "#{delete_path}/#{id_to_delete}"
+        rescue Jamf::Connection::JamfProAPIError => e
+          raise e unless e.http_response.status == 404
+
+          errs += e.errors
+        end # ids.each
+        errs
+      end
+
+      # Dynamically create_identifier_list_methods
+      # when one is called.
+      def method_missing(method, *args, &block)
+        if available_list_methods.key? method.to_s
+          attr_name = available_list_methods[method.to_s]
+          create_identifier_list_method attr_name.to_sym, method
+          send method, *args
+        else
+          super
+        end
+      end
+
+      # this is needed to prevent problems with method_missing!
+      def respond_to_missing?(method, *)
+        available_list_methods.key?(method.to_s) || super
+      end
+
+      # @return [Hash{String: Symbol}] Method name to matching attribute name for
+      #   all identifiers
+      def available_list_methods
+        return @available_list_methods if @available_list_methods
+
+        @available_list_methods = {}
+
+        identifiers.each do |i|
+          meth_name = i.to_s.end_with?('s') ? "all_#{i}es" : "all_#{i}s"
+          @available_list_methods[meth_name] = i
+        end
+        @available_list_methods
+      end
+
+      # called from method_missing to create
+      # identifier lists on the fly. No filtering or sorting of these lists.
+      ######################################
+      def create_identifier_list_method(attr_name, list_method_name)
+        # only if the attr_name exists in the OAPI_PROPERTIES _and_
+        # is listed as an identifier for this class.
+        if defined?(self::OAPI_PROPERTIES) && self::OAPI_PROPERTIES.key?(attr_name) && identifiers.include?(attr_name)
+          attr_def = self::OAPI_PROPERTIES[attr_name]
+
+          define_singleton_method(list_method_name) do |_refresh = nil, cnx: Jamf.cnx, cached_list: nil|
+            all_list = cached_list || all(cnx: cnx)
+            if attr_def[:class].is_a? Symbol
+              all_list.map { |i| i[attr_name] }
+            else
+              all_list.map { |i| attr_def[:class].new i[attr_name] }
+            end
+          end # define_singleton_method
+          Jamf.load_msg "Defined method #{self}##{list_method_name}"
+        else
+
+          define_singleton_method(list_method_name) do |*|
+            raise NoMethodError, "no method '#{list_method_name}': '#{attr_name}' is not an indentifier for #{self}"
+          end
+        end
+
+      end # create_identifier_list_method
+      private :create_identifier_list_method
+
+    end # Module ClassMethods
+
+    # Attributes
+    #####################################
+
+    # @return [String] The path for creating a new item in the collection
+    #   in the JPAPI
+    #
+    attr_reader :post_path
+
+    # @return [String] The path for deleting a this item from the collection
+    #   in the JPAPI
+    #
+    attr_reader :delete_path
+
+    # Constructor
+    #####################################
+    def initialize(**data)
+      super
+      set_api_paths
+    end
+
+    # Instance Methods
+    #####################################
+
+    #####################################
+    def exist?
+      !@id.nil?
+    end
+
+    #####################################
+    def delete
+      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless self.class.deletable?
+
+      @cnx.jp_delete delete_path
+    end
+
+    # A meaningful string representation of this object
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{self.class}@#{cnx.host}, id: #{@id}"
+    end
+
+    # Private Instance Methods
+    ############################################
+    private
+
+    ############################################
+    def set_api_paths
+      if exist?
+        @get_path = "#{self.class.get_path}/#{id}"
+
+        @update_path =
+          if defined?(self.class::PUT_PATH)
+            "#{self.class::PUT_PATH}/#{id}"
+          elsif defined?(self.class::PATCH_PATH)
+            "#{self.class::PATCH_PATH}/#{id}"
+          else
+            "#{self.class::LIST_PATH}/#{id}"
+          end
+
+        @delete_path = defined?(self.class::DELETE_PATH) ? "#{self.class::DELETE_PATH}/#{id}" : "#{self.class::LIST_PATH}/#{id}"
+
+        @post_path = nil
+
+      else
+        @post_path = defined?(self.class::POST_PATH) ? self.class::POST_PATH : self.class::LIST_PATH
+      end
+    end
+
+    ############################################
+    def create_in_jamf
+      unless defined?(self.class::POST_OBJECT)
+        raise Jamf::MissingDataError,
+              "Class #{self.class} has not defined a POST_OBJECT"
+      end
+
+      validate_for_create
+
+      post_object = self.class::POST_OBJECT.new(to_jamf)
+
+      result = @cnx.jp_post post_path, post_object.to_jamf
+
+      @id = result[:id]
+
+      # reset the API  paths now that we exist
+      set_api_paths
+
+      # return the id
+      @id
+    end
+
+    # make sure that required values are not nil
+    ############################################
+    def validate_for_create
+      self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
+        next unless attr_def[:required]
+        next unless send(attr_name).nil?
+
+        raise Jamf::MissingDataError, "Attribute '#{attr_name}' cannot be nil, must be a #{attr_def[:class]}"
+      end
+    end
+  end # class CollectionResource
+end # module JAMF