ruby-jss 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efe85ea732df2a1ce119273c532084459fdb9ebe6316d62ab7afa533d9c4adc8
-  data.tar.gz: e42de1baecb51f2886d704e63818d24063d4332a0b17170c2977aa3e336656a5
+  metadata.gz: ed31b6de65dd9f753522997db8bee3030036d7b7f3064c9a1586ecda06c2e593
+  data.tar.gz: 7c6e77eb322d52934729b7f5a26283a46921f0b52c8f6046d8bee57f0dd8cc5b
 SHA512:
-  metadata.gz: 6a0874d08b6c7fc3aa93c207c81ab3a09c0b822e5f035ddb5192144d04fbe3a846db6c6528a8150cd81a2ee9f994155d4b7ba396d11ef7ecf565c9330b99aae6
-  data.tar.gz: fb3bdf758de69f290974def92a42ff279f1c98611373116304fbe618b0536f59361d892c3444db88c952c2208bb7cfbf0763cba8a959bd84cffb3ca5f8bee8e7
+  metadata.gz: 82fbcfb1a88e333ed07d04e37878ec3f9c4fa9c5aa6705a5860285222e52d9b9adeb5ad329520868ce223e68338eac576888eb387774abe4b066804ee9c5b921
+  data.tar.gz: 65095fd093104fd752a9c4294ff1cd0e41e570f9b928a1c8497cada0c56b2990a87f432f84f6a4332d400e3ac90cbd4852776d0ba9e9a85198580816e5dac731

data/CHANGES.md

@@ -16,6 +16,22 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 
 --------
 
+## \[3.0.0] - 2023-05-22
+Major version bump because changes to policy log flushing are not backward compatible.
+
+### Added
+  - Jamf::Policy.flush_logs_for_computers: formerly private class method, now public and used for flushing policy logs for specific computers.
+
+### Fixed
+  - Fix bug in MDM enable_lost_mode instance method, and make the default behavior match the API
+  - Specify the connection instance when validating ids in MacOSManagedUpdates
+  - Send mandatory field 'name' with a MobileDeviceApplication request (Thanks @yanniks!)
+  - Policy Log Flushing now reflects API limitation: You can flush logs for a policy for all computers, or for a computer for all policies, but not specific policies for specific computers. See Jamf::Policy.flush_logs and Jamf::Policy.flush_logs_for_computers
+  - A validation method wasn't passing cnx param correctly.
+
+### Changed
+  - MacOSManagedUpdates.send_managed_os_update takes symbols or strings as the updateAction, a key or a value from the UPDATE_ACTIONS constant
+
 ## \[2.1.1] - 2022-11-07
 
 ### Fixed & Deprecated

data/README.md

@@ -6,7 +6,7 @@
 Version 2.0.0 has major changes! While we've strived for _mostly_ being backward compatible, and have done lots of testing, YMMV.  Please report any issues.
 
 _NOTE_: ruby-jss 2.0 is not completely backward compatible, please see  [README-2.0.0.md](README-2.0.0.md) for more info
- 
+
 ### Highlights
 
 - Support for Ruby 3.x
