ruby-jss 4.2.0b2 → 4.2.1

data/lib/jamf/api/jamf_pro/api_objects/j_package.rb

@@ -25,6 +25,8 @@
 
 # frozen_string_literal: true
 
+require 'cfpropertylist'
+
 # The main Module
 module Jamf
 
@@ -102,6 +104,13 @@ module Jamf
     # which usually only identifies ':id'
     ALT_IDENTIFIERS = %i[packageName fileName].freeze
 
+    # If the object does not have a 'name' attribute, this is the attribute
+    # that holds its name. Used to allow referencing objects by 'name',
+    # creates a alias of the attribute called "name" and "name=",
+    # and allows the use of "name:" as an identifier in the .fetch, .valid_id and
+    # similar methods.
+    OBJECT_NAME_ATTR = :packageName
+
     # Must define this when extending Filterable
     FILTER_KEYS = %i[
       id fileName packageName categoryId info notes manifestFileName cloudTransferStatus
@@ -126,7 +135,7 @@ module Jamf
     # The hashType value in the API or manifests for md5
     CHECKSUM_HASH_TYPE_MD5 = 'MD5'
 
-    # The hashType value in the API for sha256 - IF it exists
+    # The hashType value in the API for sha256 - IF it exists?
     CHECKSUM_HASH_TYPE_SHA256 = 'SHA_256'
 
     # The hashType value in MDM deploy manifests for sha256
@@ -149,7 +158,15 @@ module Jamf
     # fileName, with spaces converted to dashes.
     MANIFEST_FILENAME_DEFAULT_SUFFIX = '-manifest.plist'
 
-    # Not doing chunking by default in generated manifests
+    # If no manifest bundle identifier is provided, this will be used before
+    # the packageName.
+    MANIFEST_BUNDLE_ID_PREFIX = 'com.pixar.ruby-jss.'
+
+    # if no manifest bundle version is provided, this will be used.
+    MANIFEST_BUNDLE_VERSION_DEFAULT = '0'
+
+    # Not doing chunking by default in generated manifests,
+    # but if we do, we'll use this
     MANIFEST_CHUNK_SIZE = 1024 * 1024 * 10 # 10MB
 
     MANIFEST_PLIST_TEMPLATE = {
@@ -164,10 +181,11 @@ module Jamf
           ], # end assets array,
           metadata: {
             'kind' => 'software',
-            'bundle-identifier' => 'com.example.pkg',
-            'bundle-version' => '0',
+            'bundle-identifier' => "#{MANIFEST_BUNDLE_ID_PREFIX}example",
+            'bundle-version' => MANIFEST_BUNDLE_VERSION_DEFAULT,
             'title' => 'title',
-            'sizeInBytes' => 1
+            'sizeInBytes' => 1,
+            'sha256-whole' => 'sha256-goes-here'
           } # end metadata
         } # end hash
       ] # end items array
@@ -210,8 +228,8 @@ module Jamf
     # for all Jamf::JPackage objects in this ruby session.
     #
     # Setting this in the config or here means you don't have to provide a base URL
-    # each time when calling #generate_manifest, however you can still provide one
-    # at that time to override any default.
+    # each time when calling #generate_manifest or #upload, however you can still provide
+    # one at that time to override any default.
     #
     # Normally, the package's fileName is appended to this URL to generate the full
     # download URL. E.g. for a package with a fileName 'my-app.pkg', with the base URL of
@@ -244,18 +262,22 @@ module Jamf
     #####################################
 
     # Checksums
+    #
     # Packages in Jamf Pro can have a checksum in either MD5 or SHA512, or possibly
     # SHA256 - none of our 1500 pkgs have 256, but given the existence of the sha256
     # attribute in the API data, I'm assuming it existed at some point, and behaves like
     # md5 (read on)
     #
-    # In all cases, the hashType indicates the type of checksum, as a string, one of
-    # 'MD5', 'SHA_256', or 'SHA_512'.
+    # In all cases, the hashType attribute indicates the type of checksum, as a string,
+    # one of 'MD5', 'SHA_256', or 'SHA_512'.
     #
