class Jamf::APIConnection

Instances of this class represent a connection to a Jamf Pro server, using both the Classic and Jamf Pro APIs.

For most cases, a single connection to a single JSS is all you need, and ruby-jss automatically creates and uses a default connection. See {Jamf.connect}

If needed, multiple connection objects can be made and used sequentially or simultaneously.

NOTE: Individual connection instances are not thread-safe and should not be shared by multple simultaneous threads (such as with a multi-threaded http server like ‘thin’) or used for concurrent API access. In those cases, do not use the default connection, but be sure to design your application to create different API connections for each thread, and pass them into method calls as needed

Using the default connection

When ruby-jss is loaded, a not-yet-connected default instance of Jamf::Connection is created and available using {JSS.cnx}.

This connection is used as the initial default connection so all methods that make API calls will use it by default. For most uses where you’re only going to be working with one connection to one JSS, the default connection is all you need.

Before using it you must call its {#connect} method, passing in appropriate connection details and credentials.

Example:

require 'ruby-jss'
Jamf.connect host: 'server.address.edu', user: 'jss-api-user', pw: :prompt
# (see {Jamf::Connection#connect} for all the connection options)

a_phone = Jamf::MobileDevice.fetch id: 8743

# the mobile device was fetched through the default connection

If needed, you can re-login to the default connection by calling Jamf.connect with new connection parameters. You can also call JSS.disconnect to close the connection

Using standalone Connections

Sometimes you need to connect simultaneously to more than one JSS. or to the same JSS with different credentials, or you just need multiple concurrent connections for asyncronous, thread-safe use. ruby-jss allows you to create as many connections as needed, and pass them into the methods that communication with the API via the ‘cnx:` parameter (the older `api:` parameter is deprecated and will eventually not be recognized)

Example:
  my_connection = Jamf::Connection.new(params: go, in: here)
  a_computer = Jamf::Computer.fetch id: 1234, cnx: my_connection

  # the Jamf::Computer with id 1234 is fetched from the connection
  # stored in the variable 'my_connection'. The computer is
  # then stored in the variable 'a_computer'

NOTE: When an obbject is retrieved or created it stores an internal reference to the Connection object that it was made with, and uses that when making future API calls.

So in the example above, when saving any changes to a_computer, the Connection object ‘my_connection’ will (and must) be used.

Similiarly, each Connection object maintains its own caches for the data used by the ‘list` methods (e.g. Jamf::Computer.all, .all_names, and so on)

Making new APIConnection instances

New connections can be created using the standard ruby ‘new’ method.

If you provide connection details when calling ‘new’, they will be passed to the {#connect} method immediately. Otherwise you can call {#connect} later.

production_server = Jamf::Connection.new(
  'https://produser@prodserver.address.org:8443/'
  name: 'prod',
  pw: :prompt
)

# the new connection is now stored in the variable 'production_api'.

Passing an APIConnection object to API-related methods

All methods that use the API can take an ‘cnx:’ parameter which takes a Connection object. When provided, that connection is used rather than the active connection. The older, deprecated synonym ‘api:’ will eventually be removed.

For example:

prod2_computer_sns = Jamf::Computer.all_serial_numbers, cnx: production_api2

# the list of all computer serial numbers is read from the connection in
# the variable 'production_api2' and stored in 'prod2_computer_sns'

prod2_victim_md = Jamf::MobileDevice.fetch id: 832, cnx: production_api2

# the variable 'prod2_victim_md' now contains a Jamf::MobileDevice queried
# through the connection 'production_api2'.

Low-level use of Connection instances.

For most cases, using Connection instances as mentioned above is all you’ll need. However to access API resources that aren’t yet implemented in other parts of ruby-jss, you can use the methods {#c_get}, {#c_put}, {#c_post}, {#c_delete} for accessing the Classic API and {#jp_get}, {#jp_post}, {#jp_put}, {#jp_patch}, {#jp_delete} for accessing the Jamf Pro API

For even lower-level work, you can access the underlying Faraday::Connection objects via the connection’s {#c_cnx} and {#jp_cnx} attributes.

The connection class

The connection class

The connection class

The connection class

Public Class Methods

new(url = nil, **params) click to toggle source

Instantiate a connection object.

If name: is provided it will be stored as the Connection’s name attribute.

if no url is provided and params are empty, or contains only a :name key, then you must call connect with all the connection parameters before accessing a server.

See {#connect} for the parameters

    # File lib/jamf/api/connection.rb
175 def initialize(url = nil, **params)
176   @name = params.delete :name
177   @connected = false
178 
179   # initialize the data caches
180   # see cache.rb
181   @c_object_list_cache = {}
182   @c_ext_attr_definition_cache = {}
183   # @jp_singleton_cache = {}
184   # @jp_collection_cache = {}
185   # @jp_ext_attr_cache = {}
186 
187   return if url.nil? && params.empty?
188 
189   connect url, **params
190 end

Public Instance Methods

next_refresh() click to toggle source

@deprecated, use .token.next_refresh

    # File lib/jamf/api/connection.rb
219 def next_refresh
220   @token.next_refresh
221 end
pretty_print_instance_variables() click to toggle source

Only selected items are displayed with prettyprint otherwise its too much data in irb.

@return [Array] the desired instance_variables

    # File lib/jamf/api/connection.rb
214 def pretty_print_instance_variables
215   PP_VARS
216 end
secs_to_refresh() click to toggle source

@deprecated, use .token.secs_to_refresh

    # File lib/jamf/api/connection.rb
224 def secs_to_refresh
225   @token.secs_to_refresh
226 end
time_to_refresh() click to toggle source

@deprecated, use .token.time_to_refresh

    # File lib/jamf/api/connection.rb
229 def time_to_refresh
230   @token.time_to_refresh
231 end
to_s() click to toggle source

A useful string about this connection

@return [String]

    # File lib/jamf/api/connection.rb
199 def to_s
200   return 'not connected' unless connected?
201 
202   if name.to_s.start_with? "#{user}@"
203     name
204   else
205     "#{user}@#{host}:#{port}, name: #{name}"
206   end
207 end