ruby-jss 0.10.2 → 0.11.0a5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ebd3ed57a6244c6f97239f18b8f297a1c638c333
-  data.tar.gz: c80c3542d2a455decccb50275ab772a3dc320776
+  metadata.gz: 9c9db6dbef7526403d486b5e511d1a78a6d1e459
+  data.tar.gz: 6f5672d8d22feda70b4c9a7684ca73b2e64bdcaa
 SHA512:
-  metadata.gz: fb254e9ca0b1b5c990f503bc6a587e5d140b5406e785b74052bd0ad12ee4842695d41dc30dd4af8bc4def64900204e11293a5b27fccf6704ac76d48796b28fe2
-  data.tar.gz: f0ebc46ecef64a7cb2ceb13f4d29bdc68880db726ff527afe2f95fa78e817f0c45ae8d8051de2646ab5ef4fe8cd5da9efe20f2a52b898b3d67fc2616bfc68a1a
+  metadata.gz: 40e09669cd064fa1091f9d44506cd04454fdead9c4e8974bccaa1d123d8d7659cbb976a6c3c0edaf5e40f397d7b637621ed134c9081837ff6bccce5842ca5612
+  data.tar.gz: bac295fbc3b82175c1ddc1c54b4df73e1f8c2285ea21997910f0550e33a9687994d3c2bfce59a35986c2d59df63252fa69f497502b058fab6d02b33303acbcd5

data/CHANGES.md

@@ -1,9 +1,47 @@
 # Change History
 
-## v 0.10.2, 2018-02-16
+## v 0.11.0a5 2018-02-15
 
--  *IMPORTANT BUG FIX*: Updating JSS::Extendable objects with no changes to ext. attribs will no longer erase all ext attrib values. (!)
+- Fix: Updating JSS::Extendable objects with no changes to ext. attribs will no longer erase all ext attrib values. (!)
 
+- Improvement: Updated general attributes for computers and mobile devices
+
+- Improvement: Computers and MobileDevices are now Creatable. Use the .make class method to create an unsaved instance, then .create/.save instance method to create the JSS record. Note: Mobile Devices need both a unique serial number and unique udid to be accepted by the API.
+
+- Improvement: Handling of 'site' data is now done via the JSS::Sitable mixin module
+
+- Improvement: When the JSS server's hostname ends with 'jamfcloud.com' default to SSL port 443 (vs 8443 for locally hosted JSSs)
+
+- Improvement: ruby-jss now has a code of conduct for contributors.
+
+- Improvement: now requires net-ldap v 0.16, for security fixes
+
+- Add: All APIObject subclasses can be deleted without instantiating, via the .delete class method, providing an array of ids
+
+- Improvement: All handling of MDM commands is in the JSS::MDM module, which is mixed in to Computer, ComputerGroup, MobileDevice, and MobileDeviceGroup
+
+- Fix: Scope objects use the api connection of their container
+
+- Improvement: Computer app usage & mgmt data methods are now class methods, so can be used without instantiating the computer.
+  The instance methods remain, and they now just use the class methods.
+
+- Improvement/Change: All handling of management history for Computers and MobileDevices is in the new ManagementHistory module.
+
+  The primary query method (.management_history) returns the raw JSON data from the API, possibly for a subset of the data, as a Ruby Hash
+  with symbolized keys. This data is somewhat inconsistent in it's structure and content across the different types of history events,
+  but you're welcome to use it if needed.
+
+  All other methods now return Arrays of various instances of classes defined in the module.
+
+  For example, the {JSS::ManagementHistory.audit_history} method returns an Array of JSS::ManagementHistory::AuditEvent instances,  and the
+  {JSS::ManagementHistory.completed_policies} gives an Array of JSS::ManagementHistory::PolicyLog objects. These objects are read-only and
+  provide access to their values via attribute-style methods.
+
+  As with MDM command handling, and computer app usage and mgmt data, the work is done by class methods, so that the data is available without creating instances of the Computers or MobileDevices, and the instance methods just
+  call the class methods.
+
+  *WARNING* these changes mean that the methods returning Arrays of ManagementHistory class instances are not backward compatible,
+  since the earlier versions returned Hashes
 
 ## v 0.10.1 2017-11-08
 
@@ -18,6 +56,7 @@
   then you can call `#object_history` and `#add_object_history_entry` for individual object instances.
 
 - Fix: Error when no storage device on a Computer is marked as the boot drive (Thanks @christopher.kemp!)
+
 - Fix: A few lingering methods that weren't multi-APIConnection aware, are now aware
 
 ## v0.10.0 2017-10-09