-    # In the case of md5 and sha256, the actually digest value (the checksum) is in the
+    # In the case of md5 and sha256, the actual digest value (the checksum) is in the
     # 'md5' or 'sha256' attribute. In the case of sha512, the digest is in the 'hashValue'
     # attribute.
-    # In anycase, the digest value will be stored in the checksum attribute of this class
+    # In anycase, the digest value will also be stored in the checksum attribute
+    #
+    # NOTE: This is the checksum used when installing via a Policy.
+    # The checksum(s) used when deploying via MDM is stored in the manifest.
     #
     # @return [String] the checksum of the package, either an MD5, SHA256, or SHA512
     #   digest of the package file.
@@ -318,6 +340,12 @@ module Jamf
       self.suppressEula = DEFAULT_SUPPRESS_EULA if suppressEula.nil?
       self.suppressRegistration = DEFAULT_SUPPRESS_REGISTRATION if suppressRegistration.nil?
 
+      if creating_from_create && osRequirements
+        # if we're creating a new object, and osRequirements is set,
+        # convert it to a comma-separated string
+        @osRequirements = osRequirements_as_comma_sep_string(osRequirements)
+      end
+
       @checksum =
         case hashType
         when CHECKSUM_HASH_TYPE_MD5
@@ -333,14 +361,62 @@ module Jamf
     #####################################
 
     # @return [Pathname] the local receipt when this pkg is installed by a policy
+    #############################
     def receipt
       # the receipt is the filename with any .zip extension removed.
       fileName ? (Jamf::Client::RECEIPTS_FOLDER + fileName.to_s.sub(/.zip$/, '')) : nil
     end
 
+    # Change the os_requirements field in the JSS
+    # E.g. 10.5, 10.5.3, 10.6.x
+    #
+    # Extra feature: Minumum OS's can now be specified as a
+    # string using the notation ">=10.6.7".
+    #
+    # @see Jamf.expand_min_os
+    #
+    # @param new_val [String,Array<String>] comma-separated string, or array of os versions
+    #
+    # @return [void]
+    #############################
+    def osRequirements=(new_val)
+      orig_osRequirements = osRequirements
+
+      new_val = osRequirements_as_comma_sep_string(new_val)
+      @osRequirements = new_val
+
+      note_unsaved_change :osRequirements, orig_osRequirements
+    end
+
+    # Take a value for osRequirements, and return it as a comma-separated string,
+    # possibly expanded if any of them starts with '>='.
+    #
+    # @see Jamf.expand_min_os
+    #
+    # @param val [String,Array<String>] comma-separated string, or array of os versions
+    #
+    # @return [Array<String>] the osRequirements as an array of strings
+    #############################
+    def osRequirements_as_comma_sep_string(val)
+      # make sure we have a flat array of strings
+      val = val.split(',').map(&:strip) if val.is_a? String
+      val = [val].flatten.compact.uniq.map(&:to_s)
+
+      # expand any minimum OS versions
+      val.map! do |vers|
+        vers.start_with?('>=') ? Jamf.expand_min_os(vers) : vers
+      end
+
+      val.flatten.join(', ')
+    end
+    private :osRequirements_as_comma_sep_string
+
     # Recalculate the checksum of the package file from a given filepath, and update the
     # object's checksum and hashValue attributes.
     #
+    # NOTE: This updates the checksum used when installing via a Policy.
+    # The checksum(s) used when deploying via MDM is stored in the manifest.
+    #
     # You will need to call #save on the object to save the new checksum to the server.
     #
     # New checksums are always SHA512
@@ -368,38 +444,65 @@ module Jamf
       self.class.calculate_checksum(filepath, hashType) == checksum
     end
 
-    # @return [String] The manifest file name or a default if none is set
+    # @return [String] A default if none is set explicitly
     ##############################
     def default_manifestFileName
       "#{fileName.gsub(' ', '-')}#{MANIFEST_FILENAME_DEFAULT_SUFFIX}"
     end
 
-    # Set the manifest from a local file or XML plist string.
-    # If from a file, update the manifestFileName attribute to use the filename
+    # Set the manifest from a local file or a String containing an XML plist.
+    # If from a file, the manifestFileName attribute is set to the filename
+    #
+    # To automatically generate a manifest plist for this package from a
+    # locally-readable .pkg file, use #generate_manifest
+    #
+    # All manifests require a valid URL for downloading the .pkg file when
+    # installing on a client.
     #
