ruby-jss 0.6.3

data/lib/jss/api_connection.rb

@@ -0,0 +1,410 @@
+### Copyright 2016 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 JSS
+
+  #####################################
+  ### Constants
+  #####################################
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Module Classes
+  #####################################
+
+  ###
+  ### An API connection to the JSS.
+  ###
+  ### This is a singleton class, only one can exist at a time.
+  ### Its one instance is created automatically when the module loads, but it
+  ### isn't connected to anything at that time.
+  ###
+  ### Use it via the {JSS::API} constant to call the #connect
+  ### method, and the {#get_rsrc}, {#put_rsrc}, {#post_rsrc}, & {#delete_rsrc}
+  ### methods, q.v. below.
+  ###
+  ### To access the underlying RestClient::Resource instance,
+  ### use JSS::API.cnx
+  ###
+  class APIConnection
+    include Singleton
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ### The base API path in the jss URL
+    RSRC_BASE = "JSSResource"
+
+    ### A url path to load to see if there's an API available at a host.
+    ### This just loads the API resource docs page
+    TEST_PATH = "#{RSRC_BASE}/accounts"
+
+    ### If the test path loads correctly from a casper server, it'll contain
+    ### this text (this is what we get when we make an unauthenticated
+    ### API call.)
+    TEST_CONTENT = "<p>The request requires user authentication</p>"
+
+    ### The Default port
+    HTTP_PORT = 9006
+
+    ### The SSL port
+    SSL_PORT = 8443
+
+    ### The top line of an XML doc for submitting data via API
+    XML_HEADER = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>'
+
+    ### Default timeouts in seconds
+    DFT_OPEN_TIMEOUT = 60
+    DFT_TIMEOUT = 60
+
+    ### The Default SSL Version
+    DFT_SSL_VERSION = 'TLSv1'
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    ### @return [String] the username who's connected to the JSS API
+    attr_reader :jss_user
+
+    ### @return [RestClient::Resource] the underlying connection resource
+    attr_reader :cnx
+
+    ### @return [Boolean] are we connected right now?
+    attr_reader :connected
+
+    ### @return [JSS::Server] the details of the JSS to which we're connected.
+    attr_reader :server
+
+    ### @return [String] the hostname of the JSS to which we're connected.
+    attr_reader :server_host
+
+    #####################################
+    ### Constructor
+    #####################################
+
+    ###
+    ### To connect, use JSS::APIConnection.instance.connect
+    ### or a shortcut, JSS::API.connect
+    ###
+    def initialize ()
+      @connected = false
+    end # init
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    ###
+    ### Connect to the JSS API.
+    ###
+    ### @param args[Hash] the keyed arguments for connection.
+    ###
+    ### @option args :server[String] the hostname of the JSS API server, required if not defined in JSS::CONFIG
+    ###
+    ### @option args :port[Integer] the port number to connect with, defaults to 8443
+    ###
+    ### @option args :use_ssl[Boolean] should the connection be made over SSL? Defaults to true.
+    ###
+    ### @option args :verify_cert[Boolean] should HTTPS SSL certificates be verified. Defaults to true.
+    ###   If your connection raises RestClient::SSLCertificateNotVerified, and you don't care about the
+    ###   validity of the SSL cert. just set this explicitly to false.
+    ###
+    ### @option args :user[String] a JSS user who has API privs, required if not defined in JSS::CONFIG
+    ###
+    ### @option args :pw[String,Symbol] Required, the password for that user, or :prompt, or :stdin
+    ###   If :prompt, the user is promted on the commandline to enter the password for the :user.
+    ###   If :stdin#, the password is read from a line of std in represented by the digit at #,
+    ###   so :stdin3 reads the passwd from the third line of standard input. defaults to line 1,
+    ###   if no digit is supplied. see {JSS.stdin}
+    ###
+    ### @option args :open_timeout[Integer] the number of seconds to wait for an initial response, defaults to 60
+    ###
+    ### @option args :timeout[Integer] the number of seconds before an API call times out, defaults to 60
+    ###
+    ### @return [true]
+    ###
+    def connect (args = {})
+
+      # the server, if not specified, might come from a couple places.
+      # see #hostname
+      args[:server] ||= hostname
+
+      # settings from config if they aren't in the args
+      args[:server] ||= JSS::CONFIG.api_server_name
+      args[:port] ||= JSS::CONFIG.api_server_port
+      args[:user] ||= JSS::CONFIG.api_username
+      args[:timeout] ||= JSS::CONFIG.api_timeout
+      args[:open_timeout] ||= JSS::CONFIG.api_timeout_open
+      args[:ssl_version] ||= JSS::CONFIG.api_ssl_version
+
+      # if verify cert given was NOT in the args....
+      if args[:verify_cert].nil?
+        # set it from the prefs
+        args[:verify_cert] = JSS::CONFIG.api_verify_cert
+      end
+
+      # settings from client jamf plist if needed
+      args[:port] ||=  JSS::Client.jss_port
+
+      # default settings if needed
+      args[:port] ||= SSL_PORT
+      args[:timeout] ||= DFT_TIMEOUT
+      args[:open_timeout] ||= DFT_OPEN_TIMEOUT
+
+      # As of Casper 9.61 we can't use SSL, must use TLS, since SSLv3 was susceptible to poodles.
+      # NOTE - this requires rest-client v 1.7.0 or higher
+      # which requires mime-types 2.0 or higher, which requires ruby 1.9.2 or higher!
+      # That means that support for ruby 1.8.7 stops with Casper 9.6
+      args[:ssl_version] ||= DFT_SSL_VERSION
+
+
+      # must have server, user, and pw
+      raise JSS::MissingDataError, "No JSS :server specified, or in configuration." unless args[:server]
+      raise JSS::MissingDataError, "No JSS :user specified, or in configuration." unless args[:user]
+      raise JSS::MissingDataError, "Missing :pw for user '#{args[:user]}'" unless args[:pw]
+
+      # we're using ssl if 1) args[:use_ssl] is anything but false
+      # or 2) the port is the default casper ssl port.
+      args[:use_ssl] = (not args[:use_ssl] == false) or (args[:port] == SSL_PORT)
+
+      # and here's the URL
+      ssl = args[:use_ssl] ? "s" : ''
+      @rest_url = URI::encode "http#{ssl}://#{args[:server]}:#{args[:port]}/#{RSRC_BASE}"
+
+
+      # prep the args for passing to RestClient::Resource
+      # if verify_cert is anything but false, we will verify
+      args[:verify_ssl] =  (args[:verify_cert] == false) ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
+
+      args[:password] = if args[:pw] == :prompt
+        JSS.prompt_for_password "Enter the password for JSS user #{args[:user]}@#{args[:server]}:"
+      elsif args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
+        args[:pw].to_s =~ /^stdin(\d+)$/
+        line = $1
+        line ||= 1
+        JSS.stdin line
+      else
+        args[:pw]
+      end
+
+      # heres our connection
+      @cnx = RestClient::Resource.new("#{@rest_url}", args)
+
+      @jss_user = args[:user]
+      @server_host = args[:server]
+      @connected = true
+      @server = JSS::Server.new
+
+      if @server.version < JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
+        raise JSS::UnsupportedError, "Your JSS Server version, #{@server.raw_version}, is to low. Must be #{JSS::MINIMUM_SERVER_VERSION} or higher."
+      end
+
+      return @connected ? @server_host : nil
+    end # connect
+
+    ###
+    ### Reset the response timeout for the rest connection
+    ###
+    ### @param timeout[Integer] the new timeout in seconds
+    ###
+    ### @return [void]
+    ###
+    def timeout= (timeout)
+      @cnx.options[:timeout] = timeout
+    end
+
+    ###
+    ### Reset the open-connection timeout for the rest connection
+    ###
+    ### @param timeout[Integer] the new timeout in seconds
+    ###
+    ### @return [void]
+    ###
+    def open_timeout= (timeout)
+      @cnx.options[:open_timeout] = timeout
+    end
+
+
+    ###
+    ### With a REST connection, there isn't any real "connection" to disconnect from
+    ### So to disconnect, we just unset all our credentials.
+    ###
+    ### @return [void]
+    ###
+    def disconnect
+      @jss_user = nil
+      @rest_url = nil
+      @server_host = nil
+      @cnx = nil
+      @connected = false
+    end # disconnect
+
+    ###
+    ### Get an arbitrary JSS resource
+    ###
+    ### The first argument is the resource to get (the part of the API url
+    ### after the 'JSSResource/' )
+    ###
+    ### By default we get the data in JSON, and parse it
+    ### into a ruby data structure (arrays, hashes, strings, etc)
+    ### with symbolized Hash keys.
+    ###
+    ### @param rsrc[String] the resource to get
+    ###   (the part of the API url after the 'JSSResource/' )
+    ###
+    ### @param format[Symbol] either ;json or :xml
+    ###  If the second argument is :xml, the XML data is returned as a String.
+    ###
+    ### @return [Hash,String] the result of the get
+    ###
+    def get_rsrc (rsrc, format = :json)
+      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
+      rsrc = URI::encode rsrc
+      data = @cnx[rsrc].get(:accept => format)
+      return JSON.parse(data, :symbolize_names => true) if format == :json
+      data
+    end
+
+    ###
+    ### Change an existing JSS resource
+    ###
+    ### @param rsrc[String] the API resource being changed, the URL part after 'JSSResource/'
+    ###
+    ### @param xml[String] the xml specifying the changes.
+    ###
+    ### @return [String] the xml response from the server.
+    ###
+    def put_rsrc(rsrc,xml)
+      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
+
+      ### convert CRs & to &#13;
+      xml.gsub!(/\r/, '&#13;')
+
+      ### send the data
+      @cnx[rsrc].put(xml, :content_type => 'text/xml')
+    end
+
+    ###
+    ### Create a new JSS resource
+    ###
+    ### @param rsrc[String] the API resource being created, the URL part after 'JSSResource/'
+    ###
+    ### @param xml[String] the xml specifying the new object.
+    ###
+    ### @return [String] the xml response from the server.
+    ###
+    def post_rsrc(rsrc,xml)
+      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
+
+      ### convert CRs & to &#13;
+      xml.gsub!(/\r/, '&#13;')
+
+      ### send the data
+      @cnx[rsrc].post xml, :content_type => 'text/xml', :accept => :json
+    end #post_rsrc
+
+    ### Delete a resource from the JSS
+    ###
+    ### @param rsrc[String] the resource to create, the URL part after 'JSSResource/'
+    ###
+    ### @return [String] the xml response from the server.
+    ###
+    def delete_rsrc(rsrc)
+      raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
+      raise MissingDataError, "Missing :rsrc" if rsrc.nil?
+
+      ### delete the resource
+      @cnx[rsrc].delete
+
+    end #delete_rsrc
+
+
+    ### Test that a given hostname & port is a JSS API server
+    ###
+    ### @param server[String] The hostname to test,
+    ###
+    ### @param port[Integer] The port to try connecting on
+    ###
+    ### @return [Boolean] does the server host a JSS API?
+    ###
+    def valid_server? (server, port = SSL_PORT)
+      # cheating by shelling out to curl, because getting open-uri, or even net/http to use
+      # ssl_options like :OP_NO_SSLv2 and :OP_NO_SSLv3 will take time to figure out..
+      return true if `/usr/bin/curl -s 'https://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
+      return true if `/usr/bin/curl -s 'http://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
+      return false
+
+      # try ssl first
+      # NOTE:  doesn't work if we can't disallow SSLv3 or force TLSv1
+      # See cheat above.
+      begin
+        return true if open("https://#{server}:#{port}/#{TEST_PATH}", ssl_verify_mode: OpenSSL::SSL::VERIFY_NONE).read.include? TEST_CONTENT
+
+      rescue
+        # then regular http
+        begin
+          return true if open("http://#{server}:#{port}/#{TEST_PATH}").read.include? TEST_CONTENT
+        rescue
+          # any errors = no API
+          return false
+        end # begin
+      end #begin
+      # if we're here, no API
+      return false
+    end
+
+    ### The server to which we are connected, or will
+    ### try connecting to if none is specified with the
+    ### call to #connect
+    ###
+    ### @return [String] the hostname of the server
+    ###
+    def hostname
+      return @server_host if @server_host
+      srvr = JSS::CONFIG.api_server_name
+      srvr ||= JSS::Client.jss_server
+      return srvr
+    end
+
+    ### aliases
+    alias connected? connected
+
+
+  end # class JSSAPIConnection
+
+  ### The single instance of the APIConnection
+  API = APIConnection.instance
+
+
+end # module

