ruby-jss 0.8.2 → 0.9.0.b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ba0289a3600d2d044211e9b13ee210fb6c10b7a2
-  data.tar.gz: 647f502e548e3f86345ce9992e20ec26fbe1a273
+  metadata.gz: 770c1a47f03a6f98144c8ad351559817416166fb
+  data.tar.gz: 8271b37e6692aef2f4005f3bbf043964c3d9b5c9
 SHA512:
-  metadata.gz: dfebb20f13d49cd7677bc9e5fbb47ab668d5a98640cfdd3a4e97852c2cd22189c563cad9759972c5932e047ab31fdeb3cad9dce84c80c67f7e9c7e33f1f8d0f8
-  data.tar.gz: fb8761e60f48733df1f6047a4b1b324a1ece25d6c7dad6693b2a162cdd08d981921df20efb475716996f887b43f10b4c17c5029146387ca528199da9c3583950
+  metadata.gz: c642a052e9e1a5aa68e4ffcf9a22cb53a367ebe7be09a3c67dc15681605ccc7eb66a85813ca7c3bbf0b8b25ed4840931f48e18954ead42946c1409e0b3c4b21f
+  data.tar.gz: a07ceac28ddb3fd6f4c241940e0ee93ce6ba77f9ec750b0dcbe588f7417f5602bff76deb2676913743e6497e9e62ccd8cc748a193721a4e6c68ce2c9e5c839ae

data/CHANGES.md

@@ -1,6 +1,42 @@
 # Change History
 
-## v0.8.1 2017-06-07
+## v0.9.0
+
+- Add: JSS::MobileDevice.all_apple_tvs class method
+- Add: JSS::MobileDevice.management_history method, and related methods in instances
+- Add: JSS::MobileDevice.send_mdm_command has been expanded to handle all MDM commands supported by the API *except* Wallpaper and PasscodeLockGracePeriod (some day soon hopefully)
+- Improvement: JSS::RestrictedSoftware class is now Creatable and Updatable.
+- Add: JSS::Server instances (as found in the JSS::APIConnection.server attribute) now have methods #activation_code and
+  #organization
+- Add: JSS::Computer now can send MDM commands to instances via #blank_push #device_lock #erase_device and #remove_mdm_profile, or to
+  arrays of computer identifiers using the JSS::Computer.send_mdm_command method.
+- Add: JSS::Computer now has class methods to retrieve the server-wide .inventory_collection_settings and
+  .checkin_settings
+- Add: JSS::Computer instances now have access to the data in the History tab of the computer details page in
+  the WebUI. Subset-specific methods are #usage_logs, #audits, #policy_logs, #completed_policies, #failed_policies, #casper_remote_logs, #screen_sharing_logs, #casper_imaging_logs, #user_location_history, and #app_store_history
+- Add: JSS::Computer instances now have an #application_usage method which takes a date range and returns an
+  array of usage data.
+- Add: JSS::Computer instances now have access to their 'management data' (the stuff in the Management tab of
+  the Computer details in the WebUI).  As well as the #management_data method, there are shortcut methods for the subsets: #smart_groups, #static_groups, & #patch_titles and in-scope items like:  #policies, #configuration_profiles, #ebooks, #app_store_apps, #restricted_software
+- Fix: issue with handling of params to APIObject.make
+- Improvement: APIObject.fetch can be given a single value, which will be compared to the subclass's .all_ids,
+  .all_names, and other list methods for the various lookup keys, and if a match is found, the object is returned. E.g. instead of
+  JSS::Computer.fetch name: 'foo'  you can just use JSS::Computer.fetch 'foo'.
+  Note that specifying the lookup key is always faster.
+- Improvement: the OTHER_LOOKUP_KEYS constants of APIObject subclasses can now reconize variations on a key, e.g. :serialnumber and
+    :serial_number, or :macaddress and :mac_address
+- Improvement: Support for multiple APIConnection instances - you can connect to more than one server at a time and switch between them.
+- Improvement: APIConnection connection settings come first from the #connect params, then from Configuration,
+  then from the Client setting (if the machine is a client), then from the module defaults
+- Improvement: APIConnection can now take an xml payload with #delete_rsrc
+- Improvement: JSS::Policy instances can now flush their logs
+- Improvement: JSS::Policy now has setters for server_side_activation and server_side_expriation.
+
+## v0.8.3 2017-06-07
+
+- Fix: Version parsing: empty version parts default to 0, e.g. 10.2 parses as 10.2.0
+
+## v0.8.2 2017-06-07
 
 - Fix: Some objects failed to locate their 'main subset' (the chunk of API data that contains the object name and id) correctly.
 - Fix: Some versions of Gem::Version don't like dashes (which are part of SemVers).