-    # To generate a basic manifest plist for this package, use #generate_manifest
+    # No validation of the manifest is done here.
     #
-    # When using this method, if you want to be able to deploy the pkg using
-    # #deploy_via_mdm, the manifest MUST include a metadata dictionary
-    # with at least the following keys
-    #  - 'bundle-identifier' that matches the bundle identifier of the pkg
-    #  - 'bundle-version' = the version of the pkg
-    #  - 'kind' = 'software'
-    #  - 'title' = the name of the pkg or what it installs
-    #  - 'sizeInBytes' = the size of the pkg in bytes
-    # optional keys include bundle-version, and subtitle
+    # DEPLOYING VIA MDM:
     #
-    # @param manifest [String, Pathname] the manifest plist data or path to a local file
+    # When using this method, if you want to be able to deploy the package using
+    # deploy_via_mdm, the manifest MUST include a metadata dictionary
+    # with at least the following keys:
+    #   - 'kind' = 'software'
+    #   - 'bundle-identifier' that preferably matches the bundle identifier of the pkg
+    #   - 'bundle-version' = that preferably matches the version of the pkg
+    #   - 'title' = the name of the pkg or what it installs
+    #   - 'sizeInBytes' = the size of the .pkg in bytes
+    # as well as one of these non-standard keys:
+    #   - 'sha256-whole' = the SHA256 digest of the whole file, regardless of chunking data in the 'assets' array
+    # OR
+    #   - 'md5-whole' = the MD5 digest of the whole file, regardless of chunking data in the 'assets' array
+    #
+    # The non-standard keys are because the Jamf Pro API endpoint for deploying via MDM requires
+    # a whole-file checksum even if the file is chunked in the manifest.
+    #
+    # See the MANIFEST_PLIST_TEMPLATE constant for an example of the data structure (as a ruby hash, not a plist)
+    #
+    # @param new_manifest [String, Pathname] the manifest plist data or path to a local file
     #
     # @return [void]
     ##############################
-    def manifest=(manifest)
-      if manifest.is_a? Pathname
-        @manifest = manifest.read
-        self.manifestFileName = manifest.basename.to_s
-      else
-        @manifest = manifest
-      end
+    def manifest=(new_manifest)
+      # if its a string but not an xml plist, assume its a path
+      new_manifest = Pathname.new(new_manifest) if new_manifest.is_a?(String) && !new_manifest.start_with?('<?xml')
+      orig_manifest = manifest
+
+      new_xml =
+        if new_manifest.is_a? Pathname
+          new_manifest.read
+
+        elsif new_manifest.is_a? String
+          new_manifest
+
+        else
+          raise ArgumentError, 'Argument must be a Pathname, or a String containing a path or an XML plist'
+        end
+
+      @manifest = new_xml
+      note_unsaved_change :manifest, orig_manifest
     end
 
     # return the manifest as a ruby hash converted from the plist
@@ -413,24 +516,34 @@ module Jamf
       CFPropertyList.native_types(CFPropertyList::List.new(data: manifest).value)
     end
 
-    # Generate a manifest plist (xml) for this package, update the #manifest attribute,
-    # and assign an appropriate #manifestFileName.
+    # Generate a manifest plist (xml) for this package from a local .pkg file,
+    # and update the #manifest and #manifestFileName attributes
     #
     # Afterwards, you will need to call #save on the object to save the new values to
     # the server.
     #
+    # See also #manifest= for setting the manifest from a file or string.
+    #
     # The download URL used in the manifest will be the default for the class
-    # (if you have set one) or the URL passed in, with the fileName appended. The
-    # class default may come from the ruby-jss config, or be set directly on the class.
+    # (if you have set one) usually with the fileName appended. The
+    # class default may come from the ruby-jss config, or be set directly on the class,
+    # see JPackage.default_manifest_base_url=
     #
     # Unless set explicitly afterward using #manifestFileName= the manifest filename
     # will be the fileName of the Package object, with spaces converted to dashes,
     # followed by MANIFEST_FILENAME_DEFAULT_SUFFIX.
     # e.g. my-app.pkg-manifest.plist
     #