@@ -31,17 +70,24 @@
 
   The default/active connection continues to work as always, so your existing code will be fine.
   See the [documentation for the JSS::APIConnection class](http://www.rubydoc.info/gems/ruby-jss/JSS/APIConnection) for details.
+
 - Fix: Specifying port 443, as well as 8443, when connecting an APIConnection will default to using SSL. To force such a connection to NOT use SSL, provide the parameter `use_ssl: false`
+
 - Fix: require 'English', rather than require 'english'. Thanks to HIMANSHU-ELIGIBLE @ github for catching & fixing this one.
+
 - Fix: Popup extension attributes can always take a blank value.
+
 - Fix: UserGroup members have a 'username' value, not 'name'
+
 - Add: Two case-insentive string methods added to Array:
   - Array#jss_ci_include_string? Takes a string, returns true if the Array contains the string without regard to case.
         E.g. `['ThrAsHer'].jss_ci_include_string? 'thrasher' # => true`
   - Array#jss_ci_fetch_string Takes a string and fetches it from the array, regardless of case. Nil if not found.
         E.g. `['thrasher'].jss_ci_fetch_string 'ThrAsHer'  # => 'thrasher'`
 - Fix: APIConnection.map_all_ids wasn't honoring :refresh
+
 - Improvement: Extendable module: only push changed EAs when `update` is called.
+
 - Add: Computer objects now have a `last_enrolled` attribute
 
 ## v0.9.3 2017-08-08
@@ -49,6 +95,7 @@
 - Add: JSS::Computer instance now allow you to modify mac_address, alt_mac_address, udid, and serial_number.
   Note: even tho the WebUI doesn't allow editing of the serial_number, the API does and doing so can be useful
   for dealing with duplicate SN's when a new logic board with a new udid creates a new computer entry.
+
 - Add: JSS::Validate module, to consoliday generic data-validation methods. Methods will be moved to it from
   other places over time.
 

data/README.md

@@ -98,17 +98,19 @@ 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
-in the local variables jss_user, jss_user_pw, and jss_server_hostname, and others are left as default.
+The method `JSS.api` retruns the currently active connection to the API (an instance of a {JSS::APIConnection}, q.v.).
+
+When the JSS Module is first loaded, that connection isn't connected. To remedy that, use JSS.api.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
 ```
 
-Make sure the user has privileges in the JSS to do things with desired Objects.
+Make sure the user has privileges in the JSS to do things with desired Objects. Note that these might be more than you think, since some objects refer to other objects, like Sites and Categories.
+
+If the server name given ends with 'jamfcloud.com' the port number will default to 443 via SSL.  Otherwise, it defaults to 8443 with SSL (the default port for locally-hosted servers). In other situations, you can specify it with the `port:` and `use_ssl:` parameters.
 
-The {JSS::API#connect} method also accepts the symbols :stdin and :prompt as values for :pw, which will cause it to read the
+The 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
@@ -142,12 +144,12 @@ Some Classes provide other ways to list objects, depending on the data available
 
 #### Retrieving Objects
 
-To retrieve a single object call the class's constructor .fetch method and provide a name:,  id:, or other valid
+To retrieve a single object call the class's .fetch method and provide a name:,  id:, or other valid
 lookup attribute.
 
 
 ```ruby
-a_dept = JSS::Department.fetch name: "Payroll" # =>  #<JSS::Department:0x10b4c0818...
+a_dept = JSS::Department.fetch name: 'Payroll'# =>  #<JSS::Department:0x10b4c0818...
 ```
 
 Some classes can use more than just the :id and :name keys for lookups, e.g. computers can be looked up with :udid, :serial_number, or :mac_address.
@@ -209,6 +211,11 @@ To delete an object, just call its #delete method
 existing_script = JSS::Script.fetch id: 321
 existing_script.delete # => true # the delete was successful
 ```
+To delete an object without fetching it, use the class's .delete method and provide the id, or an array of ids.
+
+```ruby
+JSS::Script.delete [321, 543, 374]
+```
 
 See JSS::APIObject, the parent class of all API resources, for general information about creating, reading, updating/saving, and deleting resources.
 

data/lib/jss/api_connection.rb

@@ -237,11 +237,13 @@ module JSS
   #   prod2_victim_md = production_api2.fetch :MobileDevice, id: 832
   #
   # Here are the API calls you can make directly from an APIConnection object.
-  # Most of them behave identically to the same methods in the APIObject classes
+  # They behave practically identically to the same methods in the APIObject
+  # subclasses, since they just call those methods, passing themselves in as the
+  # APIConnection to use.
   #
   # - {#all}  The 'list' methods of the various APIObject classes. Use the 'only:'
   #   parameter to specify one of the sub-list-methods, like #all_ids or
-  #   #all_laptops
+  #   #all_laptops, e.g. `my_connection.all :computers, only: :id`
   # - {#map_all_ids} the equivalent of #map_all_ids_to in the APIObject classes
   # - {#valid_id} given a class and an identifier (like macaddress or udid)
   #   return a valid id or nil
@@ -254,6 +256,9 @@ module JSS
   # - {#send_computer_mdm_command} same as {Computer.send_mdm_command}
   # - {#computer_checkin_settings} same as {Computer.checkin_settings}
   # - {#computer_inventory_collection_settings} same as {Computer.inventory_collection_settings}
+  # - {#computer_application_usage} same as {Computer.application_usage}
+  # - {#computer_management_data} same as {Computer.management_data}
+  # - {#computer_history} same as {Computer.history}
   # - {#send_mobiledevice_mdm_command} same as {MobileDevice.send_mdm_command}
   # - {#master_distribution_point} same as {DistributionPoint.master_distribution_point}
   # - {#my_distribution_point} same as {DistributionPoint.my_distribution_point}
@@ -295,15 +300,21 @@ module JSS
     # The Default port
     HTTP_PORT = 9006
 
-    # The Jamf default SSL port
+    # The Jamf default SSL port, default for locally-hosted servers
     SSL_PORT = 8443
 
-    # The https default SSL port
+    # The https default SSL port, default for Jamf Cloud servers
     HTTPS_SSL_PORT = 443
 
     # if either of these is specified, we'll default to SSL
     SSL_PORTS = [SSL_PORT, HTTPS_SSL_PORT].freeze
 
+    # Recognize Jamf Cloud servers
+    JAMFCLOUD_DOMAIN = 'jamfcloud.com'.freeze
+
+    # JamfCloud connections default to 443, not 8443
+    JAMFCLOUD_PORT = HTTPS_SSL_PORT
+
     # The top line of an XML doc for submitting data via API
     XML_HEADER = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>'.freeze
 
@@ -739,25 +750,48 @@ module JSS
       the_class.make args
     end
 
-    # Call {JSS::Computer.checkin_settings} passing this API
+    # Call {JSS::Computer.checkin_settings} q.v.,  passing this API
     # connection
     #
-    # @return (see JSS::Computer.checkin_settings)
-    #
     def computer_checkin_settings
       JSS::Computer.checkin_settings api: self
     end
 
-
-    # Call {JSS::Computer.inventory_collection_settings} passing this API
+    # Call {JSS::Computer.inventory_collection_settings} q.v., passing this API
     # connection
     #
-    # @return (see JSS::Computer.checkin_settings)
-    #
     def computer_inventory_collection_settings
       JSS::Computer.inventory_collection_settings api: self
     end
 
+    # Call {JSS::Computer.application_usage} q.v., passing this API
+    # connection
+    #
+    def computer_application_usage(ident, start_date, end_date = nil)
+      JSS::Computer.application_usage ident, start_date, end_date, api: self
+    end
+
+    # Call {JSS::Computer.management_data} q.v., passing this API
+    # connection
+    #
+    def computer_management_data(ident, subset: nil, only: nil)
+      JSS::Computer.management_data ident, subset: subset, only: only, api: self
+    end
+
+    # Call {JSS::Computer.history} q.v., passing this API
+    # connection
+    #
+    def computer_history(ident, subset: nil)
+      JSS::Computer.history ident, subset: subset, api: self
+    end
+
+    # Call {JSS::Computer.send_mdm_command} q.v.,  passing this API
+    # connection
+    #
+    def send_computer_mdm_command(targets, command, passcode = nil)
+      JSS::Computer.send_mdm_command targets, command, passcode, api: self
+    end
+
     # Get the DistributionPoint instance for the master
     # distribution point in the JSS. If there's only one
     # in the JSS, return it even if not marked as master.
@@ -834,7 +868,7 @@ module JSS
     #
     # @return [Array<Integer>] the ids of the NetworkSegments containing the given ip
     #
-    def network_segments_for_ip(ip, refresh = false)
+    def network_segments_for_ip(ip)
       ok_ip = IPAddr.new(ip)
       matches = []
       network_ranges.each { |id, subnet| matches << id if subnet.include?(ok_ip) }
@@ -849,15 +883,6 @@ module JSS
       network_segments_for_ip JSS::Client.my_ip_address
     end
 
-    # Send an MDM command to one or more computers managed by
-    # this JSS
-    #
-    # see {JSS::Computer.send_mdm_command}
-    #
-    def send_computer_mdm_command(targets, command, passcode = nil)
-      JSS::Computer.send_mdm_command(targets, command, passcode, api: self)
-    end
-
     # Send an MDM command to one or more mobile devices managed by
     # this JSS
     #
@@ -935,7 +960,7 @@ module JSS
       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[:port] ||= JSS::Client.jss_port.to_i
       args[:use_ssl] ||= JSS::Client.jss_protocol.to_s.end_with? 's'
       args
     end
@@ -947,8 +972,7 @@ module JSS
     # @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[:port] ||= args[:server].to_s.end_with?(JAMFCLOUD_DOMAIN) ? JAMFCLOUD_PORT : SSL_PORT
       args[:timeout] ||= DFT_TIMEOUT
       args[:open_timeout] ||= DFT_OPEN_TIMEOUT
       args[:ssl_version] ||= DFT_SSL_VERSION

data/lib/jss/api_object/advanced_search.rb

@@ -60,12 +60,16 @@ module JSS
     include JSS::Creatable
     include JSS::Updatable
     include JSS::Criteriable
+    include JSS::Sitable
 
     # Class Constants
     #####################################
 
     EXPORT_FORMATS = [:csv, :tab, :xml].freeze
 
+    # Where is site data located in the API JSON?
+    SITE_SUBSET = :top
+
     # Attributes
     #####################################
 
@@ -342,7 +346,7 @@ module JSS
 
       df = acs.add_element('display_fields')
       @display_fields.each { |f| df.add_element('display_field').add_element('name').text = f }
-
+      add_site_to_xml(doc)
       doc.to_s
     end # rest xml