@@ -57,7 +57,6 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 - [BEYOND THE API](#beyond-the-api)
 - [INSTALL](#install)
 - [REQUIREMENTS](#requirements)
-  - [Contact](#contact)
 - [HELP & CONTACT INFO](#help--contact-info)
 - [LICENSE](#license)
 
@@ -65,13 +64,13 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 
 ## DESCRIPTION
 
-ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and 
+ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and
 'Jamf Pro' APIs of a Jamf Pro server. Jamf Pro is an enterprise-level management tool for Apple
 devices from [Jamf.com](http://www.jamf.com/).  It is available as a[ruby gem](https://rubygems.org/gems/ruby-jss), and the
 [source is on github](https://github.com/PixarAnimationStudios/ruby-jss).
 
 The Jamf module maintains connections to both APIs simultaneously, and uses which ever is appropriate as needed.
-Details like authentication tokens, token refreshing, JSON and XML parsing, and even knowing which resources use 
+Details like authentication tokens, token refreshing, JSON and XML parsing, and even knowing which resources use
 which API are all handled under-the-hood.
 
 The Jamf module abstracts many API resources as Ruby objects, and provides methods for interacting with those
@@ -79,8 +78,8 @@ resources. It also provides some features that aren't a part of the API itself,
 Jamf-related tools, such as uploading {Jamf::Package} files to the master distribution
 point, and the installation of those objects on client machines. (See [BEYOND THE API](#beyond-the-api))
 
-The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled, 
-some only minimally. Of those, some are read-only, some partially writable, some fully read-write. 
+The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled,
+some only minimally. Of those, some are read-only, some partially writable, some fully read-write.
 We've implemented the things we need in our environment, and as our needs grow, we'll add more.
 Hopefully others will find it useful, and add more to it as well.
 
@@ -138,14 +137,14 @@ ns.save
 
 Before you can work with Jamf Pros Objects via the APIs, you have to connect to the server.
 
-The method `Jamf.cnx` returns the 'default' connection object (an instance of a {Jamf::APIConnection}, q.v.). 
+The method `Jamf.cnx` returns the 'default' connection object (an instance of a {Jamf::APIConnection}, q.v.).
 A connection object holds all the data needed to communicate with the server to which it's connected, as well as
-any data cached from that server. 
+any data cached from that server.
 The default connection object is used for all communication unless a different one is explicitly passed to methods
 that can accept one. See 'Using multiple connections' below.
 
 When the Jamf Module is first loaded, the default connection isn't connected a server. To remedy that, use `Jamf.cnx.connect`,
-passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user, 
+passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user,
 jss_user_pw, and jss_server_hostname, and others are left as default.
 
 ```ruby
@@ -170,8 +169,8 @@ server connection parameters in a simple config file.
 
 #### Using multiple connections
 
-Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However 
-you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and 
+Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However
+you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and
 access, and pass those connection objects into methods using the `cnx:` parameter as appropriate.
 
 ```ruby
@@ -194,13 +193,13 @@ common_ipr_sns = ipr_sns_1 & ipr_sns_2
 
 ### Working with Jamf Objects
 
-All of the ruby classes representing objects in Jamf Pro have common methods for creating, listing, retrieving, updating, and deleting via the API. 
+All of the ruby classes representing objects in Jamf Pro have common methods for creating, listing, retrieving, updating, and deleting via the API.
 All supported objects can be listed, retrieved and deleted, but only some can be updated or created, mostly becase we haven't needed to do that ourselves
 yet and haven't implemented that functionality.  If you need additional features implemented, please get in touch (see 'Contact' above) or feel free to
 try implementing it yourself and send us a merge request.
 
-Some of the implemented objects also provide access to more 'functional' API resources. For example, the API resources for 
-sending MDM commands to computers and mobile devices are available as class and instance methods of Jamf::Computer and Jamf::MobileDevice, 
+Some of the implemented objects also provide access to more 'functional' API resources. For example, the API resources for
+sending MDM commands to computers and mobile devices are available as class and instance methods of Jamf::Computer and Jamf::MobileDevice,
 as are the API resources for accessing management history.
 
 --------
@@ -474,21 +473,13 @@ It also requires other ruby gems, which will be installed automatically if you i
 See the .gemspec file for details
 
 
-### Contact
-
-If you have questions or feedback about ruby-jss, please reach out  to us via:
-- The [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK)
-- Open an issue on GitHub
-- Email ruby-jss@pixar.com
-
-
 ## HELP & CONTACT INFO
 
 Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/).
 
 There's a [wiki on the github page](https://github.com/PixarAnimationStudios/ruby-jss/wiki), feel free to contribute examples and tidbits.
 
-You can report issues in several ways:
+If you have questions or feedback about ruby-jss, please reach out  to us via:
 - [Open an issue on github](https://github.com/PixarAnimationStudios/ruby-jss/issues)
 - [Email the developers at ruby-jss@pixar.com](mailto:ruby-jss@pixar.com)
 - Join the conversation in the [#ruby-jss Macadmins Slack Channel](https://macadmins.slack.com/archives/C03C7F563MK)

data/lib/jamf/api/classic/api_objects/computer.rb

@@ -1158,15 +1158,29 @@ module Jamf
       @need_to_update = true
     end
 
-    # flush the logs for this computer in a given policy
-    # @see Jamf::Policy.flush_logs
+    # Flush all policy logs for this computer older than a given time period.
     #
-    def flush_policy_logs(policy, older_than: 0, period: :days)
-      Jamf::Policy.flush_logs(
-        policy,
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # With no parameters, will flush all logs for the computer
+    #
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
+    #
+    # @param older_than[Integer] 0, 1, 2, 3, or 6
+    #
+    # @param period[Symbol] :days, :weeks, :months, or :years
+    #
+    # @see Jamf::Policy.flush_logs_for_computers
+    #
+    def flush_policy_logs(older_than: 0, period: :days)
+      Jamf::Policy.flush_logs_for_computers(
+        [@id],
         older_than: older_than,
         period: period,
-        computers: [@id], cnx: @cnx
+        cnx: @cnx
       )
     end
 

data/lib/jamf/api/classic/api_objects/mdm.rb

@@ -476,7 +476,7 @@ module Jamf
             raise Jamf::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id
           end
         end # unles
-        
+
         targets
       end
 
@@ -860,7 +860,7 @@ module Jamf
         cnx = api if api
 
         unless WALLPAPER_LOCATIONS.keys.include? wallpaper_setting
-          raise ArgumentError, 
+          raise ArgumentError,
                 "wallpaper_setting must be one of: :#{WALLPAPER_LOCATIONS.keys.join ', :'}"
         end
 
@@ -999,7 +999,7 @@ module Jamf
       #
       # @param play_sound[Boolean] Play a sound when entering lost mode
       #
-      # @param enforce_lost_mode[Boolean] Re-enabled lost mode when re-enrolled after wipe.
+      # @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
       #
       # @param cnx [Jamf::Connection] the API thru which to send the command
       #
@@ -1011,7 +1011,7 @@ module Jamf
         phone: nil,
         footnote: nil,
         play_sound: false,
-        enforce_lost_mode: true,
+        enforce_lost_mode: false,
         api: nil,
         cnx: Jamf.cnx
       )
@@ -1081,7 +1081,7 @@ module Jamf
 
         status = FLUSHABLE_STATUSES[status]
 
-        # TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can 
+        # TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can
         # use this to flush commands for unmanaged machines.
         target_ids = raw_targets_to_ids targets, cnx: cnx, expand_groups: false, unmanaged_ok: true
 
@@ -1378,21 +1378,21 @@ module Jamf
     #
     # @param play_sound[Boolean] Play a sound when entering lost mode
     #
-    # @param enforce_lost_mode[Boolean] Re-enabled lost mode when re-enrolled after wipe.
+    # @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
     #
     # @return (see .send_mdm_command)
     #
     def enable_lost_mode(
       message: nil,
-      phone_number: nil,
+      phone: nil,
       footnote: nil,
-      enforce_lost_mode: true,
+      enforce_lost_mode: false,
       play_sound: false
     )
       self.class.enable_lost_mode(
         @id,
         message: message,
-        phone_number: phone_number,
+        phone: phone,
         footnote: footnote,
         play_sound: play_sound,
         enforce_lost_mode: enforce_lost_mode, cnx: @cnx

data/lib/jamf/api/classic/api_objects/mobile_device_application.rb

@@ -544,6 +544,7 @@ module Jamf
       doc = REXML::Document.new Jamf::Connection::XML_HEADER
       obj = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
       gen = obj.add_element 'general'
+      gen.add_element('name').text = @display_name
       gen.add_element('display_name').text = @display_name
       gen.add_element('description').text = @description
       gen.add_element('os_type').text = @os_type

data/lib/jamf/api/classic/api_objects/policy.rb

@@ -293,10 +293,19 @@ module Jamf
     # Class Methods
     ######################
 
-    # Flush logs for a given policy older than some number of days, weeks,
-    # months or years, possibly limited to one or more computers.
+    # Flush logs for a given policy older than a given time period.
+    # This flushes the logs of the given policy for all computers.
     #
-    # With no parameters, flushes all logs for the policy for all computers.
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # (See .flush_logs_for_computers to to flush all logs for given computers)
+    #
+    # With no parameters, flushes all logs for the policy.
+    #
+    # Without older_than: and period:, will flush all logs for the policy
     #
     # NOTE: Currently the API doesn't have a way to flush only failed policies.
     #
@@ -306,52 +315,74 @@ module Jamf
     #
     # @param policy[Integer,String] The id or name of the policy to flush
     #
-    # @param older_than[Integer] 0, 1, 2, 3, or 6
-    #
-    # @param period[Symbol] :days, :weeks, :months, or :years
+    # @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
     #
-    # @param computers[Array<Integer,String>] Identifiers of the target computers
-    #   either ids, names, SNs, macaddrs, or UDIDs. If omitted, flushes logs for
-    #   all computers
+    # @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
     #
     # @param cnx [Jamf::Connection] the API  connection to use.
     #
     # @return [void]
     #
-    def self.flush_logs(policy, older_than: 0, period: :days, computers: [], api: nil, cnx: Jamf.cnx)
+    def self.flush_logs(policy, older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      orig_timeout = cnx.timeout
       pol_id = valid_id policy, cnx: cnx
       raise Jamf::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id
 
-      older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
-      raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
-
-      period = LOG_FLUSH_INTERVAL_PERIODS[period]
-      raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
-
-      computers = [computers] unless computers.is_a? Array
+      older_than, period = validate_log_flush_params(older_than, period)
 
       # log flushes can be really slow
+      orig_timeout = cnx.timeout
       cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
 
-      return cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}" if computers.empty?
-
-      flush_logs_for_specific_computers pol_id, older_than, period, computers, cnx
+      cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}"
     ensure
       cnx.timeout = orig_timeout
     end
 
-    # use an XML body in a DELETE request to flush logs for
-    # a list of computers - used by the flush_logs class method
-    def self.flush_logs_for_specific_computers(pol_id, older_than, period, computers, cnx)
+    # Flush policy logs for specific computers older than  a given time period.
+    # This flushes the logs for all policies for these computers.
+    #
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # (See .flush_logs to to flush all logs for a given policy)
+    #
+    # Without older_than: and period:, will flush all logs for the computers
+    #
+    # NOTE: Currently the API doesn't have a way to flush only failed policies.
+    #
+    # WARNING: Log flushing can take a long time, and the API call doesnt return
+    # until its finished. The connection timeout will be temporarily raised to
+    # 30 minutes, unless it's already higher.
+    #
+    # @param computers[Array<Integer,String>] Identifiers of the target computers
+    #   either ids, names, SNs, macaddrs, or UDIDs.
+    #
+    # @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
+    #
+    # @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
+    #
+    # @param cnx [Jamf::Connection] the API  connection to use.
+    #
+    # @return [void]
+    #
+    def self.flush_logs_for_computers(computers = [], older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
+      computers = [computers] unless computers.is_a? Array
+      raise JSS::InvalidDataError, 'One or more computers must be specified' if computers.empty?
+
+      older_than, period = validate_log_flush_params(older_than, period)
+
       # build the xml body for a DELETE request
       xml_doc = REXML::Document.new Jamf::Connection::XML_HEADER
       lf = xml_doc.add_element 'logflush'
       lf.add_element('log').text = 'policy'
-      lf.add_element('log_id').text = pol_id.to_s
       lf.add_element('interval').text = "#{older_than} #{period}"
+
       comps_elem = lf.add_element 'computers'
       computers.each do |c|
         id = Jamf::Computer.valid_id c, cnx: cnx
@@ -361,13 +392,41 @@ module Jamf
         ce.add_element('id').text = id.to_s
       end
 
+      # for debugging the xml...
+      #
+      # formatter = REXML::Formatters::Pretty.new(2)
+      # formatter.compact = true
+      # formatter.write(xml_doc, $stdout)
+      # puts
+      # return
+
+      # log flushes can be really slow
+      orig_timeout = cnx.timeout
+      cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
+
       # Do a DELETE request with a body.
-      cnx.delete(LOG_FLUSH_RSRC) do |req|
+      resp = cnx.c_cnx.delete(LOG_FLUSH_RSRC) do |req|
         req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
         req.body = xml_doc.to_s
       end
+
+      resp.body
+    ensure
+      cnx.timeout = orig_timeout
     end
-    private_class_method :flush_logs_for_specific_computers
+
+    # validate the logflush params
+    # @return [Array<String>]
+    def self.validate_log_flush_params(older_than, period)
+      older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
+      raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
+
+      period = LOG_FLUSH_INTERVAL_PERIODS[period]
+      raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
+
+      [older_than, period]
+    end
+    private_class_method :validate_log_flush_params
 
     # Attributes
     ######################
@@ -1852,11 +1911,14 @@ module Jamf
     end
     alias execute run
 
-    # Flush logs for this policy older than
-    # some number of days, weeks, months or years, possibly limited to
-    # one or more computers
+    # Flush logs for this policy older than a given time period.
     #
-    # With no parameters, flushes all logs for all computers
+    # IMPORTANT: from the Jamf Developer Site:
+    #   The ability to flush logs is currently only supported for flushing all logs
+    #   for a given policy or all logs for a given computer. There is no support for
+    #   flushing logs for a given policy and computer combination.
+    #
+    # With no parameters, will flush all logs for the policy
     #
     # NOTE: Currently the API doesn't have a way to flush only failed policies.
     #
@@ -1868,19 +1930,16 @@ module Jamf
     #
     # @param period[Symbol] :days, :weeks, :months, or :years
     #
-    # @param computers[Array<Integer,String>] Identifiers of the target computers
-    #   either ids, names, SNs, macaddrs, or UDIDs
-    #
     # @return [void]
     #
-    def flush_logs(older_than: 0, period: :days, computers: [])
-      raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #create first." unless @in_jss
+    def flush_logs(older_than: 0, period: :days)
+      raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #save first." unless @in_jss
 
       Jamf::Policy.flush_logs(
         @id,
         older_than: older_than,
         period: period,
-        computers: computers, cnx: @cnx
+        cnx: @cnx
       )
     end
 

data/lib/jamf/api/classic/api_objects/scopable/scope.rb

@@ -476,7 +476,10 @@ module Jamf
         item_id = validate_item(:target, key, item)
         return if @targets[key]&.include?(item_id)
 
-        raise Jamf::AlreadyExistsError, "Can't set #{key} target to '#{item}' because it's already an explicit exclusion." if @exclusions[key]&.include?(item_id)
+        if @exclusions[key]&.include?(item_id)
+          raise Jamf::AlreadyExistsError,
+                "Can't set #{key} target to '#{item}' because it's already an explicit exclusion."
+        end
 
         @targets[key] << item_id
         @all_targets = false
@@ -775,7 +778,7 @@ module Jamf
       ################
       def scoped_machines
         scoped_machines = {}
-        @target_class.all_objects(cnx: container.cnx).each do |machine|
+        @target_class.all_objects(:refresh, cnx: container.cnx).each do |machine|
           scoped_machines[machine.id] = machine.name if in_scope? machine
         end
         scoped_machines

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

@@ -19,14 +19,14 @@
 #    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.
-#
-#
+
+# frozen_string_literal: true
 
 module Jamf
 
   # This module should be mixed in to Jamf::Computer and Jamf::ComputerGroup
   #
-  # It provides access to the macos-managed-software-updates JPAPI resource for 
+  # It provides access to the macos-managed-software-updates JPAPI resource for
   # managed OS update commands to managed macs running Big Sur or higher.
   #
   module MacOSManagedUpdates
@@ -37,7 +37,7 @@ module Jamf
       includer.extend(ClassMethods)
     end
 
-    # These resources in the Jamf Pro API can be used to send Managed macOS 
+    # These resources in the Jamf Pro API can be used to send Managed macOS
     # updates to clients running Big Sur or higher
     MANAGED_SW_UPDATES_RSRC = 'v1/macos-managed-software-updates'
 
@@ -45,7 +45,7 @@ module Jamf
     MANAGED_SW_UPDATES_AVAILABLE_VERSIONS_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/available-updates"
 
     # POSTing JSON data to this resource will send the MDM commands to install os updates
-    # For details about the data to send, see 
+    # For details about the data to send, see
     # https://developer.jamf.com/jamf-pro/reference/post_v1-macos-managed-software-updates-send-updates
     MANAGED_SW_UPDATES_SEND_UPDATES_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/send-updates"
 
@@ -53,6 +53,12 @@ module Jamf
     DOWNLOAD_AND_INSTALL = 'DOWNLOAD_AND_INSTALL'
     DOWNLOAD_ONLY = 'DOWNLOAD_ONLY'
 
+    # for easier use of these values as the updateAction
+    UPDATE_ACTIONS = {
+      install: DOWNLOAD_AND_INSTALL,
+      download: DOWNLOAD_ONLY
+    }
+
     # Class Methods
     #####################################
     module ClassMethods
@@ -73,48 +79,51 @@ module Jamf
 
       # Send the os update command to target Computers or a ComputerGroup
       #
-      # @param updateAction [String] Required. 'DOWNLOAD_AND_INSTALL' or 'DOWNLOAD_ONLY'
+      # @param updateAction [Symbol, Symbol] Required. One of the keys or values from UPDATE_ACTIONS
       #
-      # @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the 
+      # @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the
       #   computer targets. Required if no groupId is given.
       #
       # @param groupId [String, Integer] Identifier for the computer group target.
-      #   Requied if no deviceIDs are given.
+      #   Requied if no deviceIds are given.
       #
-      # @param maxDeferrals [Integer] Allow users to defer the update the provided number 
-      #   of times before macOS forces the update. If a value is provided, the Software 
-      #   Update will use the InstallLater install action. MaxDeferral is ignored if using the 
-      #   DOWNLOAD_ONLY updateAction.
+      # @param maxDeferrals [Integer] Allow users to defer the update the provided number
+      #   of times before macOS forces the update. If a value is provided, the Software
+      #   Update will use the InstallLater install action. MaxDeferral is ignored if using the
+      #   :download updateAction.
       #
-      # @param version [String] The OS version to install. If no value is provided, the 
+      # @param version [String] The OS version to install. If no value is provided, the
       #   version will default to latest version based on device eligibility.
       #
       # @param skipVersionVerification [Boolean] Should the specified version be installed
       #   even it it isn't applicable to this machine? If no value is provided, will default to false.
-      #   If true, the specified version will be forced to complete DownloadAndInstall
-      #   install action.
+      #   If true, the specified version will be forced to complete the :install updateAction.
       #
       # @param applyMajorUpdate [Boolean] Available only when updating to the latest version
       #   based on device eligibility. Defaults to false. If false the calculated latest version
       #   will only include minor version updates. If a value is provided, the calculated latest
       #   version will include minor and major version updates.
       #
-      # @param forceRestart [Boolean]  Will default to false. Can only be true if updateAction 
-      #   is DOWNLOAD_AND_INSTALLn and the devices the command is sent to are on macOs 11 or higher. 
-      #   If true, the DownloadAndInstall action is performed, a restart will be forced. 
-      #   MaxDeferral will be ignored if true. 
+      # @param forceRestart [Boolean]  Will default to false. Can only be true if updateAction
+      #   is :install and the target devices are on macOs 11 or higher.
+      #   If true, the DownloadAndInstall action is performed, a restart will be forced.
+      #   MaxDeferral will be ignored if true.
       #
-      # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx 
+      # @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
       #
-      # @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse] 
+      # @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse]
       ########################
       def send_managed_os_update(updateAction:, deviceIds: nil, groupId: nil, maxDeferrals: nil, version: nil, skipVersionVerification: false, applyMajorUpdate: false, forceRestart: false, cnx: Jamf.cnx)
-        if self == Jamf::Computer 
+        action_to_send = UPDATE_ACTIONS.value?(updateAction) ? updateAction : UPDATE_ACTIONS[updateAction]
+
+        raise ArgumentError, "Unknown updateAction, must be one of: #{UPDATE_ACTIONS.keys.join ', '}" unless action_to_send
+
+        if self == Jamf::Computer
           raise ArgumentError, 'Must provide one or more deviceIds' unless deviceIds
         elsif self == Jamf::ComputerGroup
           raise ArgumentError, 'Must provide a groupId' unless groupId
         else
-          raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup' 
+          raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup'
         end
 
         if version
@@ -124,9 +133,9 @@ module Jamf
 
         if deviceIds
           deviceIds = [deviceIds] unless deviceIds.is_a?(Array)
-          deviceIds.map! { |id| valid_id id }
+          deviceIds.map! { |id| valid_id id, cnx: cnx }
         end
-        groupId = valid_id groupId if groupId
+        groupId = valid_id(groupId, cnx: cnx) if groupId
 
         data = {}
         # ids in the JPAPI are string containing integers
@@ -137,11 +146,11 @@ module Jamf
         data[:version] = version if version
         data[:skipVersionVerification] = skipVersionVerification if skipVersionVerification
         data[:applyMajorUpdate] = applyMajorUpdate if applyMajorUpdate
-        data[:updateAction] = updateAction if updateAction
-        data[:forceRestart] = forceRestart if forceRestart  
-        
+        data[:updateAction] = action_to_send
+        data[:forceRestart] = forceRestart if forceRestart
+
         payload = Jamf::OAPISchemas::MacOsManagedSoftwareUpdate.new(data).to_json
-        
+
         result = cnx.jp_post MANAGED_SW_UPDATES_SEND_UPDATES_RSRC, payload
         Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse.new result
       end
@@ -161,14 +170,14 @@ module Jamf
       groupId = is_a?(Jamf::Computer) ? nil : @id
 
       self.class.send_managed_os_update(
-        deviceIds: deviceIds, 
-        groupId: groupId, 
-        maxDeferrals: maxDeferrals, 
-        version: version, 
-        skipVersionVerification: skipVersionVerification, 
-        applyMajorUpdate: applyMajorUpdate, 
-        forceRestart: forceRestart, 
-        updateAction: updateAction, 
+        deviceIds: deviceIds,
+        groupId: groupId,
+        maxDeferrals: maxDeferrals,
+        version: version,
+        skipVersionVerification: skipVersionVerification,
+        applyMajorUpdate: applyMajorUpdate,
+        forceRestart: forceRestart,
+        updateAction: updateAction,
         cnx: @cnx
       )
     end

data/lib/jamf/validate.rb

@@ -98,7 +98,9 @@ module Jamf
     #
     # @return [Object] the validated unique value
     #
-    def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: Jamf.cnx)
+    def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       return val unless klass.all(:refresh, cnx: cnx).map { |i| i[identifier] }.include? val
 
       key = klass.real_lookup_key identifier

data/lib/jamf/version.rb

@@ -27,6 +27,6 @@
 module Jamf
 
   ### The version of ruby-jss
-  VERSION = '2.1.1'.freeze
+  VERSION = '3.0.0'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Chris Lasell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-09 00:00:00.000000000 Z
+date: 2023-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: CFPropertyList