-    # You can also generate the manifest when uploading the pkg file by providing
-    # appropriate options to #upload,
-    # in which case the new values will be saved to the Jamf Pro server automatically.
+    # By default, this method is invoked when uploading the pkg file using #upload
+    # and the opts will be passed from that method to this one.
+    # When invoked from #upload, the new values will be saved to the Jamf Pro server automatically.
+    #
+    # The manifests generated by this method are suitable for use in MDM deployments.
+    #
+    # If you don't provide a bundle_identifier, it will be generated from the packageName,
+    # prefixed with 'com.pixar.ruby-jss.' and with spaces converted to dashes.
+    #
+    # If you don't provide a bundle_version, it will be '0'
     #
     # @param filepath [String, Pathname] the path to a local copy of the package file for which
     #   this manifest is being generated. This MUST match the one uploaded to the server, as it is
@@ -450,10 +563,12 @@ module Jamf
     #   A common chunk size is 10MB, or 1024 * 1024 * 10.
     #   NOTE: Not all distribution points support chunked downloads.
     #
-    # @option opts bundle_identifier [String, Symbol] the bundle identifier of the package,
-    #   Should match that in the .pkg itself, but defaults to 'xolo.fileName'
+    # @option opts bundle_identifier [String, Symbol] The bundle identifier of the package,
+    #   Should match that in the .pkg itself.
+    #   Defaults to 'com.pixar.ruby-jss.packageName' where packageName is the
+    #   packageName with whitespace converted to dashes.
     #
-    # @option opts bundle_version [String, Symbol] the version of the package.
+    # @option opts bundle_version [String] the version of the package.
     #   Defaults to '0'
     #
     # @option opts subtitle [String] a subtitle for the package, optional
@@ -470,10 +585,12 @@ module Jamf
       validate_local_file(file)
 
       filesize = file.size
-      url = parse_manifest_url opts[:url], append_filename: opts[:append_filename_to_url]
 
       # make the manifest
       new_manifest = MANIFEST_PLIST_TEMPLATE.dup
+
+      url = build_manifest_url opts[:url], append_filename: opts[:append_filename_to_url]
+
       new_manifest[:items][0][:assets][0]['url'] = url.to_s
 
       # get the checksum(s)
@@ -486,25 +603,14 @@ module Jamf
       new_manifest[:items][0][:metadata]['title'] = packageName
       new_manifest[:items][0][:metadata]['subtitle'] = opts[:subtitle] if opts[:subtitle]
       new_manifest[:items][0][:metadata]['sizeInBytes'] = filesize
-      new_manifest[:items][0][:metadata]['bundle-identifier'] = opts[:bundle_identifier] || "xolo.#{fileName}"
-      new_manifest[:items][0][:metadata]['bundle-version'] = opts[:bundle_version] || '0'
-
-      # TESTING - store the whole-file checksum in
-      # manifest[:items][0][:metadata]['sha256-whole']. taking it from
-      # manifest[:items][0][:assets][0]['sha256s'][0], if available, or generate it if needed
-      # It is used by the deploy_via_mdm method.
-      # The test will be to deploy this pkg via MDM in a prestage, and see
-      # if the 'unknown' hash key 'sha256-whole' causes a problem installing.
-      new_manifest[:items][0][:metadata]['sha256-whole'] =
-        if new_manifest[:items][0][:assets][0]['sha256s'].size == 1
-          new_manifest[:items][0][:assets][0]['sha256s'][0]
-        else
-          new_manifest[:items][0][:assets][0]['sha256s'] = [Digest::SHA256.hexdigest(file.read)]
-        end
+      new_manifest[:items][0][:metadata]['bundle-identifier'] =
+        (opts[:bundle_identifier] || "#{MANIFEST_BUNDLE_ID_PREFIX}#{packageName.gsub(/\s+/, '-')}")
+      new_manifest[:items][0][:metadata]['bundle-version'] = opts[:bundle_version] if opts[:bundle_version]
 
       plist = CFPropertyList::List.new
       plist.value = CFPropertyList.guess(new_manifest)