data/README.md

@@ -51,10 +51,10 @@ Hopefully others will find it useful, and add more to it as well.
 ## SYNOPSIS
 
 ```ruby
-require 'jss'
+require 'ruby-jss'
 
 # Connect to the API
-JSS::API.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
+JSS.api.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
 
 # get an array of basic data about all JSS::Package objects in the JSS:
 pkgs = JSS::Package.all
@@ -99,11 +99,11 @@ ns.save
 Before you can work with JSS Objects via the API, you have to connect to it.
 
 The constant {JSS::API} contains the connection to the API (a singleton instance of {JSS::APIConnection}). When the JSS Module is first loaded, it isn't
-connected.  To remedy that, use JSS::API.connect, passing it values for the connection. In this example, those values are stored
+connected.  To remedy that, use JSS.api_connection.connect, passing it values for the connection. In this example, those values are stored
 in the local variables jss_user, jss_user_pw, and jss_server_hostname, and others are left as default.
 
 ```ruby
-JSS::API.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
+JSS.api_connection.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
 ```
 
 Make sure the user has privileges in the JSS to do things with desired Objects.
@@ -111,7 +111,7 @@ Make sure the user has privileges in the JSS to do things with desired Objects.
 The {JSS::API#connect} method also accepts the symbols :stdin and :prompt as values for :pw, which will cause it to read the
 password from stdin, or prompt for it in the shell. See the {JSS::APIConnection} class for more connection options and details about its methods.
 
-Also see {JSS::Configuration}, and the [CONFIGURATION](#configuration) section below, for how to store
+Also see JSS::Configuration, and the [CONFIGURATION](#configuration) section below, for how to store
 server connection parameters in a simple config file.
 
 ### Working with JSS Objects (a.k.a REST Resources)
@@ -164,7 +164,7 @@ Some Objects can be created anew in the JSS via ruby. To do so, first make a Rub
 ```ruby
 new_pkg = JSS::Package.make name: "transmogrifier-2.3-1.pkg"
 ```
-*NOTE*: some classes require more data than just a :name when created with .create.
+*NOTE*: some classes require more data than just a :name when created with .make.
 
 Then set the attributes of the new object as needed
 
@@ -236,6 +236,7 @@ See each Class's documentation for details.
 * {JSS::Peripheral}
 * {JSS::PeripheralType}
 * {JSS::RemovableMacAddress}
+* {JSS::RestrictedSoftware}
 * {JSS::Script}
 * {JSS::Site}
 * {JSS::User}
@@ -282,7 +283,6 @@ These must be created and edited via the JSS WebApp
 * {JSS::DistributionPoint}
 * {JSS::LDAPServer}
 * {JSS::NetBootServer}
-* {JSS::RestrictedSoftware}
 * {JSS::SoftwareUpdateServer}
 
 ### Deletable
@@ -291,7 +291,7 @@ All supported API Objects can be deleted
 
 Other useful classes:
 
-* {JSS::APIConnect} - An object representing the connection to the REST API
+* {JSS::APIConnection} - An object representing the connection to the REST API
 * {JSS::DBConnection} - An object representing the connection to MySQL database, if used
 * {JSS::Server} - An encapsulation of some info about the JamfPro server, such as the version and license. An instance is available as an attribute of the {JSS::APIConnection} singleton.
 * {JSS::Client} - An object representing the local machine as a Casper-managed client, and JAMF-related info and methods
@@ -301,7 +301,7 @@ Other useful classes:
 
 The {JSS::Configuration} singleton class is used to read, write, and use site-specific defaults for the JSS module. When the Module is required, the single instance of {JSS::Configuration} is created and stored in the constant {JSS::CONFIG}. At that time the system-wide file /etc/jss_gem.conf is examined if it exists, and the items in it are loaded into the attributes of {JSS::CONFIG}. The user-specific file ~/.jss_gem.conf then is examined if it exists, and any items defined there will override those values from the system-wide file.
 
-The values defined in those files are used as defaults throughout the module. Currently, those values are only related to establishing the API connection. For example, if a server name is defined, then a :server does not have to be specified when calling {JSS::API#connect}. Values provided explicitly when calling JSS::API.connect will override the config values.
+The values defined in those files are used as defaults throughout the module. Currently, those values are only related to establishing the API connection. For example, if a server name is defined, then a :server does not have to be specified when calling {JSS::API#connect}. Values provided explicitly when calling JSS.api_connection.connect will override the config values.
 
 While the {JSS::Configuration} class provides methods for changing the values, saving the files, and re-reading them, or reading an arbitrary file, the files are text files with a simple format, and can be created by any means desired. The file format is one attribute per line, thus:
 
@@ -326,11 +326,11 @@ api_username: readonly-api-user
 api_verify_cert: false
 ```
 