data/lib/jss/api_object.rb

@@ -0,0 +1,616 @@
+### Copyright 2016 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 JSS
+
+  #####################################
+  ### Module Variables
+  #####################################
+
+  #####################################
+  ### Module Methods
+  #####################################
+
+  #####################################
+  ### Classes
+  #####################################
+
+  ###
+  ### This class is the parent to all JSS API objects. It provides standard methods and structures
+  ### that apply to all API resouces.
+  ###
+  ### See the README.md file for general info about using subclasses of JSS::APIObject
+  ###
+  ### == Subclassing
+  ###
+  ### === Constructor
+  ###
+  ### In general, subclasses should do any class-specific argument checking before
+  ### calling super, and then afterwards, use the contents of @init_data to populate
+  ### any class-specific attributes. @id, @name, @rest_rsrc, and @in_jss are handled here.
+  ###
+  ### If a subclass can be looked up by some key other than :name or :id, the subclass must
+  ### pass the keys as an Array in the second argument when calling super from #initialize.
+  ### See {JSS::Computer#initialize} for an example of how to implement this feature.
+  ###
+  ### === Object Creation
+  ###
+  ### If a subclass should be able to be created in the JSS be sure to include {JSS::Creatable}
+  ###
+  ### The constructor should verify any extra required data (aside from :name) in the args before or after
+  ### calling super.
+  ###
+  ### See {JSS::Creatable} for more details.
+  ###
+  ### === Object Modification
+  ###
+  ### If a subclass should be modifiable in the JSS, include {JSS::Updatable}, q.v. for details.
+  ###
+  ### === Object Deletion
+  ###
+  ### All subclasses can be deleted in the JSS.
+  ###
+  ### === Required Constants
+  ###
+  ### Subclasses *must* provide certain Constants in order to correctly interpret API data and
+  ### communicate with the API.
+  ###
+  ### ==== RSRC_BASE = [String],  The base for REST resources of this class
+  ###
+  ### e.g. 'computergroups' in  "https://casper.mycompany.com:8443/JSSResource/computergroups/id/12"
+  ###
+  ### ==== RSRC_LIST_KEY = [Symbol] The Hash key for the JSON list output of all objects of this class in the JSS.
+  ###
+  ### e.g. the JSON output of resource "JSSResource/computergroups" is a hash
+  ### with one item (an Array of computergroups). That item's key is the Symbol :computer_groups
+  ###
+  ### ==== RSRC_OBJECT_KEY = [Symbol] The Hash key used for individual JSON object output.
+  ### It's also used in various error messages
+  ###
+  ### e.g. the JSON output of the resource "JSSResource/computergroups/id/436" is
+  ### a hash with one item (another hash with details of one computergroup).
+  ### That item's key is the Symbol :computer_group
+  ###
+  ### ==== VALID_DATA_KEYS = [Array<Symbol>] The Hash keys used to verify validity of :data
+  ### When instantiating a subclass using :data => somehash, some minimal checks are performed
+  ### to ensure the data is valid for the subclass
+  ###
+  ### The Symbols in this Array are compared to the keys of the hash provided.
+  ### If any of these don't exist in the hash's keys, then the :data is
+  ### not valid and an exception is raised.
+  ###
+  ### The keys :id and :name must always exist in the hash.
+  ### If only :id and :name are valid, VALID_DATA_KEYS should be an empty array.
+  ###
+  ### e.g. for a department, only :id and :name are valid, so VALID_DATA_KEYS is an empty Array ([])
+  ### but for a computer group, the keys :computers and :is_smart must be present as well.
+  ### so VALID_DATA_KEYS will be [:computers, :is_smart]
+  ###
+  ### *NOTE* Some API objects have data broken into subsections, in which case the
+  ### VALID_DATA_KEYS are expected in the section :general.
+  ###
+  class APIObject
+
+    #####################################
+    ### Mix-Ins
+    #####################################
+
+    #####################################
+    ### Class Variables
+    #####################################
+
+    ### This Hash holds the most recent API query for a list of all items in any subclass,
+    ### keyed by the subclass's RSRC_LIST_KEY. See the self.all class method.
+    ###
+    ### When the .all method is called without an argument, and this hash has
+    ### a matching value, the value is returned, rather than requerying the
+    ### API. The first time a class calls .all, or whnever refresh is
+    ### not false, the API is queried and the value in this hash is updated.
+    ###
+    @@all_items = {}
+
+    #####################################
+    ### Class Methods
+    #####################################
+
+    ###
+    ### Return an Array of Hashes for all objects of this subclass in the JSS.
+    ###
+    ### This method is only valid in subclasses of JSS::APIObject, and is
+    ### the parsed JSON output of an API query for the resource defined in the subclass's RSRC_BASE,
+    ### e.g. for JSS::Computer, with the RSRC_BASE of :computers,
+    ### This method retuens the output of the 'JSSResource/computers' resource,
+    ### which is a list of all computers in the JSS.
+    ###
+    ### Each item in the Array is a Hash with at least two keys, :id and :name.
+    ### The class methods .all_ids and .all_names provide easier access to those data
+    ### as mapped Arrays.
+    ###
+    ### Some API classes provide other data in each Hash, e.g. :udid (for computers
+    ### and mobile devices) or :is_smart (for groups).
+    ###
+    ### Subclasses implementing those API classes should provide .all_xxx
+    ### class methods for accessing those other values as mapped Arrays,
+    ### e.g. JSS::Computer.all_udids
+    ###
+    ### The results of the first query for each subclass is stored in @@all_items
+    ### and returned at every future call, so as to not requery the server every time.
+    ###
+    ### To force requerying to get updated data, provided a non-false argument.
+    ### I usually use :refresh, so that it's obvious what I'm doing, but true, 1,
+    ### or anything besides false or nil will work.
+    ###
+    ### @param refresh[Boolean] should the data be re-queried from the API?
+    ###
+    ### @return [Array<Hash{:name=>String, :id=> Integer}>]
+    ###
+    def self.all(refresh = false)
+      raise JSS::UnsupportedError, ".all can only be called on subclasses of JSS::APIObject" if self == JSS::APIObject
+      @@all_items[self::RSRC_LIST_KEY] = nil if refresh
+      return @@all_items[self::RSRC_LIST_KEY] if @@all_items[self::RSRC_LIST_KEY]
+      @@all_items[self::RSRC_LIST_KEY] = JSS::API.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
+    end
+
+    ###
+    ### Returns an Array of the JSS id numbers of all the members
+    ### of the subclass.
+    ###
+    ### e.g. When called from subclass JSS::Computer,
+    ### returns the id's of all computers in the JSS
+    ###
+    ### @param refresh[Boolean] should the data be re-queried from the API?
+    ###
+    ### @return [Array<Integer>] the ids of all items of this subclass in the JSS
+    ###
+    def self.all_ids(refresh = false)
+      self.all(refresh).map{|i| i[:id]}
+    end
+
+    ###
+    ### Returns an Array of the JSS names of all the members
+    ### of the subclass.
+    ###
+    ### e.g. When called from subclass JSS::Computer,
+    ### returns the names of all computers in the JSS
+    ###
+    ### @param refresh[Boolean] should the data be re-queried from the API?
+    ###
+    ### @return [Array<String>] the names of all item of this subclass in the JSS
+    ###
+    def self.all_names(refresh = false)
+      self.all(refresh).map{|i| i[:name]}
+    end
+
+    ###
+    ### Return a hash of all objects of this subclass
+    ### in the JSS where the key is the id, and the value
+    ### is some other key in the data items returned by the JSS::APIObject.all.
+    ###
+    ### If the other key doesn't exist in the API
+    ### data, (eg :udid for JSS::Department) the values will be nil.
+    ###
+    ### Use this method to map ID numbers to other identifiers returned
+    ### by the API list resources. Invert its result to map the other
+    ### identfier to ids.
+    ###
+    ### @example
+    ###   JSS::Computer.map_all_ids_to(:name)
+    ###
+    ###   # Returns, eg {2 => "kimchi", 5 => "mantis"}
+    ###
+    ###   JSS::Computer.map_all_ids_to(:name).invert
+    ###
+    ###   # Returns, eg {"kimchi" => 2, "mantis" => 5}
+    ###
+    ### @param other_key[Symbol] the other data key with which to associate each id
+    ###
+    ### @param refresh[Boolean] should the data  re-queried from the API?
+    ###
+    ### @return [Hash{Integer => Oject}] the associated ids and data
+    ###
+    def self.map_all_ids_to(other_key, refresh = false)
+      h = {}
+      self.all(refresh).each{|i| h[i[:id]] = i[other_key]}
+      h
+    end
+    
+    
+    ### Return an Array of JSS::APIObject subclass instances
+    ### e.g when called on JSS::Package, return all JSS::Package
+    ### objects in the JSS. 
+    ###
+    ### NOTE: This may be slow as it has to look up each object individually!
+    ### use it wisely.
+    ###
+    ### @param refresh[Boolean] should the data  re-queried from the API?
+    ###
+    ### @return [Hash{Integer => Object}] the objects requested
+    def self.all_objects(refresh = false)
+      objects_key = "#{self::RSRC_LIST_KEY}_objects".to_sym
+      @@all_items[objects_key] = nil if refresh
+      return @@all_items[objects_key] if @@all_items[objects_key]
+      @@all_items[objects_key] = self.all(refresh = false).map{|o| self.new :id => o[:id]}      
+    end
+    
+    
+    
+    ###
+    ### Convert an Array of Hashes of API object data to a
+    ### REXML element.
+    ###
+    ### Given an Array of Hashes of items in the subclass
+    ### where each Hash has at least an :id  or a :name key,
+    ### (as what comes from the .all class method)
+    ### return a REXML <classes> element
+    ### with one <class> element per Hash member.
+    ###
+    ### @example
+    ###   # for class JSS::Computer
+    ###   some_comps = [{:id=>2, :name=>"kimchi"},{:id=>5, :name=>"mantis"}]
+    ###   xml_names = JSS::Computer.xml_list some_comps
+    ###   puts xml_names  # output manually formatted for clarity, xml.to_s has no newlines between elements
+    ###
+    ###   <computers>
+    ###     <computer>
+    ###       <name>kimchi</name>
+    ###     </computer>
+    ###     <computer>
+    ###       <name>mantis</name>
+    ###     </computer>
+    ###   </computers>
+    ###
+    ###   xml_ids = JSS::Computer.xml_list some_comps, :id
+    ###   puts xml_names  # output manually formatted for clarity, xml.to_s has no newlines between elements
+    ###
+    ###   <computers>
+    ###     <computer>
+    ###       <id>2</id>
+    ###     </computer>
+    ###     <computer>
+    ###       <id>5</id>
+    ###     </computer>
+    ###   </computers>
+    ###
+    ### @param array[Array<Hash{:name=>String, :id =>Integer, Symbol=>#to_s}>] the Array of subclass data to convert
+    ###
+    ### @param content[Symbol] the Hash key to use as the inner element for each member of the Array
+    ###
+    ### @return [REXML::Element] the XML element representing the data
+    ###
+    def self.xml_list(array, content = :name)
+      JSS.item_list_to_rexml_list self::RSRC_LIST_KEY, self::RSRC_OBJECT_KEY, array, content
+    end
+
+    ###
+    ### Some API objects contain references to other API objects. Usually those
+    ### references are a Hash containing the :id and :name of the target. Sometimes,
+    ### however the reference is just the name of the target.
+    ###
+    ### A Script has a property :category, which comes from the API as
+    ### a String, the name of the category for that script. e.g. "GoodStuff"
+    ###
+    ### A Policy also has a property :category, but it comes from the API as a Hash
+    ### with both the name and id, e.g.  !{:id => 8, :name => "GoodStuff"}
+    ###
+    ### When that reference is to a single thing (like the category to which something belongs)
+    ### APIObject subclasses usually store only the name, and use the name when
+    ### returning data to the API.
+    ###
+    ### When an object references a list of related objects
+    ### (like the computers assigned to a user) that list will be and Array of Hashes
+    ### as above, with both the :id and :name
+    ###
+    ###
+    ### This method is just a handy way to extract the name regardless of how it comes
+    ### from the API. Most APIObject subclasses use it in their #initialize method
+    ###
+    ### @param a_thing[String,Array] the api data from which we're extracting the name
+    ###
+    ### @return [String] the name extracted from a_thing
+    ###
+    def self.get_name(a_thing)
+      case a_thing
+        when String
+          a_thing
+        when Hash
+          a_thing[:name]
+        when nil
+          nil
+      end
+    end
+
+    #####################################
+    ### Class Constants
+    #####################################
+
+    ###
+    ### These Symbols are added to VALID_DATA_KEYS for performing the
+    ### :data validity test described above.
+    ###
+    REQUIRED_DATA_KEYS = [:id, :name]
+
+    ###
+    ### By default, these keys are available for object lookups
+    ### Others can be added by subclasses using an array of them
+    ### as the second argument to super(initialize)
+    ### The keys must be Symbols that  match the keyname in the resource url.
+    ### e.g. :serialnumber  for JSSResource/computers/serialnumber/xxxxx
+    ###
+    DEFAULT_LOOKUP_KEYS = [:id, :name]
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    ### @return [Integer] the JSS id number
+    attr_reader :id
+
+    ### @return [String] the name
+    attr_reader :name
+
+    ### @return [Boolean] is it in the JSS?
+    attr_reader :in_jss
+
+    ### @return [String] the Rest resource for API access (the part after "JSSResource/" )
+    attr_reader :rest_rsrc
+
+    #####################################
+    ### Constructor
+    #####################################
+
+    ###
+    ### The args hash must include :id, :name, or :data.
+    ### * :id or :name will be looked up via the API
+    ### * * if the subclass includes JSS::Creatable, :id can be :new, to create a new object in the JSS.
+    ###     and :name is required
+    ### * :data must be the JSON output of a separate {JSS::APIConnection} query (a Hash of valid object data)
+    ###
+    ### Some subclasses can accept other options, by pasing their keys in a final Array
+    ###
+    ### @param args[Hash] the data for looking up, or constructing, a new object.
+    ###
+    ### @option args :id[Integer] the jss id to look up
+    ###
+    ### @option args :name[String] the name to look up
+    ###
+    ### @option args :data[Hash] the JSON output of a separate {JSS::APIConnection} query
+    ###
+    ### @param other_lookup_keys[Array<Symbol>] Hash keys other than :id and :name, by which an API
+    ###   lookup may be performed.
+    ###
+    def initialize(args = {}, other_lookup_keys = [])
+
+      ################################
+      ################################
+      ####### Previously looked-up JSON data
+      if args[:data]
+
+        @init_data = args[:data]
+        ### Does this data come in subsets?
+        @got_subsets = @init_data[:general].kind_of?(Hash)
+
+        ### data must include all they keys in REQUIRED_DATA_KEYS + VALID_DATA_KEYS
+        ### in either the main hash keys or the :general sub-hash, if it exists
+        hash_to_check = @got_subsets ? @init_data[:general] : @init_data
+        combined_valid_keys = self.class::REQUIRED_DATA_KEYS + self.class::VALID_DATA_KEYS
+        keys_ok = (hash_to_check.keys & combined_valid_keys).count == combined_valid_keys.count
+        raise JSS::InvalidDataError, ":data is not valid JSON for a #{self.class::RSRC_OBJECT_KEY} from the API. It needs at least the keys :#{combined_valid_keys.join ', :'}" unless keys_ok
+
+        ### and the id must be in the jss
+        raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} with JSS id: #{@init_data[:id]}" unless  self.class.all_ids.include? hash_to_check[:id]
+
+
+      ################################
+      ################################
+      ###### Make a new one in the JSS, but only if we've included the Creatable module
+      elsif args[:id] == :new
+
+        raise JSS::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless defined? self.class::CREATABLE
+
+        raise JSS::MissingDataError, "You must provide a :name for a new #{self.class::RSRC_OBJECT_KEY}." unless args[:name]
+
+        raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" if self.class.all_names.include? args[:name]
+
+
+        ### NOTE: subclasses may want to pre-populate more keys in @init_data when :id == :new
+        ### then parse them into attributes later.
+        @name = args[:name]
+        @init_data = {:name => args[:name]}
+        @in_jss = false
+        @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{URI.escape @name}"
+        @need_to_update = true
+        return
+
+      ################################
+      ################################
+      ###### Look up the data via the API
+      else
+        ### what lookup key are we using?
+        combined_lookup_keys = self.class::DEFAULT_LOOKUP_KEYS + other_lookup_keys
+        lookup_key = (combined_lookup_keys & args.keys)[0]
+
+        raise JSS::MissingDataError, "Args must include :#{combined_lookup_keys.join(', :')}, or :data"  unless lookup_key
+
+        rsrc = "#{self.class::RSRC_BASE}/#{lookup_key}/#{args[lookup_key]}"
+
+        begin
+          @init_data = JSS::API.get_rsrc(rsrc)[self.class::RSRC_OBJECT_KEY]
+
+          ### If we're looking up by id or name and we're here,
+          ### then we have it regardless of which subset it's in
+          ### otherwise, first assume they are in the init hash
+          @id = lookup_key == :id ? args[lookup_key] : @init_data[:id]
+          @name = lookup_key == :name ? args[lookup_key] : @init_data[:name]
+
+        rescue RestClient::ResourceNotFound
+          raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching: #{args[:name] ? args[:name] : args[:id]}"
+        end
+      end ## end arg parsing
+
+      # Find the "main" subset which contains :id and :name
+      #
+      # If they aren't at the top-level of the init hash they are in a subset hash,
+      # usually :general, but sometimes someething else,
+      # like ldap servers, which have them in :connection
+      # Whereever both :id and :name are, that's the main subset
+
+      @init_data.keys.each do |subset|
+        @main_subset = @init_data[subset] if @init_data[subset].kind_of? Hash and @init_data[subset][:id] and @init_data[subset][:name]
+        break if @main_subset
+      end
+      @main_subset ||= @init_data
+
+      @id ||= @main_subset[:id]
+      @name ||= @main_subset[:name]
+
+      # many things have  a :site
+      if @main_subset[:site]
+        @site = JSS::APIObject.get_name( @main_subset[:site])
+      end 
+      
+      # many things have a :category
+      if @main_subset[:category]
+        @category = JSS::APIObject.get_name( @main_subset[:category]) 
+      end
+      
+      # set empty strings to nil
+      @init_data.jss_nillify! '', :recurse
+
+      @in_jss = true
+      @rest_rsrc =  "#{self.class::RSRC_BASE}/id/#{@id}"
+      @need_to_update = false
+    end # init
+
+    #####################################
+    ### Public Instance Methods
+    #####################################
+
+    ###
+    ### Either Create or Update this object in the JSS
+    ###
+    ### If this item is creatable or updatable, then
+    ### create it if needed, or update it if it already exists.
+    ###
+    ### @return [Integer] the id of the item created or updated
+    ###
+    def save
+      if @in_jss
+        raise JSS::UnsupportedError, "Updating this object in the JSS is currently not supported" \
+          unless defined? self.class::UPDATABLE
+        return self.update
+      else
+        raise JSS::UnsupportedError, "Creating this object in the JSS is currently not supported" \
+          unless defined? self.class::CREATABLE
+        return self.create
+      end
+    end
+
+
+    ###
+    ### Delete this item from the JSS.
+    ###
+    ### Subclasses may want to redefine this method,
+    ### first calling super, then setting other attributes to
+    ### nil, false, empty, etc..
+    ###
+    ### @return [void]
+    ###
+    def delete
+      return nil unless @in_jss
+      JSS::API.delete_rsrc @rest_rsrc
+      @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{URI.escape @name}"
+      @id = nil
+      @in_jss = false
+      @need_to_update = false
+    end # delete
+
+    #####################################
+    ### Private Instance Methods
+    #####################################
+    private
+
+    ###
+    ### Return a String with the XML Resource
+    ### for submitting creation or changes to the JSS via
+    ### the API via the Creatable or Updatable modules
+    ###
+    ### Most classes will redefine this method.
+    ###
+    def rest_xml
+      doc = REXML::Document.new APIConnection::XML_HEADER
+      tmpl = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
+      tmpl.add_element('name').text = @name
+      return doc.to_s
+    end
+
+    
+    ### Aliases
+    
+    alias in_jss? in_jss
+    
+  end # class APIObject
+
+
+
+end # module JSS
+
+### Mix-in Sub Modules
+require "jss/api_object/creatable"
+require "jss/api_object/uploadable"
+require "jss/api_object/locatable"
+require "jss/api_object/matchable"
+require "jss/api_object/purchasable"
+require "jss/api_object/updatable"
+require "jss/api_object/extendable"
+
+### Mix-in Sub Modules with Classes
+require "jss/api_object/criteriable"
+require "jss/api_object/scopable"
+
+### APIObject SubClasses with SubClasses
+require "jss/api_object/advanced_search"
+require "jss/api_object/extension_attribute"
+require "jss/api_object/group"
+
+### APIObject SubClasses without SubClasses
+require "jss/api_object/building"
+require "jss/api_object/category"
+require "jss/api_object/computer"
+require "jss/api_object/department"
+require "jss/api_object/distribution_point"
+require "jss/api_object/ldap_server"
+require "jss/api_object/mobile_device"
+require "jss/api_object/netboot_server"
+require "jss/api_object/network_segment"
+require "jss/api_object/package"
+require "jss/api_object/peripheral_type"
+require "jss/api_object/peripheral"
+require "jss/api_object/policy"
+require "jss/api_object/removable_macaddr"
+require "jss/api_object/script"
+require "jss/api_object/site"
+require "jss/api_object/software_update_server"
+require "jss/api_object/user"
+