-      self.manifest = plist.to_str CFPropertyList::List::FORMAT_XML, formatted: true
+      self.manifest = plist.to_str(CFPropertyList::List::FORMAT_XML, formatted: true)
+
       self.manifestFileName = default_manifestFileName
     end
 
@@ -524,12 +630,16 @@ module Jamf
     # the url is not valid.
     #
     # @param given_url [String] the URL to use, if provided
+    # @param append_filename [Boolean] should the filename be appended to the URL?
     #
     # @return [URI] the URI object for the URL
     ##############################
-    def parse_manifest_url(given_url = nil, append_filename: true)
+    def build_manifest_url(given_url = nil, append_filename: true)
       url = given_url || self.class.default_manifest_base_url
-      raise ArgumentError, 'No URL provided for manifest' unless url
+      unless url
+        raise ArgumentError,
+              'No URL for manifest. Pass one with url: or set one with Jamf::JPackage.default_manifest_base_url=, or set package_manifest_base_url in the ruby-jss.conf file.'
+      end
 
       # append the filename to the URL if needed
       url = "#{url.to_s.chomp('/')}/#{CGI.escape fileName}" unless append_filename == false
@@ -537,9 +647,10 @@ module Jamf
       # check validity and return
       URI.parse url
     end
-    private :parse_manifest_url
+    private :build_manifest_url
 
-    # calculate the manifest checksum[s] for a given file, and store in the manifest data
+    # calculate the manifest checksum[s] for a given file, and store in the manifest data.
+    # We only do SHA256, but Apple supports MD5 as well.
     #
     # @param file [Pathname] the path to the file to checksum
     # @param chunk_size [Integer] the size of each chunk in the manifest, in bytes.
@@ -564,6 +675,18 @@ module Jamf
         new_manifest[:items][0][:assets][0]['sha256-size'] = file.size
         new_manifest[:items][0][:assets][0]['sha256s'] = [Digest::SHA256.hexdigest(file.read)]
       end
+
+      # Store the whole-file checksum in
+      # manifest[:items][0][:metadata]['sha256-whole']. taking it from
+      # manifest[:items][0][:assets][0]['sha256s'][0], if available, or generate it if needed
+      # It is used by the deploy_via_mdm method.
+      # This value is required for MDM deployments, even if the file is chunked in the manifest.
+      new_manifest[:items][0][:metadata]['sha256-whole'] =
+        if new_manifest[:items][0][:assets][0]['sha256s'].size == 1
+          new_manifest[:items][0][:assets][0]['sha256s'][0]
+        else
+          Digest::SHA256.hexdigest(file.read)
+        end
     end
     private :calculate_manifest_checksums
 
@@ -583,8 +706,10 @@ module Jamf
     end
     private :append_manifest_image
 
-    # Upload a package file to Jamf Pro for this package object.
-    # After uploading, the upload response is in the @upload_response attribute.
+    # Upload a package file to Jamf Pro.
+    #
+    # WARNING: This will automatically call #save, saving any pending changes to
+    # the Jamf Pro server!
     #
     # This uses the Jamf Pro API to upload the file via the package/upload endpoint.
     # If you don't use an appropriate primary distribution point, this may not work.
@@ -594,44 +719,44 @@ module Jamf
     # If that filename is in use by some other package, you'll get an error:
     #    Field: fileName, Error: DUPLICATE_FIELD duplicate name
     #
-    # IMPORTANT: This will automatically call #save at least once, and possibly twice.
+    # This will automatically call #save at least once, and possibly twice.
     # First, in order to ensure the correct fileName in Jamf based on the file being uploaded,
     # and second, in order to update the checksum and manifest in Jamf Pro, if needed.
     # *** Any other outstanding changes will also be saved!
     #
+    # After uploading, the response from the server is in the #upload_response attribute,
+    # with a timestamp added to the data from the API.
+    #
     # @param filepath [String, Pathname] the path to the package file to upload
     #
     # @param opts[Hash] a hash of keyword arguments
     #
     # @option opts :update_checksum [Boolean] update the checksum of the package in Jamf Pro.
     #   Defaults to true. All new checksums are SHA_512.
