ruby-jss 1.0.0b2 → 1.0.0b6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e2cda3beb0c57a922fa2bae9be0ed07ddb0ad3f4
-  data.tar.gz: a5c707f859c044e7d7021b9e6c7d4a0c5f6900a9
+SHA256:
+  metadata.gz: b7a56f45bbacab2bbc21539605b30f7bedbaef3672a639d2f32b80d766352090
+  data.tar.gz: d9ade8517e722087ae3fc6fe4ed79c01b938a01a1e5b556c3df6ca2b294282d1
 SHA512:
-  metadata.gz: 2f655fcf07b79416bcccef6eceacec0c023e7fccb4507c4588df60c38c7a40c226951539eecdaa85dd094e3fbcd9682417e04e20b371ceeb1e2f1ac6d1422b8c
-  data.tar.gz: 60e672418b4fff07a72df15cbe2e8aa5963566db72425c1640a11bf0355a8f79ef196783c74dbeff2f983da143a3d10971d333598ee243190279d3199c22acef
+  metadata.gz: 81be4beedc05189fb45f8978895458c1ee9ee70eaee7755c90bd3b7f9af01084f39593b5caaea77973ad20d41e317e40235a5307d4279ebc84dcd9e780120095
+  data.tar.gz: 0afc5a122964e84d1869a5c4f9914d0b790d91f641a1b76aa1673640bea0a501449e6d59c653fcec3adc0b3f14e00d6ae18350b2a988be32d4dc415b0f92fd30

data/.yardopts

@@ -1,4 +1,4 @@
---title "The JSS API Ruby Gem - access to the Casper Suite API"
+--title "ruby-jss: access to the Jamf Pro 'Classic' API"
 --readme README.md
 --embed-mixins
 -

data/CHANGES.md

@@ -1,35 +1,73 @@
 # Change History
 
-## v 1.0.0b2, 2018-06-x26
+## v 1.0.0, 2018-08-10
+
+Finally we're going to version 1.0, which we should have done when we went opensource. Future releases will try to adhere to [Semantic Versioning](https://semver.org/) as described in the [rubygems.org guidelines](https://guides.rubygems.org/patterns/#semantic-versioning)
+
+**IMPORTANT** This version is not backward compatible with 0.x version. Please read the details below and test your code before deploying widely.
+
 
-Finally we're going to version 1.0, which we should have done when we went opensource.
 
 - requirement: Jamf Pro API version must be 10.4 or higher
 
+- change: defaults to using TLSv1.2 for API connections.
+
+  As of Jamf Pro 10.5. the server requires TLSv1.2 and will not accept connections using TLSv1.
+
+  **COMPATIBILITY:**
+
+  MacOS 10.12 and lower have an old version of the openssl library which used by the built-in ruby (/usr/bin/ruby), which does not support TLSv1.2.
+
+  If you are using macOS 10.12 or lower to connect to Jamf Pro 10.4 (the lowest Jamf server supported by this version of ruby-jss), you must specify the older TLS when using APIConnection#connect, e.g.
+
+  `JSS.api.connect server: 'myjss.myschool.edu', user: 'username', pw: :prompt, ssl_version: :TLSv1`
+
+  Machines running macOS 10.12 or lower will not be able to connect to Jamf Pro > v10.4 with the built-in ruby openssl library. If you specify `ssl_version: :TLSv1` you will get an error because the server won't accept it. If you leave the default :TLSv1_2, ruby's openssl library will complain that it doesn't know about that.
+
+  If you have 10.12 or older machines that must connect to newer Jamf Pro servers with ruby-jss, there are a few options.
+
+  - upgade the machines to 10.13 or higher
+  - install a newer openssl, then install a your own ruby using that openssl (both can be done with homebrew)
+  - do the above, then extract the openssl library and modify it to work with the built-in ruby.
+
+  If you have questions about this, feel free to reach out to ruby-jss@pixar.com, or in the #ruby or #jss-api channels in MacAdmins slack space, for some advice.
+
 - add: JSS::PatchSource metaclass and the subclassses JSS::PatchInternalSource, and JSS::PatchExternalSource. These provide acecss to the patchavailabletitles enpoint, which is needed to acquire name_id's for creating/activating JSS::PatchTitles
 