-and then any calls to {JSS::API.connect} will assume that server and username, and won't complain about the self-signed certificate.
+and then any calls to {JSS.api_connection.connect} will assume that server and username, and won't complain about the self-signed certificate.
 
 ### Passwords
 
-The config files don't store passwords and the {JSS::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the JSS::API.connect call.
+The config files don't store passwords and the {JSS::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the JSS.api_connection.connect call.
 
 The {JSS::API#connect} method also accepts the symbols :stdin# and :prompt as values for the :pw argument, which will cause it to read the password from a line of stdin, or prompt for it in the shell.
 
@@ -340,7 +340,7 @@ Here's an example of how to use a password stored in a file:
 
 ```ruby
 password = File.read "/path/to/secure/password/file" # read the password from a file
-JSS::API.connect pw: password   # other arguments used from the config settings
+JSS.api_connection.connect pw: password   # other arguments used from the config settings
 ```
 
 And here's an example of how to read a password from a web server and use it.
@@ -348,12 +348,12 @@ And here's an example of how to read a password from a web server and use it.
 ```ruby
 require 'open-uri'
 password =  open('https://server.org.org/path/to/password').read
-JSS::API.connect pw: password   # other arguments used from the config settings
+JSS.api_connection.connect pw: password   # other arguments used from the config settings
 ```
 
 ## BEYOND THE API
 
-While the Casper API provides access to object data in the JSS, this gem tries to use that data to provide more than just information exchange. Here are some examples of how we use the API data to provide functionality found in various Casper tools:
+While the Jamf Pro API provides access to object data in the JSS, this gem tries to use that data to provide more than just information exchange. Here are some examples of how we use the API data to provide functionality found in various Casper tools:
 
 * Client Machine Access
   * The {JSS::Client} module provides the ability to run jamf binary commands, and access the local cache of package receipts
@@ -375,7 +375,7 @@ While the Casper API provides access to object data in the JSS, this gem tries t
 
 ## REQUIREMENTS
 
-the JSS gem was written for:
+ruby-jss was written for:
 
 * Mac OS X 10.9 or higher
 * Ruby 2.0 or higher

data/bin/cgrouper

@@ -191,7 +191,7 @@ class App
     raise JSS::MissingDataError, "No JSS Username provided or found in the JSS gem config." unless @options.user
     raise JSS::MissingDataError, "No JSS Server provided or found in the JSS gem config." unless @options.server
 
-    JSS::API.connect( :server => @options.server,
+    JSS.api_connection.connect( :server => @options.server,
       :port => @options.port,
       :verify_cert => @options.verify_cert,
       :user => @options.user,

data/bin/netseg-update

@@ -148,7 +148,7 @@ class App
   end # run
 
   def connect_to_jss
-    JSS::API.connect(
+    JSS.api_connection.connect(
       server: @server,
       port: @port,
       verify_cert: @verify_cert,

data/lib/jss/api_connection.rb

@@ -37,18 +37,129 @@ module JSS
   # Classes
   #####################################
 
-  # An API connection to the JSS.
+  # Instances of this class represent 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.
+  # JSS::APIConnection objects are REST connections to JSS APIs and contain
+  # (once connected) all the data needed for communication with
+  # that API, including login credentials, URLs, and so on.
   #
-  # 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.
+  # == The default connection
   #
-  # To access the underlying RestClient::Resource instance,
-  # use JSS::API.cnx
+  # When ruby-jss is loaded, a not-yet-connected default instance of
+  # JSS::APIConnection is created, activated, and stored internally.
+  # Before using it you must call its {#connect} method, passing in appropriate
+  # connection details and credentials.
+  #
+  # Here's how to use the default connection:
+  #
+  #   require 'ruby-jss'
+  #   JSS.api.connect server: 'server.address.edu', user: 'jss-api-user', pw: :prompt
+  #
+  # (see {JSS::APIConnection#connect} for all the connection options)
+  #
+  # If you're only going to be connecting to one server, or one at a time,
+  # using the default connection is preferred. You can call its {#connect}
+  # method at any time to change servers or connection credentials.
+  #
+  # == Multiple connections & the currently active connection
+  #
+  # Sometimes you need to connect simultaneously to more than one JSS.
+  # or to the same JSS with different credentials.
+  #
+  # While multiple connection instances can be created, only one is active at
+  # a time and all API access happens through the currently active connection.
+  # (See below for how to switch between different connections)
+  #
+  # The currently-active connection instance is available from the
+  # `JSS.api` method.
+  #
+  # == Making new connection instances
+  #
+  # New connections can be created and stored in a variable using
+  # the standard ruby 'new' method.
+  #
+  # If you provide connection details when calling 'new', they will be passed
+  # to the #connect method immediately.
+  #
+  #   production_api = JSS::APIConnection.new(
+  #     name: 'prod',
+  #     server: 'prodserver.address.org',
+  #     user: 'produser',
+  #     pw: :prompt
+  #   )
+  #
+  #   # the new connection is now stored in the variable 'production_api'.
+  #
+  # == Switching between multiple connections
+  #
+  # Only one connection is active at a time and the currently active one is
+  # returned when you call `JSS.api` or its aliases `JSS.api_connection` or
+  # `JSS.connection`
+  #
+  # To activate another connection just pass it to the JSS.use_api method like so:
+  #   JSS.use_api production_api
+  #   # the connection we stored in 'production_api' is now active
+  #
+  # To re-activate to the default connection, just call
+  #   JSS.use_default_connection
+  #
+  # NOTE:
+  # The APIObject list methods (e.g. JSS::Computer.all) cache the list
+  # data from the API the first time they are used, and after that when
+  # their 'refresh' option is true.
+  #
+  # Those caches are stored in the APIConnection instance through-
+  # which they were read, so they won't be incorrect when you switch
+  # connections.
+  #
+  # == Connection Names:
+  #
+  # As seen in the example above, you can provide a 'name:' parameter
+  # (a String or a Symbol) when creating a new connection. The name can be
+  # used later to identify connection objects.
+  #
+  # If you don't provide one, the name is ':disconnected' until you
+  # connect, and then 'user@server:port' after connecting.
+  #
+  # The name of the default connection is always :default
+  #
+  # To see the name of the currently active connection, just use `JSS.api.name`
+  #
+  #   JSS.use_api production_api
+  #   JSS.api.name  # => 'prod'
+  #
+  #   JSS.use_default_connection
+  #   JSS.api.name  # => :default
+  #
+  # == Creating, Storing and Activating a connection in one step
+  #
+  # Both of the above steps (creating/storing a connection, and making it
+  # active) can be performed in one step using the
+  # `JSS.new_api_connection` method, which creates a new APIConnection, makes it
+  # the active connection, and returns it.
+  #
+  #    production_api2 = JSS.new_api_connection(
+  #      name: 'prod2',
+  #      server: 'prodserver.address.org',
+  #      user: 'produser',
+  #      pw: :prompt
+  #    )
+  #
+  #   JSS.api.name  # => 'prod2'
+  #
+  # == Low-level use of APIConnection instances.
+  #
+  # For most uses, creating, activating, and connecting APIConnection instances
+  # is all you'll need. However to access API resources that aren't yet
+  # implemented in other parts of ruby-jss, you can use the methods
+  # {#get_rsrc}, {#put_rsrc}, {#post_rsrc}, & {#delete_rsrc}
+  # documented below.
+  #
+  # For even lower-level work, you can access the underlying RestClient::Resource
+  # inside the APIConnection via the connection's {#cnx} attribute.
+  #
+  # APIConnection instances also have a {#server} attribute which contains an
+  # instance of {JSS::Server} q.v., representing the JSS to which it's connected.
   #
   class APIConnection
 
@@ -117,13 +228,41 @@ module JSS
     # @return [String] The base URL to to the current REST API
     attr_reader :rest_url
 
+    # @return [String,Symbol] an arbitrary name that can be given to this
+    # connection during initialization, using the name: parameter.
+    # defaults to user@hostname:port
+    attr_reader :name
+
+    # @return [Hash]
+    # This Hash holds the most recent API query for a list of all items in any
+    # APIObject subclass, keyed by the subclass's RSRC_LIST_KEY.
+    # See the APIObject.all class method.
+    #
+    # When the APIObject.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.
+    attr_reader :object_list_cache
+
     # Constructor
     #####################################
 
-    # To connect, use JSS::API.connect
+    # If name: is provided (as a String or Symbol) that will be
+    # stored as the APIConnection's name attribute.
+    #
+    # For other available parameters, see {#connect}.
+    #
+    # If they are provided, they will be used to establish the
+    # connection immediately.
+    #
+    # If not, you must call {#connect} before accessing the API.
     #
-    def initialize
+    def initialize(args = {})
+      @name = args.delete :name
+      @name ||= :disconnected
       @connected = false
+      @object_list_cache = {}
+      connect args unless args.empty?
     end # init
 
     # Instance Methods
@@ -175,6 +314,7 @@ module JSS
 
       verify_server_version
 
+      @name = "#{@jss_user}@#{@server_host}:#{@port}" if @name.nil? || @name == :disconnected
       @connected ? hostname : nil
     end # connect
 
@@ -237,7 +377,8 @@ module JSS
     # @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
+      # puts object_id
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS.api.connect first.' unless @connected
       rsrc = URI.encode rsrc
       @last_http_response = @cnx[rsrc].get(accept: format)
       return JSON.parse(@last_http_response, symbolize_names: true) if format == :json
@@ -252,7 +393,7 @@ module JSS
     # @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
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS.api_connection.connect first.' unless @connected
 
       # convert CRs & to 
       xml.gsub!(/\r/, '
')
@@ -271,11 +412,11 @@ module JSS
     #
     # @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
+    def post_rsrc(rsrc, xml = '')
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS.api_connection.connect first.' unless @connected
 
       # convert CRs & to 
-      xml.gsub!(/\r/, '
')
+      xml.gsub!(/\r/, '
') if xml
 
       # send the data
       @last_http_response = @cnx[rsrc].post xml, content_type: 'text/xml', accept: :json
@@ -289,10 +430,13 @@ module JSS
     #
     # @return [String] the xml response from the server.
     #
-    def delete_rsrc(rsrc)
-      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS::API.connect first.' unless @connected
+    def delete_rsrc(rsrc, xml = nil)
+      raise JSS::InvalidConnectionError, 'Not Connected. Use JSS.api_connection.connect first.' unless @connected
       raise MissingDataError, 'Missing :rsrc' if rsrc.nil?
 
+      # payload?
+      return delete_with_payload rsrc, xml if xml
+
       # delete the resource
       @last_http_response = @cnx[rsrc].delete
     end # delete_rsrc
@@ -352,14 +496,29 @@ module JSS
     ####################################
     private
 
-    # Apply defaults from the JSS::CONFIG, the JSS::Client
-    # or the module defaults to the args for the #connect method
+    # Apply defaults from the JSS::CONFIG,
+    # then from the JSS::Client,
+    # then from the module defaults
+    # to the args for the #connect method
     #
     # @param args[Hash] The args for #connect
     #
     # @return [Hash] The args with defaults applied
     #
     def apply_connection_defaults(args)
+      apply_defaults_from_config(args)
+      apply_defaults_from_client(args)
+      apply_module_defaults(args)
+    end
+
+    # Apply defaults from the JSS::CONFIG
+    # to the args for the #connect method
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [Hash] The args with defaults applied
+    #
+    def apply_defaults_from_config(args)
       # settings from config if they aren't in the args
       args[:server] ||= JSS::CONFIG.api_server_name
       args[:port] ||= JSS::CONFIG.api_server_port
@@ -371,12 +530,32 @@ module JSS
       # if verify cert was not in the args, get it from the prefs.
       # We can't use ||= because the desired value might be 'false'
       args[:verify_cert] = JSS::CONFIG.api_verify_cert if args[:verify_cert].nil?
+      args
+    end # apply_defaults_from_config
 
+    # Apply defaults from the JSS::Client
+    # to the args for the #connect method
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [Hash] The args with defaults applied
+    #
+    def apply_defaults_from_client(args)
+      return unless JSS::Client.installed?
       # these settings can come from the jamf binary config, if this machine is a JSS client.
       args[:server] ||= JSS::Client.jss_server
       args[:port] ||= JSS::Client.jss_port
-      args[:use_ssl] ||= JSS::Client.jss_protocol.end_with? 's'
+      args[:use_ssl] ||= JSS::Client.jss_protocol.to_s.end_with? 's'
+      args
+    end
 
+    # Apply the module defaults to the args for the #connect method
+    #
+    # @param args[Hash] The args for #connect
+    #
+    # @return [Hash] The args with defaults applied
+    #
+    def apply_module_defaults(args)
       # defaults from the module if needed
       args[:port] ||= args[:use_ssl] ? SSL_PORT : HTTP_PORT
       args[:timeout] ||= DFT_TIMEOUT
@@ -410,7 +589,18 @@ module JSS
     #
     def verify_server_version
       @connected = true
-      @server = JSS::Server.new
+
+      # the jssuser resource is readable by anyone with a JSS acct
+      # regardless of their permissions.
+      # However, it's marked as 'deprecated'. Hopefully jamf will
+      # keep this basic level of info available for basic authentication
+      # and JSS version checking.
+      begin
+        @server = JSS::Server.new get_rsrc('jssuser')[:user]
+      rescue RestClient::Unauthorized, RestClient::Request::Unauthorized
+        raise JSS::AuthenticationError, "Incorrect JSS username or password for '#{JSS.api_connection.jss_user}@#{JSS.api_connection.server_host}'."
+      end
+
       min_vers = JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
       return unless @server.version < min_vers
       err_msg = "JSS version #{@server.raw_version} to low. Must be >= #{min_vers}"
@@ -485,9 +675,101 @@ module JSS
       raise JSS::ConflictError, conflict_reason
     end
 
-  end # class JSSAPIConnection
+    # RestClient::Resource#delete doesn't take an HTTP payload,
+    # but some JSS API resources require it (notably, logflush).
+    #
+    # This method uses RestClient::Request#execute
+    # to do the same thing that RestClient::Resource#delete does, but
+    # adding the payload.
+    #
+    # @param rsrc[String] the sub-resource we're DELETEing
+    #
+    # @param payload[String] The XML to be passed with the DELETE
+    #
+    # @param additional_headers[Type] See RestClient::Request#execute
+    #
+    # @param &block[Type] See RestClient::Request#execute
+    #
+    # @return [String] the XML response from the server.
+    #
+    def delete_with_payload(rsrc, payload, additional_headers = {}, &block)
+      headers = (@cnx.options[:headers] || {}).merge(additional_headers)
+      @last_http_response = RestClient::Request.execute(
+        @cnx.options.merge(
+          method: :delete,
+          url: @cnx[rsrc].url,
+          payload: payload,
+          headers: headers
+        ),
+        &(block || @block)
+      )
+    end # delete_with_payload
+
+  end # class APIConnection
+
+  # Create a new APIConnection object and use it for all
+  # future API calls. If connection options are provided,
+  # they are passed to the connect method immediately, otherwise
+  # JSS.api.connect must be called before attemting to use the
+  # connection.
+  #
+  # @param (See JSS::APIConnection#connect)
+  #
+  # @return [APIConnection] the new, active connection
+  #
+  def self.new_api_connection(args = {})
+    @api = APIConnection.new args
+    @api
+  end
+
+  # Switch the connection used for all API interactions to the
+  # one provided. See {JSS::APIConnection} for details and examples
+  # of using multiple connections
+  #
+  # @param connection [APIConnection] The APIConnection to use for future
+  #   API calls. If omitted, use the default connection created when ruby-jss
+  #   was loaded (which may or may not yet be connected)
+  #
+  # @return [APIConnection] The connection now being used.
+  #
+  def self.use_api_connection(connection)
+    raise 'API connections must be instances of JSS::APIConnection' unless connection.is_a? JSS::APIConnection
+    @api = connection
+  end
+
+  # Make the default connection (Stored in JSS::API) active
+  #
+  # @return [void]
+  #
+  def self.use_default_connection
+    use_api_connection API
+  end
+
+  # The currently active JSS::APIConnection instance.
+  #
+  # @return [JSS::APIConnection]
+  #
+  def self.api
+    @api
+  end
+
+  # aliases of module methods
+  class << self
+    alias api_connection api
+    alias connection api
+
+    alias new_connection new_api_connection
+    alias new_api new_api_connection
+
+    alias use_api use_api_connection
+    alias use_connection use_api_connection
+  end
+
+  # create the default connection
+  new_api_connection(name: :default) unless @api
 
-  # The default APIConnection
-  API = APIConnection.new
+  # Save the default connection in the API constant,
+  # mostly for backward compatibility.
+  API = @api unless defined? API
 
 end # module