+    #   WARNING: If you set this to false, the checksum in the object will not be updated
+    #   and installs may fail. Be sure to set it to the correct value yourself.
     #
     # @option opts :update_manifest [Boolean] update the manifest of the package in Jamf Pro
-    #   Defaults to true
+    #   Defaults to true.
+    #   WARNING: If you set this to false, the manifest in the object will not be updated
+    #   and PreStage & MDM deployments may fail. Be sure to set it to the correct value
+    #   using #generate_manifest or #manifest= yourself.
     #
-    # @options opts url [String] the URL where the package will be downloaded from,
-    #   defaults to the class default
+    # @options opts url [String] See #generate_manifest
     #
-    # @option opts append_filename_to_url [Boolean] should the fileName be appended to the URL,
-    #   defaults to true.
-    #   If false, the url given must be the full URL to download the individual package file.
+    # @option opts append_filename_to_url [Boolean] See #generate_manifest
     #
-    # @option opts chunk_size [Integer] the size of each chunk in the manifest, in bytes.
-    #   If omitted, the whole file will be checksummed at once and downloads will not be chunked.
-    #   A common chunk size is 10MB, or 1024 * 1024 * 10.
-    #   NOTE: Not all distribution points support chunked downloads.
+    # @option opts chunk_size [Integer] See #generate_manifest
     #
-    # @option opts bundle_identifier [String, Symbol] the bundle identifier of the package,
-    #   Should match that in the .pkg itself, but defaults to 'xolo.fileName'
+    # @option opts bundle_identifier [String] See #generate_manifest
     #
-    # @option opts bundle_version [String, Symbol] the version of the package.
-    #   Defaults to '0'
+    # @option opts bundle_version [String] See #generate_manifest
     #
-    # @option opts subtitle [String] a subtitle for the package, optional
+    # @option opts subtitle [String] See #generate_manifest
     #
-    # @option opts full_size_image_url [String] optional, used during MDM deployment
+    # @option opts full_size_image_url [String] See #generate_manifest
     #
-    # @option opts display_image_url [String] optional, used during MDM deployment
+    # @option opts display_image_url [String] See #generate_manifest
     #
     # @return [void]
     ##############################
@@ -640,70 +765,72 @@ module Jamf
       validate_local_file(file)
 
       # update the filename if needed
-      # must happen before the upload
-      real_filename = file.basename.to_s
-      self.fileName = real_filename unless fileName == real_filename
-      save
+      # must happen before the upload so it matches the file being uploaded
+      self.fileName = file.basename.to_s
 
-      # upload the file
-      @upload_response = cnx.jp_upload("#{get_path}/#{UPLOAD_ENDPOINT}", file)
-      @upload_response[:time] = Time.now
+      # We must save the checksum and manifest to the server before uploading
+      # the file, because otherwise jamf will likely overwrite the manifest
+      # after it uploads to the primary distribution point.
 
       # recalulate the checksum unless told no to
+      # NOTE: It appears that the checksum will always be recaluclated by
+      # the Jamf Pro server, as MD5. If you really want our default SHA512,
+      # then do this again later, manually.
       recalculate_checksum(file) unless opts[:update_checksum] == false
 
-      # generate a manifest if needed
-      generate_manifest file, **opts unless opts[:update_manifest] == false
+      # generate a manifest using the new file
+      generate_manifest(file, **opts) unless opts[:update_manifest] == false
 
-      # save the new checksum and manifest
+      # save the new fileName, checksum and manifest
       save
+
+      # upload the file
+      @upload_response = cnx.jp_upload("#{get_path}/#{UPLOAD_ENDPOINT}", file)
+      @upload_response[:time] = Time.now
+      @upload_response
     end
 
     # Deploy this package to computers or a group via MDM.
     #
     # REQUIREMENTS:
-    # - The package must have a manifest, see #generate_manifest
+    # - The package must have a manifest with specific data. See #manifest=
+    #   and #generate_manifest for details.
     # - The .pkg file must be a product archive (.pkg) built with Xcode or productbuild.
     #   (it must contain a 'Distribution' file, usually generated by those tools)
     #   Simple 'component' packages built with pkgbuild are not supported.