-- add: JSS::PatchTitle, which also gives access to the patchreports endpoint. Also uses the JSS::PatchTitle::Version class to handle patch versions within a title, and assign packages to them.
+- add: JSS::PatchTitle, which also gives access to the patchreports endpoint. Also uses the JSS::PatchTitle::Version class to handle patch versions within a title, and assign packages to them. **WARNING**: ruby-jss will now allow duplicate 'display names' (the #name of the JSS::PatchTitle instance) - but the Jamf Web UI will allow duplicates. If you have duplicates, and retrieve PatchTitles by name, which one gets returned to you is undefined.
+
+  - The 'source_id' and 'name_id' of a patch title are, when combined, a unique identifier in the JSS (i.e. name_id's are unique within sources) As such, the PatchTitle.all list provides a :source_name_id key, which is a String made by joining the two values with a '-', e.g. '1-GoogleChrome'.  This value can be used as a lookup for .fetch, e.g. `JSS::PatchTitle.fetch source_name_id: '1-GoogleChrome'`. There is also a matching .all_source_name_ids method, and the .map_all_ids_to() method takes :source_name_id as a mapping parameter. You can also use .fetch and .make with both source: (id or name) and  name_id: specified.
+
 
-- add: JSS::PatchPolicy. PatchPolicies are creatable when providing an active PatchTitle and an approiate PatchTitle::Version that has a package assigned to it.
+- add: JSS::PatchPolicy. PatchPolicies are creatable when providing an active PatchTitle and an appropriate PatchTitle::Version that has a package assigned to it.
 
 - add: the Group metaclass now has a calculate_members option (bool) to the #create method. When true, the membership of the group will be updated in the existing ruby instance immediately after the group is created in the JSS. Doesn't do much for static groups, but is useful for smart groups. Defaults to true. If you don't care about the membership immediately, or don't want to wait for the membership to be calculated on the server, set this to false.
 
 - improvement: better handling of http error responses
 
+- improvement: JSS::Policy objects now have setters for the 'Maintenence' subset, e.g. recons ('update inventory'), reset_name, fix_byhost, etc.
+
 - add: more generic data validation methods in JSS::Validate module, and more use of them throughout the code.
 
 - add: 'support' in SelfServable for notifications - note that there are API bugs limiting the usefulness of this.
 
 - add: regex options to JSS::Criteriable::Criterion objects
 
-- remove: the .new class method on APIObject subclasses no longer works. Even thought its the standard ruby way to create instances of a class, it was confusing, since it implied creating new objects in the JSS.  Instead you must now use .fetch to instantiate existing objects and .make to instantiate local instances of objects to be created in the JSS.
+- remove: the .new class method on APIObject subclasses no longer works. Even though it's the standard ruby way to create instances of a class, it was confusing, since it implied creating new objects in the JSS.  Instead you must now use the .fetch class method to instantiate existing objects and the .make class method to instantiate local instances of objects to be created in the JSS.
+
+  **COMPATIBILITY:**
+
+  `existingcomp = JSS::Computer.new id: 1234` and `new_pol = JSS::Policy.new id: :new, name: 'mypolicy'` will now raise an error.
+
+  Instead you must use `existingcomp = JSS::Computer.fetch id: 1234` and `new_pol = JSS::Policy.make name: 'mypolicy'`
 
-- update: API connections now default to TLSv1.2. If you're connecting from a machine that doesn't support  TLSv1.2 (like the os-supplied ruby in macOS < 10.13) then you can specify `ssl_version: 'TLSv1'` when you connect, as long as your Jamf Pro server supports it.
+  Note that the instance methods #create (create the current instance as a new object in the JSS) and #update (send changes in the current instance to the JSS) remain unchanged, and both continue handled by #save
 
-- add: there is now a, sort-of, spec/testing framework. While based on ruby's minitest specifications, its wrapped in a very custom executable with a helper module. See the README in the test directory for details.  Specs will be added slowly over time.
+- add: there is now a, sort-of, spec/testing framework. While based on ruby's minitest specifications, it's wrapped in a very custom executable with a helper module. See the README in the test directory for details.  Specs will be added slowly over time.
 
-- fix: as Apple says: various bugfixes and improvements.
+- add: JSS::Client now has a .management_action class method, which wraps around the 'Management Action.app' tool that comes with Jamf Pro and creates Notification Center notifications. At the moment support is minimal, and the notification type (alert vs. banner) is up to the User.
 
+- misc: as Apple says: various bugfixes and improvements.
 
 ## v 0.14.0, 2018-05-30
 

data/README.md

@@ -27,13 +27,13 @@
 
 ## DESCRIPTION
 
-The ruby-jss project provides a Ruby module called JSS, which is used for accessing the REST API of
+ruby-jss defines a Ruby module called JSS, which is used for accessing the 'classic' REST API of
 the JAMF Software Server (JSS), the core of Jamf Pro, an enterprise-level management tool for Apple
 devices from [Jamf.com](http://www.jamf.com/). It is available as a
 [rubygem](https://rubygems.org/gems/ruby-jss), and the
 [source is on github](https://github.com/PixarAnimationStudios/ruby-jss).
 
-The module abstracts API resources as Ruby objects, and provides methods for interacting with those
+The module abstracts many API resources as Ruby objects, and provides methods for interacting with those
 resources. It also provides some features that aren't a part of the API itself, but come with other
 Jamf-related tools, such as uploading .pkg and .dmg {JSS::Package} data to the master distribution
 point, and the installation of {JSS::Package} objects on client machines. (See [BEYOND THE API](#beyond-the-api))
@@ -47,7 +47,6 @@ Hopefully others will find it useful, and add more to it as well.
 
 [Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
 
-
 ## SYNOPSIS
 
 Here are some simple examples of using ruby-jss
@@ -157,8 +156,8 @@ Some classes can use more than just the :id and :name keys for lookups, e.g. com
 
 You can even fetch objects without specifying the kind of identifier, e.g. `JSS::Computer.fetch 3241`, but this will be slower, since ruby-jss searches by matching the given value with all available identifiers, returning the first match.
 
-*NOTE*: A class's '.fetch' method is now the preferred method to use for retrieving existing objects.
-The '.new' method still works as before, but is deprecated for object retrieval and doing so may raise errors in the future. See below for using .make to create new objects in the JSS.
+*NOTE*: For APIObject subclasses, the '.fetch' class method is now the required method to use for retrieving existing objects
+from the API. The '.new' method no longer works. See below for using .make to create new objects in the JSS.
 
 --------
 
@@ -185,7 +184,9 @@ Then use the #create method to create it in the JSS. The #save method is an alia
 new_pkg.create # returns 453, the id number of the object just created
 ```
 
-*NOTE*: A class's '.make' method is now the preferred method to use for creating new objects. The '.new id: :new' method still works as before, but is deprecated for object creation and doing so may raise errors in the future.
+*NOTE*: For APIObject subclasses, the '.make' class method is now the required method to use for making ruby instances to be
+created in the JSS. The '.new' method no longer works.
+
 
 --------
 
@@ -240,6 +241,7 @@ Here's what we've implemented so far. See each Class's [documentation(http://www
 * {JSS::ComputerExtensionAttribute}
 * {JSS::ComputerGroup}
 * {JSS::Department}
+* {JSS::DistributionPoint}
 * {JSS::MobileDeviceApplication}
 * {JSS::MobileDeviceExtensionAttribute}
 * {JSS::MobileDeviceGroup}
@@ -258,6 +260,10 @@ Here's what we've implemented so far. See each Class's [documentation(http://www
 * {JSS::Computer}
 * {JSS::MobileDevice}
 * {JSS::Policy} (still not fully implemented)
+* {JSS::PatchInternalSource}
+* {JSS::PatchExternalSource}
+* {JSS::PatchTitle}
+* {JSS::PatchPolicy}
 
 **NOTE** Computer and Mobile Device data gathered by an Inventory Upate (a.k.a. 'recon') is not editable.
 
@@ -368,26 +374,6 @@ While the Jamf Pro API provides access to object data in the JSS, this gem tries
 * Extension Attributes
   * {JSS::ExtensionAttribute} work with {JSS::AdvancedSearch} subclasses to provide extra reporting about Ext. Attrib. values.
 
-## REQUIREMENTS
-
-ruby-jss was written for:
-
-* Mac OS X 10.9 or higher
-* Ruby 2.0 or higher
-* Casper Suite version 9.4 or higher
-
-It also requires these gems, which will be installed automatically if you install JSS with `gem install jss`
-
-* rest-client >=1.6.7  ( >= 1.7.0 with Casper >= 9.6.1) http://rubygems.org/gems/rest-client
-* json or json\_pure >= 1.6.5 http://rubygems.org/gems/json or http://rubygems.org/gems/json_pure
-  * (only in ruby 1.8.7.  Ruby >= 1.9 has json in its standard library)
-* ruby-mysql >= 2.9.12 http://rubygems.org/gems/ruby-mysql
-  * (only for a few things that still require direct SQL access to the JSS database)
-* plist =3.1.0 http://rubygems.org/gems/plist
-  * for the {JSS::Composer} module and {JSS::Client} class
-* net-ldap >= 0.3.1 http://rubygems.org/gems/net-ldap
-  * for accessing the LDAP servers defined in the JSS, to check for user and group info.
-
 ## INSTALL
 
 NOTE: You may need to install XCode, and it's CLI tools, in order to install the required gems.
@@ -396,10 +382,23 @@ In general, you can install ruby-jss with this command:
 
 `gem install ruby-jss`
 
+## REQUIREMENTS
+
+ruby-jss was written for:
+
+* Mac OS X 10.9 or higher
+* Ruby 2.0 or higher
+* Casper Suite version 10.4 or higher
+
+It also requires other ruby gems, which will be installed automatically if you install with `gem install ruby-jss`
+See the .gemspec file for details
+
 
 ## HELP
 
-Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/)
+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.
 
 [Email the developers](mailto:ruby-jss@pixar.com)
 

data/bin/cgrouper

@@ -207,9 +207,9 @@ class App
 
      # get the group from the API
       if @options.action == :create_group
-        @group = JSS::ComputerGroup.new :id => :new, :name => @options.group, :type => :static
+        @group = JSS::ComputerGroup.make :name => @options.group, :type => :static
       else
-        @group = JSS::ComputerGroup.new :name => @options.group
+        @group = JSS::ComputerGroup.fetch :name => @options.group
       end
 
     end # if ACTIONS_NEEDING_GROUP

data/bin/jamfHelperBackgrounder

@@ -40,8 +40,6 @@
 # == Author
 #   Chris Lasell <chrisl@pixar.com>
 #
-# == Copyright
-#   Copyright (c) 2017 Pixar Animation Studios
 ##############################
 
 require 'ruby-jss'

data/bin/netseg-update

@@ -322,8 +322,7 @@ Notes:
       end # if noop
 
       ender = @use_cidr ? :cidr : :ending_address
-      new_seg = JSS::NetworkSegment.new(
-        :id => :new,
+      new_seg = JSS::NetworkSegment.make(
         :name => seg,
         :starting_address => seg_data[:starting],
         ender => seg_data[:ending]
@@ -339,7 +338,7 @@ Notes:
         puts "Without --no-op this would: Delete segment named '#{seg}',"
         next
       end # if noop
-      JSS::NetworkSegment.new(name: seg).delete
+      JSS::NetworkSegment.fetch(name: seg).delete
       puts "Deleted Network Segment '#{seg}' from the JSS"
     end #  @segments_to_delete.each do |seg|
   end # delete_segments
@@ -354,7 +353,7 @@ Notes:
                    IPAddr.new(seg_data[:ending])
                  end
 
-      this_seg = JSS::NetworkSegment.new name: seg
+      this_seg = JSS::NetworkSegment.fetch name: seg
       data_range = data_start..data_end
       next if this_seg.range == data_range
 

data/data/ruby-jss.conf.example

@@ -57,7 +57,7 @@ api_server_port:
 ###   The SSL version to use for the API connection
 ###
 ###   If you leave this blank:
-###   Defaults to 'TLSv1'
+###   Defaults to 'TLSv1_2'
 ###
 api_ssl_version:
 
@@ -75,14 +75,8 @@ api_verify_cert:
 ### - api_username
 ###   The username to use when making an API connection.
 ###
-###   *** REQUIRED ***
-###
 ###   Note that the passwords are not storeable here!!
-###     see https://github.com/PixarAnimationStudios/ruby-jss/blob/master/README.md#passwords
-###
-###   If you leave this blank:
-###   d3 may break, as well as any other code that
-###   expects a configured api user name
+###     see https://github.com/PixarAnimationStudios/ruby-jss/blob/master/README.md#password
 ###
 api_username:
 

data/lib/jss/api_connection.rb

@@ -336,6 +336,7 @@ module JSS
 
     # @return [Boolean] are we connected right now?
     attr_reader :connected
+    alias connected? connected
 
     # @return [JSS::Server] the details of the JSS to which we're connected.
     attr_reader :server
@@ -509,14 +510,19 @@ module JSS
     def get_rsrc(rsrc, format = :json)
       # puts object_id
       validate_connected
+
       raise JSS::InvalidDataError, 'format must be :json or :xml' unless %i[json xml].include? format
 
+      # TODO: fix what rubocop is complaining about in the line below.
+      # (I doubt we want to CGI.escape the whole resource)
       rsrc = URI.encode rsrc
       begin
         @last_http_response = @cnx[rsrc].get(accept: format)
       rescue RestClient::ExceptionWithResponse => e
         handle_http_error e
       end
+      # TODO: make sure we're returning the String version of the
+      # response (i.e. its body) here and in POST, PUT, DELETE.
       format == :json ? JSON.parse(@last_http_response, symbolize_names: true) : @last_http_response
     end
 
@@ -625,9 +631,6 @@ module JSS
       srvr ||= JSS::Client.jss_server
       srvr
     end
-
-    # aliases
-    alias connected? connected
     alias host hostname
 
     #################

data/lib/jss/api_object/advanced_search.rb

@@ -210,7 +210,7 @@ module JSS
       @api.timeout = 1800
       @api.open_timeout = 1800
       begin
-        requery = self.class.new(id: @id)
+        requery = self.class.fetch(id: @id)
         @search_results = requery.search_results
         @result_display_keys = requery.result_display_keys
       ensure

data/lib/jss/api_object/computer_invitation.rb

@@ -172,7 +172,7 @@ module JSS
     def create
       new_invitation_id = super
 
-      jss_me = ComputerInvitation.new(id: new_invitation_id, name: 'set_by_request')
+      jss_me = ComputerInvitation.fetch(id: new_invitation_id, name: 'set_by_request')
       @name = jss_me.name
       @invitation_type = jss_me.invitation_type
       @create_account_if_does_not_exist = jss_me.create_account_if_does_not_exist

data/lib/jss/api_object/criteriable.rb

@@ -81,7 +81,7 @@ module JSS
   ###   crta = JSS::Criteriable::Criteria.new [crtn_0, crtn_1]
   ###
   ###   # create a new Advanced Search
-  ###   srch = JSS::AdvancedComputerSearch.new :id => :new, :name => "my computer search"
+  ###   srch = JSS::AdvancedComputerSearch.make, :name => "my computer search"
   ###   srch.display_fields = ["Computer Name"]
   ###
   ###   # add our Criteria to it

data/lib/jss/api_object/ebook.rb

@@ -1,3 +1,28 @@
+### Copyright 2018 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
 # This is just a stub for now.
 
 #

data/lib/jss/api_object/group.rb

@@ -106,7 +106,7 @@ module JSS
     # Constructor
     #####################################
 
-    # When creating a new group in the JSS, you must call .new with a :type key
+    # When creating a new group in the JSS, you must call .make with a :type key
     # and a value of :smart or :static, as well as a :name and the :id => :new
     #
     # @see JSS::APIObject

data/lib/jss/api_object/mobile_device_application.rb

@@ -424,7 +424,7 @@ module JSS
     #
     def upload_ipa(path)
       new_ipa = Pathname.new path
-      upload(:app, new_icon)
+      upload(:app, new_ipa)
       refresh_ipa
     end
 

data/lib/jss/api_object/patch_title.rb

@@ -36,8 +36,20 @@ module JSS
   # attribute, a Hash of versions keyed by the version string. The values are
   # JSS::PatchTitle::Version objects.
   #
-  # Use the patch_report method on the PatchTitle class, an instance of it, or
-  # a PatchTitle::Version, to retrieve a report of computers with a
+  # When creating/activating new Patch Titles, with .make, a unique name:, a
+  # source: and a name_id: must be provided - the source must be the name or id
+  # of an existing PatchSource, and the name_id must be offered by that source.
+  # Once created, the source_id and name_id cannot be changed.
+  #
+  # When fetching titles, they can be fetched by id:, source_name_id:, or both
+  # source: and name_id:
+  #
+  # WARNING: While they can be fetched by name, beware: the JSS does not enforce
+  # unique names of titles even thought ruby-jss does. If there are duplicates
+  # of the name you fetch, which one you get is undefined.
+  #
+  # Use the patch_report class or instance method, or
+  # PatchTitle::Version.patch_report, to retrieve a report of computers with a
   # specific version of the title installed, or :all, :latest, or :unknown
   # versions. Reports called on the class or an instance default to :all
   # versions, and are slower to retrieve than a specific version,
@@ -152,7 +164,10 @@ module JSS
     # source_id: parameter, which limites the results to
     # patch titles with the specified source_id.
     #
-    # ALSO, JAMF BUG: More broken json - the id is coming as a string.
+    # Also - since the combined source_id and name_id are unique, create an
+    # identifier key ':source_name_id' by joining them with '-'
+    #
+    # JAMF BUG: More broken json - the id is coming as a string.
     # so here we turn it into an integer manually :-(
     # Ditto for source_id
     #
@@ -160,6 +175,7 @@ module JSS
       data = super refresh, api: api
       data.each do |info|
         info[:id] = info[:id].to_i
+        info[:source_name_id] = "#{info[:source_id]}-#{info[:name_id]}"
         info[:source_id] = info[:source_id].to_i
       end
       return data unless source_id
@@ -182,12 +198,6 @@ module JSS
       all(refresh, source_id: source_id, api: api).map { |i| i[:id] }
     end
 
-    # @return [Array<String>] all 'name_id' values for active patches
-    #
-    def self.all_name_ids(refresh = false, source_id: nil, api: JSS.api)
-      all(refresh, source_id: source_id, api: api).map { |i| i[:name_id] }
-    end
-
     # Returns an Array of unique source_ids used by active Patches
     #
     # e.g. if there are patches that come from one internal source
@@ -207,6 +217,12 @@ module JSS
       all(refresh, api: api).map { |i| i[:source_id] }.sort.uniq
     end
 
+    # @return [Array<String>] all 'source_name_id' values for active patches
+    #
+    def self.all_source_name_ids(refresh = false, api: JSS.api)
+      all(refresh, api: api).map { |i| i[:source_name_id] }
+    end
+
     # Get a patch report for a softwaretitle, withouth fetching an instance.
     # Defaults to reporting all versions. Specifiying a version will be faster.
     #
@@ -280,18 +296,50 @@ module JSS
     end
     private_class_method :patch_report_rsrc
 
-    # for some reason, patch titles can't be fetched by name.
-    # only by id. SO, look up the id if given a name.
+    # Patch titles only have an id-based GET resource in the API.
+    # so all other lookup values have to be converted to ID before
+    # the call to super
     #
-    def self.fetch(id: nil, name: nil, api: JSS.api)
-      unless id
-        id =  JSS::PatchTitle.map_all_ids_to(:name).invert[name]
-        raise NoSuchItemError, "No matching #{self::RSRC_OBJECT_KEY} found" unless id
-      end
+    def self.fetch(identifier = nil, **params)
+      # default api
+      api = params[:api] ? params[:api] : JSS.api
+
+      # source: and source_id: are considered the same, source_id: wins
+      params[:source_id] ||= params[:source]
+
+      # if given a source name, this converts it to an id
+      params[:source_id] = JSS::PatchSource.valid_id params[:source_id]
+
+      # build a possible source_name_id
+      params[:source_name_id] ||= "#{params[:source_id]}-#{params[:name_id]}"
+
+      id =
+        if identifier
+          valid_id identifier
+        elsif params[:id]
+          all_ids.include?(params[:id]) ? params[:id] : nil
+        elsif params[:source_name_id]
+          map_all_ids_to(:source_name_id).invert[params[:source_name_id]]
+        elsif params[:name]
+          map_all_ids_to(:name).invert[params[:name]]
+        end
+
+      raise JSS::NoSuchItemError, "No matching #{name} found" unless id
 
       super id: id, api: api
     end
 
+    # Override the {APIObject.valid_id}, since patch sources are so non-standard
+    # Accept id, source_name_id, or name.
+    # Note name may not be unique, and if not, ymmv
+    #
+    def self.valid_id(ident, refresh = false, api: JSS.api)
+      id = all_ids(refresh, api: api).include?(ident) ? ident : nil
+      id ||= map_all_ids_to(:source_name_id).invert[ident]
+      id ||= map_all_ids_to(:name).invert[ident]
+      id
+    end
+
     # Attributes
     #####################################
 
@@ -303,6 +351,9 @@ module JSS
     #   for this title
     attr_reader :source_id
 
+    # @return [String] the source_id and name_id joined by '-', a unique identifier
+    attr_reader :source_name_id
+
     # @return [Boolean] Are new patches announced in the JSS web ui?
     attr_reader :web_notification
     alias web_notification? web_notification
@@ -311,17 +362,31 @@ module JSS
     attr_reader :email_notification
     alias email_notification? email_notification
 
-    # @return [Hash{String => JSS::PatchTitle::Version}] The JSS::PatchVersions fetched for
-    #   this title, keyed by version string
-    attr_reader :versions
-
-    # PatchTitles may be fetched by name: or id:
     #
     def initialize(**args)
       super
 
-      @name_id = @init_data[:name_id]
-      @source_id = @init_data[:source_id]
+      if in_jss
+        @name_id = @init_data[:name_id]
+        @source_id = @init_data[:source_id]
+      else
+        # source: and source_id: are considered the same, source_id: wins
+        @init_data[:source_id] ||= @init_data[:source]
+
+        raise JSS::MissingDataError, 'source: and name_id: must be provided' unless @init_data[:name_id] && @init_data[:source_id]
+
+        @source_id = JSS::PatchSource.valid_id(@init_data[:source_id])
+
+        raise JSS::NoSuchItemError, "No Patch Sources match '#{@init_data[:source]}'" unless source_id
+
+        @name_id = @init_data[:name_id]
+
+        valid_name_id = JSS::PatchSource.available_name_ids(@source_id).include? @name_id
+
+        raise JSS::NoSuchItemError, "source #{@init_data[:source]} doesn't offer name_id '#{@init_data[:name_id]}'" unless valid_name_id
+      end
+
+      @source_name_id = "#{@source_id}-#{@name_id}"
 
       @init_data[:notifications] ||= {}
       notifs = @init_data[:notifications]
@@ -337,6 +402,16 @@ module JSS
       @changed_pkgs = []
     end
 
+    # @return [Hash{String => JSS::PatchTitle::Version}] The JSS::PatchVersions fetched for
+    #   this title, keyed by version string
+    def versions
+      return @versions unless in_jss
+      return @versions unless @versions.empty?
+      # if we are in jss, and versions is empty, re-fetch them
+      @versions = self.class.fetch(id: id).versions
+    end
+
+
     # @return [Hash] Subset of @versions, containing those which have packages
     #   assigned
     #
@@ -376,33 +451,14 @@ module JSS
       @need_to_update = true
     end
 
-    def source_id=(new_id)
-      sid = JSS::PatchSource.valid_patch_source_id new_id
-      raise JSS::NoSuchItemError, "No active Patch Sources matche '#{new_id}'" unless sid
-      return if sid == source_id
-      @source_id = sid
-      @need_to_update = true
-    end
-
-    def name_id=(new_id)
-      return if new_id == name_id
-      raise JSS::MissingDataError, 'source_id must be set before setting name_id' if source_id.to_s.empty?
-      raise JSS::NoSuchItemError, "source_id #{source_id} doesn't offer name_id '#{new_id}'" unless JSS::PatchSource.available_name_ids(source_id).include? new_id
-      @name_id = new_id
-      @need_to_update = true
-    end
-
     # wrapper to fetch versions after creating
     def create
-      validate_for_saving
       response = super
-      @versions = self.class.fetch(id: id).versions
       response
     end
 
     # wrapper to clear @changed_pkgs after updating
     def update
-      validate_for_saving
       response = super
       @changed_pkgs.clear
       response
@@ -433,10 +489,6 @@ module JSS
     #################################
     private
 
-    def validate_for_saving
-      raise JSS::MissingDataError, 'PatchTitles must have valid source_id and name_id' if source_id.to_s.empty? || name_id.to_s.empty?
-    end
-
     # Return the REST XML for this title, with the current values,
     # for saving or updating.
     #