-    # - The .pkg file must be signed with a Developer ID Installer certificate
+    # - The .pkg file must be signed with a trusted signing certificate
     #
-    # This will send a command to install the package to one or more
-    # computers, and/or the members of a single computer group.
+    # This will send an MDM InstallEnterpriseApplication command to install the package
+    # to one or more computers, and/or the members of a single computer group.
     #
     # @param computer_ids [Array<Integer>,Integer] The ids of the computers to deploy to
     #
     # @param group_id [Integer] The id of the computer group to deploy to
     #
-    # @param managed [Boolean] Should the installed package be managed by Jamf Pro, default is false.
+    # @param managed [Boolean] Should the installed package be managed by Jamf Pro?
+    #   Defaults to false. This seems to be for App Store apps only??
     #
-    # @return [void]
+    # @return [Hash] the response from the server. see #deploy_response
     ##############################
     def deploy_via_mdm(computer_ids: nil, group_id: nil, managed: false)
-      raise Jamf::MissingDataError, 'No manifest set for this package' unless manifest
-      raise Jamf::NoSuchItemError, 'This package has no id, it must be saved in Jamf Pro before uploading' unless id
+      raise ArgumentError, 'No computer_ids or group_id provided' unless computer_ids || group_id
+      raise Jamf::MissingDataError, 'No manifest set for this package' if manifest.to_s.empty?
+      raise Jamf::NoSuchItemError, 'This package has no id, it must be saved in Jamf Pro before uploading' unless exist?
 
-      # convert the manifest to a ruby hash
+      # convert the full manifest to a ruby hash
       parsed_manifest = manifest_hash
 
       # manifest data for the MDMDeploy command, which is a hash.
       # hopefully some day Jamf will just use the manifest for the pkg
       mdm_manifest = {}
-      mdm_manifest['url'] = parsed_manifest['items'][0]['assets'][0]['url']
-      # See the TESTING note in #generate_manifest
-      mdm_manifest['hash'] = parsed_manifest['items'][0]['metadata']['sha256-whole']
-      mdm_manifest['hashType'] = CHECKSUM_HASH_TYPE_SHA256_MDM_DEPLOY
-      mdm_manifest['sizeInBytes'] = parsed_manifest['items'][0]['metadata']['sizeInBytes']
-      mdm_manifest['bundleId'] = parsed_manifest['items'][0]['metadata']['bundle-identifier']
-      mdm_manifest['bundleVersion'] = parsed_manifest['items'][0]['metadata']['bundle-version']
-      mdm_manifest['title'] = parsed_manifest['items'][0]['metadata']['title']
-
-      mdm_manifest['subtitle'] = parsed_manifest['items'][0]['metadata']['subtitle'] if parsed_manifest['items'][0]['metadata']['subtitle']
-
-      parsed_manifest['items'][0]['assets'].each do |asset|
-        mdm_manifest['fullSizeImageURL'] = asset['url'] if asset['kind'] == 'full-size-image'
-        mdm_manifest['displayImageURL'] = asset['url'] if asset['kind'] == 'display-image'
-      end
+      mdm_manifest['url'] = manifest_url_for_deployment(parsed_manifest)
+      mdm_manifest['hash'], mdm_manifest['hashType'] = manifest_checksum_for_deployment(parsed_manifest)
+      mdm_manifest['bundleId'] = manifest_bundle_identifier_for_deployment(parsed_manifest)
+      mdm_manifest['bundleVersion'] = manifest_bundle_version_for_deployment(parsed_manifest)
+      mdm_manifest['title'] = manifest_title_for_deployment(parsed_manifest)
+      mdm_manifest['sizeInBytes'] = manifest_size_for_deployment(parsed_manifest)
+
+      set_optional_mdm_manifest_values(parsed_manifest, mdm_manifest)
 
       # make sure the computers are in an array
       computer_ids = [computer_ids].flatten.compact.uniq
@@ -712,13 +839,100 @@ module Jamf
       payload = {
         manifest: mdm_manifest,
         installAsManaged: managed,
-        devices: computer_ids,
-        groupId: group_id.to_s
+        devices: computer_ids
       }
+      payload[:groupId] = group_id.to_s if group_id
+
       # send the command
       @deploy_response = cnx.post(DEPLOYMENT_ENDPOINT, payload)
     end
 
+    # the URL is required for MDM deployments
+    # @param parsed_manifest [Hash] the parsed manifest data as a ruby hash
+    # @return [String] the URL in the manifest for MDM deployments
+    #####################################
+    def manifest_url_for_deployment(parsed_manifest)
+      url = parsed_manifest.dig 'items', 0, 'assets', 0, 'url'
+      raise Jamf::MissingDataError, 'No URL in the manifest' unless url
+
+      url
+    end
+    private :manifest_url_for_deployment
+
+    # whole-file checksums are required for MDM deployments
+    # @return [Array<String>] the checksum and checksum type in the manifest for MDM deployments
+    #####################################
+    def manifest_checksum_for_deployment(parsed_manifest)
+      if whole = parsed_manifest.dig('items', 0, 'metadata', 'sha256-whole')
+        [whole, CHECKSUM_HASH_TYPE_SHA256_MDM_DEPLOY]
+      elsif whole = parsed_manifest.dig('items', 0, 'metadata', 'md5-whole')
+        [whole, CHECKSUM_HASH_TYPE_MD5]
+      else
+        raise Jamf::MissingDataError, 'No whole-file checksum in the manifest. Must have either sha256-whole or md5-whole in the metadata'
+      end
+    end
+    private :manifest_checksum_for_deployment
+
+    # size in bytes is required for MDM deployments
+    # @return [Integer] the size in bytes in the manifest for MDM deployments
+    #####################################
+    def manifest_size_for_deployment(parsed_manifest)
+      size = parsed_manifest.dig 'items', 0, 'metadata', 'sizeInBytes'
+      raise Jamf::MissingDataError, 'No sizeInBytes in the manifest metadata' unless size
+
+      size
+    end
+    private :manifest_size_for_deployment
+
+    # bundle identifier is required for MDM deployments
+    # @return [String] the bundle identifier in the manifest for MDM deployments
+    #####################################
+    def manifest_bundle_identifier_for_deployment(parsed_manifest)
+      bid = parsed_manifest.dig 'items', 0, 'metadata', 'bundle-identifier'
+      raise Jamf::MissingDataError, 'No bundle-identifier in the manifest metadata' unless bid
+
+      bid
+    end
+    private :manifest_bundle_identifier_for_deployment
+
+    # bundle version is required for MDM deployments
+    # @return [String] the bundle version in the manifest for MDM deployments
+    #####################################
+    def manifest_bundle_version_for_deployment(parsed_manifest)
+      bv = parsed_manifest.dig 'items', 0, 'metadata', 'bundle-version'
+      raise Jamf::MissingDataError, 'No bundle-version in the manifest metadata' unless bv
+
+      bv
+    end
+    private :manifest_bundle_version_for_deployment
+
+    # title is required for MDM deployments
+    # @return [String] the title in the manifest for MDM deployments
+    #####################################
+    def manifest_title_for_deployment(parsed_manifest)
+      ttl = parsed_manifest.dig 'items', 0, 'metadata', 'title'
+      raise Jamf::MissingDataError, 'No title in the manifest metadata' unless ttl
+
+      ttl
+    end
+    private :manifest_title_for_deployment
+
+    # set the optional values for the MDM deployment manifest
+    # @return [void]
+    #####################################
+    def set_optional_mdm_manifest_values(parsed_manifest, mdm_manifest)
+      # subtitle is optional for MDM deployments
+      sttl = parsed_manifest.dig 'items', 0, 'metadata', 'subtitle'
+      mdm_manifest['subtitle'] = sttl if sttl
+
+      # Images are optional for MDM deployments
+      parsed_manifest['items'][0]['assets']&.each do |asset|
+        mdm_manifest['fullSizeImageURL'] = asset['url'] if asset['kind'] == 'full-size-image'
+        mdm_manifest['displayImageURL'] = asset['url'] if asset['kind'] == 'display-image'
+      end
+    end
+    private :set_optional_mdm_manifest_values
+
   end # class
 
 end # module