ruby-jss 2.0.0b3 → 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES.md +13 -10
- data/README-2.0.0.md +141 -63
- data/README.md +225 -173
- data/lib/jamf/api/classic/api_objects/distribution_point.rb +12 -50
- data/lib/jamf/api/classic/api_objects/patch_title.rb +14 -9
- data/lib/jamf/api/classic/base_classes/api_object.rb +68 -9
- data/lib/jamf/api/classic/base_classes/patch_source.rb +10 -5
- data/lib/jamf/api/connection.rb +1 -1
- data/lib/jamf/api/jamf_pro/mixins/collection_resource.rb +8 -12
- data/lib/jamf/version.rb +1 -1
- data/lib/jamf/zeitwerk_config.rb +217 -0
- data/lib/jamf.rb +7 -39
- metadata +6 -6
- data/lib/zeitwerk_config.rb +0 -168
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 37c859eb265ff9298b8d49a8ded47c218d3355e270bf31cf3a276c7ac6db04b2
|
|
4
|
+
data.tar.gz: 83aac996b44f27830bcf24ee03f8ea70d4758b4e9418dfdbb8e4b2232c62c2f4
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c48ed5cafc7f2b24aba6a3eec0d83ecc8fd0a065372ef22b5d0db63c5ac8415d5033952f2a7d10d37eb29876c63bbd9775990cb9146fbd5d744dc0993955b5f2
|
|
7
|
+
data.tar.gz: 0cc3a608b9458e1abaf2aa04d32f34858ac892889ae384ee0ac0583c683a43d2d6be7b9dbd763d59738647dc7a1dad423cdfc22441b552df71674f7736597c05
|
data/CHANGES.md
CHANGED
|
@@ -4,28 +4,31 @@ All notable changes to this project will be documented in this file.
|
|
|
4
4
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
5
5
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## _IMPORTANT_: Known Security Issue in v1.5.3 and below
|
|
8
8
|
|
|
9
|
-
Versions of ruby-jss prior to 1.6.0 contain a known security issue due to
|
|
9
|
+
Versions of ruby-jss prior to 1.6.0 contain a known security issue due to how we were using the 'plist' gem.
|
|
10
10
|
|
|
11
11
|
This has been resolved in 1.6.0, which now uses the CFProperlyList gem.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
__Please update all installations of ruby-jss to at least v1.6.0.__
|
|
14
14
|
|
|
15
15
|
Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue and providing examples of how it could be exploited.
|
|
16
16
|
|
|
17
|
+
|
|
17
18
|
## \[2.0.0] - Unreleased
|
|
18
19
|
|
|
19
20
|
Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as much backward compatibility as possible, there are some significant changes and v2.0.0 is not fully backward compatible. **PLEASE TEST YOUR CODE EXTENSIVELY**
|
|
20
21
|
|
|
21
|
-
Here are the high-level changes and there are many many others. For more details, see [CHANGES-2.0.0](CHANGES-2.0.0.md)
|
|
22
|
+
Here are the high-level changes and there are many many others. For more details, see [CHANGES-2.0.0.md](CHANGES-2.0.0.md)
|
|
23
|
+
|
|
24
|
+
- Support for Ruby 3.x
|
|
25
|
+
- tested in 3.0 and 3.1
|
|
26
|
+
- Combined access to both the Classic and Jamf Pro APIs
|
|
27
|
+
- A single namespace module
|
|
28
|
+
- Connection objects talk to both APIs & automatically handle details like bearer tokens
|
|
29
|
+
- Auto-generated code for Jamf Pro API objects
|
|
30
|
+
- Autoloading of code using [Zeitwerk](https://github.com/fxn/zeitwerk)
|
|
22
31
|
|
|
23
|
-
- Combined access to both APIs.
|
|
24
|
-
- The Classic and Jamf Pro APIs are no longer separated into the JSS and Jamf modules. There is only the `Jamf` module, and `JSS` is merely an alias of it, so all your code refering to the JSS module should still work.
|
|
25
|
-
- Auto-generated classes for the Jamf Pro API
|
|
26
|
-
- Base classes for JamfPro API objects are automatically generated from the OAPI3 Schema available at https://your.jamf.server/api/schema. This make it much simpler for ruby-jss to implement and update new and changed objects and endpoints in the Jamf Pro API.
|
|
27
|
-
- Code is auto-loaded from disk
|
|
28
|
-
- Because the auto-generated classes add hundreds of files to the gem, ruby-jss now uses [Zeitwerk](https://github.com/fxn/zeitwerk) to auto-load only the files it needs when they are needed.
|
|
29
32
|
|
|
30
33
|
|
|
31
34
|
## \[1.6.7] - 2022-02-22
|
data/README-2.0.0.md
CHANGED
|
@@ -2,50 +2,53 @@
|
|
|
2
2
|
|
|
3
3
|
Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as much backward compatibility as possible, there are some significant changes under the hood. **_PLEASE TEST YOUR CODE EXTENSIVELY_**
|
|
4
4
|
|
|
5
|
-
This document discusses the high-level changes,
|
|
5
|
+
This document discusses the high-level changes, a few specific changes that have already happened, as well as planned changes and deprecations. It also provides some discussion and background around all of this.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
This is a work-in-progress at the moment, and will probably remain so well after initial release. Hopefully this document will prompt discussion and decision-making in the [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK) (Please join us!)
|
|
8
|
+
|
|
9
|
+
These changes have been in mind for some time, but the requirement in late 2022 for the Classic API to authenticate with Bearer Tokens from the Jamf Pro API means that the time has come, so here we are!
|
|
8
10
|
|
|
9
11
|
**CONTENTS**
|
|
10
12
|
|
|
11
13
|
<!-- TOC -->
|
|
12
14
|
|
|
13
|
-
- [
|
|
14
|
-
|
|
15
|
-
- [
|
|
16
|
-
|
|
17
|
-
- [
|
|
18
|
-
- [
|
|
19
|
-
- [
|
|
20
|
-
|
|
21
|
-
- [
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
- [
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
- [
|
|
41
|
-
|
|
42
|
-
|
|
15
|
+
- [Requirements](#requirements)
|
|
16
|
+
- [High level changes](#high-level-changes)
|
|
17
|
+
- [Ruby 3.x support](#ruby-3x-support)
|
|
18
|
+
- [Combined API access](#combined-api-access)
|
|
19
|
+
- [A single Connection class](#a-single-connection-class)
|
|
20
|
+
- [Connecting to the API](#connecting-to-the-api)
|
|
21
|
+
- [The default connection](#the-default-connection)
|
|
22
|
+
- [A single namespace Jamf](#a-single-namespace-jamf)
|
|
23
|
+
- [Inherant differences between the APIs](#inherant-differences-between-the-apis)
|
|
24
|
+
- [Which API does an object come from?](#which-api-does-an-object-come-from)
|
|
25
|
+
- [Automatic code generation](#automatic-code-generation)
|
|
26
|
+
- [Autoloading with Zeitwerk](#autoloading-with-zeitwerk)
|
|
27
|
+
- [Known Breaking Changes](#known-breaking-changes)
|
|
28
|
+
- [Notable changes from ruby-jss 1.x](#notable-changes-from-ruby-jss-1x)
|
|
29
|
+
- [Paged queries to the Jamf Pro API](#paged-queries-to-the-jamf-pro-api)
|
|
30
|
+
- [API data are no longer cached ?](#api-data-are-no-longer-cached-)
|
|
31
|
+
- [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects)
|
|
32
|
+
- [Class/Mixin hierarchy for Jamf Pro API objects](#classmixin-hierarchy-for-jamf-pro-api-objects)
|
|
33
|
+
- [Support for 'Sticky Sessions' in Jamf Cloud](#support-for-sticky-sessions-in-jamf-cloud)
|
|
34
|
+
- [The valid_id method for Classic API collection classes](#the-valid_id-method-for-classic-api-collection-classes)
|
|
35
|
+
- [Planned deprecations](#planned-deprecations)
|
|
36
|
+
- [Use of the term 'api'](#use-of-the-term-api)
|
|
37
|
+
- [.map_all_ids_to method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes)
|
|
38
|
+
- [Using .make, #create, and #update for Classic API objects](#using-make-create-and-update-for-classic-api-objects)
|
|
39
|
+
- [JSS::CONFIG](#jssconfig)
|
|
40
|
+
- [Jamf::Connection instance methods #next_refresh, #secs_to_refresh, & #time_to_refresh](#jamfconnection-instance-methods-next_refresh-secs_to_refresh---time_to_refresh)
|
|
41
|
+
- [Cross-object validation in setters](#cross-object-validation-in-setters)
|
|
42
|
+
- [fetch :random](#fetch-random)
|
|
43
|
+
- [Documentation](#documentation)
|
|
44
|
+
- [How to install for testing](#how-to-install-for-testing)
|
|
45
|
+
- [Contact](#contact)
|
|
43
46
|
|
|
44
47
|
<!-- /TOC -->
|
|
45
48
|
|
|
46
49
|
## Requirements
|
|
47
50
|
|
|
48
|
-
ruby-jss 2.0 requires ruby 2.6.3 or higher, and a Jamf Pro server running version 10.35 or higher.
|
|
51
|
+
ruby-jss 2.0,0 requires ruby 2.6.3 or higher, and a Jamf Pro server running version 10.35 or higher.
|
|
49
52
|
|
|
50
53
|
This means it will work with the OS-supplied /usr/bin/ruby in macOS 10.15 Catalina and above, until Apple removes ruby from the OS.
|
|
51
54
|
|
|
@@ -57,15 +60,15 @@ The plan is for ruby-jss 2.0+ to be compatible with ruby 2.6.3 and higher, inclu
|
|
|
57
60
|
|
|
58
61
|
As of this writing, basic access to the API seems to be working in ruby 3, but much much more testing is needed.
|
|
59
62
|
|
|
60
|
-
It looks like the biggest changes have been dealing with keyword arguments as Hashs. Methods defined with `def methodname([...] foo = {}` need to be changed to `def methodname([...] **foo` and calls to those methods, even in your own code, need to be changed to `methodname([...] **foo)` when `foo` is a hash of keyword args.
|
|
63
|
+
It looks like the biggest changes have been dealing with keyword arguments as Hashs. Methods defined with `def methodname([...] foo = {})` need to be changed to `def methodname([...] **foo)` and calls to those methods, even in your own code, need to be changed to `methodname([...] **foo)` when `foo` is a hash of keyword args.
|
|
61
64
|
|
|
62
|
-
**IMPORTANT**:
|
|
65
|
+
**IMPORTANT**: This may be a breaking change. Do not pass raw hashes as 'keyword' args. Instead use the double-splat: `methodname(**hash)` which should be compatible with ruby 3.x and 2.6.x
|
|
63
66
|
|
|
64
|
-
|
|
67
|
+
For more info see [Separation of positional and keyword arguments in Ruby 3.0](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
|
|
65
68
|
|
|
66
69
|
### Combined API access
|
|
67
70
|
|
|
68
|
-
ruby-jss
|
|
71
|
+
Previous versions of ruby-jss used the `JSS` module to encapsulate all access to the Classic API. When the Jamf Pro API became a thing, it was a vary different beast, so the `Jamf` module was created as the way to interact with that API as it grew and developed.
|
|
69
72
|
|
|
70
73
|
Even though the latest Jamf Pro release notes say the Jamf Pro API is still officially "open for user testing", it has stablized enough that it is used by many folks for production work.
|
|
71
74
|
|
|
@@ -77,23 +80,24 @@ There is now one `Jamf::Connection` class, instances of which are connections to
|
|
|
77
80
|
|
|
78
81
|
##### Connecting to the API
|
|
79
82
|
|
|
80
|
-
Most of the previous methods and parameters for making
|
|
83
|
+
Most of the previous methods and parameters for making connections to either API should still work, including using a URL rather than individual connection parameters. So both of these are valid and identical:
|
|
81
84
|
|
|
82
85
|
```ruby
|
|
83
86
|
a_connection = Jamf::Connection.new 'https://apiuser@my.jamf.server:8443/', pw: :prompt
|
|
84
87
|
|
|
85
88
|
another_connection = Jamf::Connection.new host: 'my.jamf.server', port: 8443, user: 'apiuser', pw: :prompt
|
|
86
89
|
```
|
|
87
|
-
|
|
88
90
|
Other connection parameters can be passed in as normal.
|
|
89
91
|
|
|
90
92
|
###### The default connection
|
|
91
93
|
|
|
92
|
-
The top-level module methods for accessing the 'default' connection are still available and are now synonyms: `Jamf.cnx` and `JSS.api` both return the current default Jamf::Connection instance. There is also a top-level methods`Jamf.connect` which is the same as `Jamf.cnx.connect`. The top-level methods for changing the default connection are still there.
|
|
94
|
+
The top-level module methods for accessing the 'default' connection are still available and are now synonyms: `Jamf.cnx` and `JSS.api` both return the current default Jamf::Connection instance. There is also a top-level methods`Jamf.connect` which is the same as `Jamf.cnx.connect`. The top-level methods for changing the default connection are still there.
|
|
95
|
+
|
|
96
|
+
NOTE: The use of `JSS::API` has been deprecated for years now, and still is (see below).
|
|
93
97
|
|
|
94
98
|
#### A single namespace `Jamf`
|
|
95
99
|
|
|
96
|
-
Version 2.0.0 combines the `JSS` module and the `Jamf` module into a single `Jamf` module, with `JSS` aliased to it. This means you can use
|
|
100
|
+
Version 2.0.0 combines the `JSS` module and the `Jamf` module into a single `Jamf` module, with `JSS` aliased to it. This means you can use the names interchangably to refer to the Jamf module, and existing code that used either should still work. The module name no longer indicates which API you're working with.
|
|
97
101
|
|
|
98
102
|
For example, the `JSS::Computer` class, from the Classic API, is still a thing, but now just points to the `Jamf::Computer` class, still from the Classic API. The `Jamf::InventoryPreloadRecord` class, from the Jamf Pro API remains as is, but can also be referred to as `JSS::InventoryPreloadRecord`
|
|
99
103
|
|
|
@@ -103,9 +107,9 @@ In theory, you shouldn't need to worry about which classes and objects come from
|
|
|
103
107
|
|
|
104
108
|
However, in reality the two APIs have different functionality, some of which must be reflected in the ruby classes that represent objects in those APIs.
|
|
105
109
|
|
|
106
|
-
Take, for example, the classes for 'Collection Resources' - API endpoints that let you deal with collections of objects like Computers, or Inventory Preload Records. These classes implement a `.all` class method, which retrieves
|
|
110
|
+
Take, for example, the classes for 'Collection Resources' - API endpoints that let you deal with collections of objects like Computers, or Inventory Preload Records. These classes implement a `.all` class method, which retrieves an Array of some data about all members of the collection.
|
|
107
111
|
|
|
108
|
-
Not only is the data returned in such
|
|
112
|
+
Not only is the data returned in such Arrays very different between the APIs, but in the Jamf Pro API, you can ask the server to return the list already sorted, possibly filtered, or 'paged' in groups of some number of items. None of that is possible in the Classic API.
|
|
109
113
|
|
|
110
114
|
The `.all` method, and its relatives like `.all_ids`, `.all_names`, etc. exist for Collection Resources in both APIs, but the methods take different parameters, e.g. to deal with sorting and filtering. Jamf Pro API classes have a `.pager` method which returns an object from which you can retrieve the 'pages' of your query.
|
|
111
115
|
|
|
@@ -121,9 +125,11 @@ The API documentation you see at your own Jamf Pro server at https://your.jamf.s
|
|
|
121
125
|
|
|
122
126
|
In ruby-jss 2.0 and up, the OAPI spec is used to automatically generate hundreds of 'base' classes in ruby-jss, each with automatically generated attribute getters, setters, validators, and other useful methods. These base classes can then be used as the superclasses of the Jamt Pro API objects we implement for direct use in ruby-jss - and the majority of the coding is already done! The subclasses implementing objects in ruby-jss can then be expanded and customized beyond the simple, auto-generated superclass.
|
|
123
127
|
|
|
124
|
-
Not only does this make it fast and simple to implement new objects in ruby-jss, but allows fast and simple updates to existing objects, when new functionality is introduced to the API.
|
|
128
|
+
Not only does this make it fast and simple to implement new objects in ruby-jss, but allows fast and simple updates to existing objects, when new functionality is introduced to the API.
|
|
125
129
|
|
|
126
|
-
|
|
130
|
+
Hopefully it will also allow a single version of ruby-jss to work with a wide range of Jamf Pro versions, as API endpoint versions are added and deprecated (details of how that'll work are TBD)
|
|
131
|
+
|
|
132
|
+
If you develop ruby-jss, please see (documentation link will go here) for more info about how to use the auto-generated classes, or reach out to us. (See [Contact](#contact), below)
|
|
127
133
|
|
|
128
134
|
### Autoloading with Zeitwerk
|
|
129
135
|
|
|
@@ -138,6 +144,22 @@ Then as files load, lines will be written to standard error indicating:
|
|
|
138
144
|
- A module was mixed-in to some other module or class
|
|
139
145
|
- A method was just automatically defined
|
|
140
146
|
|
|
147
|
+
## Known Breaking Changes
|
|
148
|
+
|
|
149
|
+
So far we've only uncovered a few areas where our ruby-jss 1.x code didn't work with ruby-jss 2.0.0
|
|
150
|
+
|
|
151
|
+
- Using unsplatted Hashes as 'named parameters' to method calls.
|
|
152
|
+
- See [Ruby 3.x support](#ruby-3x-support) above
|
|
153
|
+
|
|
154
|
+
- Jamf Pro API objects no longer have aliases for their attributes
|
|
155
|
+
- See [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects) below
|
|
156
|
+
|
|
157
|
+
- Subclassing ruby-jss classes in your own code.
|
|
158
|
+
- Those classes, and methods called on them, may need to be updated to match the new ruby-jss classes, in order to maintain _their_ backward compatibility.
|
|
159
|
+
|
|
160
|
+
- If you make calls to Classic API's `.valid_id` class method for collection classes, and you pass in an integer as a String, e.g. '1234', expecting to get the valid id of the object with the _name_ or _serial_number_ '1234' you will now get back the id 1234 if there is an object with that id. That may not be the id of the object you were looking for.
|
|
161
|
+
- See [The valid_id method for Classic API collection classes](#the-valid_id-method-for-classic-api-collection-classes) below for details and how to do such a validation now.
|
|
162
|
+
|
|
141
163
|
## Notable changes from ruby-jss 1.x
|
|
142
164
|
|
|
143
165
|
### Paged queries to the Jamf Pro API
|
|
@@ -150,26 +172,32 @@ The `.all` method will never deliver paged results, however if you give it a `fi
|
|
|
150
172
|
|
|
151
173
|
### API data are no longer cached (?)
|
|
152
174
|
|
|
153
|
-
**NOTE:** As of this writing, caching has been removed for the objects from the Jamf Pro API, but caching remains in the Classic API. Its removal, or the re-instatement of caching for JP API objects, are pending discussion with users of ruby-jss.
|
|
175
|
+
**NOTE:** As of this writing, caching has been removed for the objects from the Jamf Pro API, but caching remains in the Classic API. Its removal, or the re-instatement of caching for JP API objects, are pending discussion with other users of ruby-jss.
|
|
154
176
|
|
|
155
177
|
Pre-2.0, methods that would fetch large datasets from the server would always cache that data in the Connection object, and by default use the cache in future calls unless a `refresh` parameter is given. These datasets included:
|
|
156
178
|
|
|
157
179
|
- collection lists, used by `.all` and friends, like `.all_ids` and `.valid_id`
|
|
158
|
-
- Extension Attribute
|
|
180
|
+
- Extension Attribute definitions, used for validating Extension Attribute values
|
|
159
181
|
|
|
160
182
|
In 2.0+, that caching has been removed for objects from them Jamf Pro API.
|
|
161
183
|
|
|
162
|
-
|
|
184
|
+
If you want to avoid repeated GET requests to the server when you aren't worried that the resulting data may have changed, you can store the results of `.all` in a variable, and either use it yourself, or pass it in to other methods via the `cached_list:` parameter. Passing in a cached_list wil prevent those methods from calling `.all` and reaching out to the server again.
|
|
163
185
|
|
|
164
|
-
**WARNING**:
|
|
186
|
+
**WARNING**: Caching a list yourself and using it with `cached_list` can cause all kinds of problems if you don't ensure these points:
|
|
187
|
+
- the cached_list contains the correct data structure for the class
|
|
188
|
+
- i.e. pass in the results of `.all` for that class, not `.all_ids` or other sub-lists.
|
|
189
|
+
- the cached_list came from the correct Connection instance
|
|
190
|
+
- the cached_list is sufficiently up to date.
|
|
165
191
|
|
|
166
192
|
### No Attribute aliases for Jamf Pro API objects
|
|
167
193
|
|
|
168
194
|
Objects from the Jamf Pro API will no longer define aliases for the attribute names that come from the API itself. This means, e.g., to get the name of a ComputerPrestage or MobileDevicePrestage, you have to ask for its `displayName` not its `name`, since the property comes from the API as `displayName`. To see a list of all the names, you must use `.all_displayNames` not `.all_names`. For objects with a 'name' property (most of them) then you can use `.name` and `.all_names`.
|
|
169
195
|
|
|
170
|
-
The reason behind this is twofold:
|
|
196
|
+
The reason behind this is twofold:
|
|
197
|
+
1) to simplify ruby-jss's code and automate as much as possible
|
|
198
|
+
2) to reflect what Jamf actually gives us in the APIs
|
|
171
199
|
|
|
172
|
-
This is a breaking change from earlier ruby-jss versions, for which Jamf Pro API objects had the potential for aliases of their attribute names.
|
|
200
|
+
**IMPORTANT** This is a breaking change from earlier ruby-jss versions, for which Jamf Pro API objects had the potential for aliases of their attribute names.
|
|
173
201
|
|
|
174
202
|
### Class/Mixin hierarchy for Jamf Pro API objects
|
|
175
203
|
|
|
@@ -177,11 +205,11 @@ If you contribute to ruby-jss, be aware that the structure of superclasses, subc
|
|
|
177
205
|
|
|
178
206
|
There's a lot to document about these changes, and much of the current documentation is out of date, referring to how things were done when the Jamf module was separate and only talked to the Jamf Pro API.
|
|
179
207
|
|
|
180
|
-
Give us time and we'll get everything updated. In the meantime, feel free to reach out
|
|
208
|
+
Give us time and we'll get everything updated. In the meantime, feel free to reach out for assistance or questions. (See [Contact](#contact), below)
|
|
181
209
|
|
|
182
210
|
### Support for 'Sticky Sessions' in Jamf Cloud
|
|
183
211
|
|
|
184
|
-
If you are connecting to a Jamf Cloud server, you can specifcy `
|
|
212
|
+
If you are connecting to a Jamf Cloud server, you can specifcy `sticky_session: true` when calling `Jamf::Connection.new` or `Jamf::Connection#connect`. If you already have a connected Connection object, you can enable or disable Sticky Sessions using `my_connection_object.sticky_session =` with a boolean value (for the default connection use `Jamf.cnx.sticky_session = <boolean>`). To see the actual cookie being sent to enable sticky sessions, use `Jamf::Connection#sticky_session_cookie`.
|
|
185
213
|
|
|
186
214
|
Attempting to enable a sticky session with a connection to an on-prem server (host not ending in 'jamfcloud.com') will raise an error.
|
|
187
215
|
|
|
@@ -189,12 +217,64 @@ For details about Sticky Sessions see [Sticky Sessions for Jamf Cloud](https://d
|
|
|
189
217
|
|
|
190
218
|
**WARNING:** Jamf recommends NOT using sticky sessions unless they are needed. Using them inappropriately may negatively impact performance, especially for large automated processes.
|
|
191
219
|
|
|
220
|
+
### The `valid_id` method for Classic API collection classes
|
|
221
|
+
|
|
222
|
+
In the Classic API, object ids are Integers, but in the Jamf Pro API, they are Strings containing integers.
|
|
223
|
+
|
|
224
|
+
In previous versions of ruby-jss, the `valid_id` class method for the Jamf Pro API will accept Integers and convert them to Strings to search for the valid id. In order to provide the same flexibility, `valid_id` now works the same way for regardless of which API is used.
|
|
225
|
+
|
|
226
|
+
Previously, the Classic API collection classes would return nil (no match) if you passed in an id as a string, unless you had an object with a name or other identifier with that numeric string value.
|
|
227
|
+
|
|
228
|
+
So for example, assuming you wanted to find out if the id 1234 was valid, you could do
|
|
229
|
+
|
|
230
|
+
```ruby
|
|
231
|
+
ok_id = JSS::Computer.valid_id 1234
|
|
232
|
+
# => 1234, or nil if 1234 is not a valid id
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
But if you did
|
|
236
|
+
|
|
237
|
+
```ruby
|
|
238
|
+
ok_id = JSS::Computer.valid_id '1234'
|
|
239
|
+
# => nil, or the id of a computer _named_ '1234'
|
|
240
|
+
# (no computer would have '1234' as a serialnumber, udid, or macaddress)
|
|
241
|
+
```
|
|
242
|
+
you would likely not get the integer id 1234 back.
|
|
243
|
+
|
|
244
|
+
In ruby-jss 2.0.0, the valid_id method has changed so that the second example above will return the integer id 1234, if it exists as an id. If not, it will look at other identifiers with the string value, and return the id of any match, or nil if there's no match.
|
|
245
|
+
|
|
246
|
+
The downside of this is: what if you really _are_ looking for the id of the object with the name '1234'?
|
|
247
|
+
|
|
248
|
+
To deal with that situation, the valid_id method for the Classic API now behaves like the one for the Jamf Pro API: it can accept an arbitrary key: value pair, limiting the search to the indentifier used as the key.
|
|
249
|
+
|
|
250
|
+
So you can use this to get what you're looking for
|
|
251
|
+
|
|
252
|
+
```ruby
|
|
253
|
+
ok_id = JSS::Computer.valid_id name: '1234'
|
|
254
|
+
# => nil, or the id of a computer named '1234'
|
|
255
|
+
```
|
|
192
256
|
|
|
193
257
|
## Planned deprecations
|
|
194
258
|
|
|
195
|
-
|
|
259
|
+
Even though it was publically released in 2014, ruby-jss's origins are from 2009, so it's been around for a while. We've learned a lot since then, and lots of the old lingering code is terribly out of date.
|
|
260
|
+
|
|
261
|
+
The move to 2.0.0 is our opportunity to start streamlining things and cleaning up not just the code, but how it's used.
|
|
196
262
|
|
|
197
|
-
|
|
263
|
+
We wanted to make the initial transition to 2.0.0 as backward-compatible as possible, but going forward, a lot of things will be changing or going away.
|
|
264
|
+
|
|
265
|
+
All of this is up for discussion! If you have suggestions or ideas for improvement, cleanup, or modernization, or if one of these deprecated items is important to you, [please reach out](#contact) and let us hear your thoughts.
|
|
266
|
+
|
|
267
|
+
As a side effect of these planned changes, and due to our attempts to adhere to [Semantic Versioning](https://semver.org), you can expect the major version number to start going up faster than it used to.
|
|
268
|
+
|
|
269
|
+
Here are the things we are planning on removing or changing in the coming months-to-years:
|
|
270
|
+
|
|
271
|
+
### Use of the term 'api'
|
|
272
|
+
|
|
273
|
+
In ruby-jss < 2.0, the term `api` is used with the Classic API in method names, method parameters, instance variables, attributes, and constants. It is used to pass, access, refer to, or hold instances of JSS::APIConnnection, e.g. so a method that talks to the server would use the passed connection rather than the module-wide default connection.
|
|
274
|
+
|
|
275
|
+
The term 'api' is inappropriate because the thing being passed is a 'connection' not an 'api'. Now that there are actually two APIs at play, that usage is even less appropriate.
|
|
276
|
+
|
|
277
|
+
Going forward, use `cnx` (simpler to type than 'connection') instead. Example:
|
|
198
278
|
|
|
199
279
|
```ruby
|
|
200
280
|
my_connection = Jamf::Connection.new 'https://user@my.jamf.server:8443/', pw: :prompt
|
|
@@ -214,11 +294,11 @@ comp = JSS::Computer.fetch id: 12, cnx: my_connection
|
|
|
214
294
|
comp.cnx # => my_connection
|
|
215
295
|
```
|
|
216
296
|
|
|
217
|
-
|
|
297
|
+
The original Jamf module, which accessed only the Jamf Pro API, has always used the better-suited abbreviation `cnx` for this, and now that is standard everywhere.
|
|
218
298
|
|
|
219
|
-
|
|
299
|
+
For now `api` should continue to work, but it will be removed 'eventually', so please start changing your code now.
|
|
220
300
|
|
|
221
|
-
Accordingly, `JSS::API` (which should never have been a constant to begin with) is also deprecated. To access the default connection, use `Jamf.cnx`
|
|
301
|
+
Accordingly, `JSS::API` (which should never have been a constant to begin with) has been deprecated for years in favor of `JSS.api`, which is now also deprecated. To access the default connection, use `Jamf.cnx`
|
|
222
302
|
|
|
223
303
|
### `.map_all_ids_to` method for Classic API collection classes
|
|
224
304
|
|
|
@@ -230,7 +310,7 @@ For now `map_all_ids_to` still works, however it's just a wrapper for `map_all`.
|
|
|
230
310
|
|
|
231
311
|
Use `.create` and `#save` instead, as with the Jamf Pro API objects
|
|
232
312
|
|
|
233
|
-
|
|
313
|
+
All versions of ruby-jss have avoided the use of the ruby-standard `.new` on Collection Resource classes, because the word 'new' in this context is ambiguous: are you creating a new instance of the class in ruby (which might already exist on the server), or are you creating a new object in Jamf Pro that doesn't yet exist on the server?
|
|
234
314
|
|
|
235
315
|
In v2.0.0 we are standardizing on the behavior of the previous Jamf module:
|
|
236
316
|
|
|
@@ -239,8 +319,6 @@ In v2.0.0 we are standardizing on the behavior of the previous Jamf module:
|
|
|
239
319
|
- `Jamf::SomeCollectionClass#save` instance method for sending an object to the server to be created OR updated in Jamf pro.
|
|
240
320
|
- Note that `#save` has been available for this use since the earliest versions of ruby-jss.
|
|
241
321
|
|
|
242
|
-
|
|
243
|
-
|
|
244
322
|
This means that these deprecated methods will go away for Classic API objects
|
|
245
323
|
|
|
246
324
|
- `Jamf::SomeCollectionClass.make` class method for instantiating a ruby object to be added as a new SomeCollectionClass to Jamf Pro
|
|
@@ -286,7 +364,7 @@ existing_policy.save
|
|
|
286
364
|
|
|
287
365
|
### JSS::CONFIG
|
|
288
366
|
|
|
289
|
-
This
|
|
367
|
+
This should never have been a constant. Use Jamf.config. JSS::CONFIG will go away eventually.
|
|
290
368
|
|
|
291
369
|
### Jamf::Connection instance methods `#next_refresh`, `#secs_to_refresh`, & `#time_to_refresh`
|
|
292
370
|
|
|
@@ -320,7 +398,7 @@ You can still fetch random objects from a collection, but use `.fetch random: tr
|
|
|
320
398
|
|
|
321
399
|
The YARD documentation for v2.0.0 is available before release in the [github.io site for ruby-jss](http://pixaranimationstudios.github.io/ruby-jss/docs/v2.x/index.html).
|
|
322
400
|
|
|
323
|
-
All the documentation for ruby-jss is in need of updating, from the top-level README to the auto-generated YARD docs.
|
|
401
|
+
All the documentation for ruby-jss is in serious need of updating, from the top-level README to the auto-generated YARD docs. Forgive us while we slowly get it up to snuff. If you have questions that aren't answered there, please reach out (see [Contact](#contact), below)
|
|
324
402
|
|
|
325
403
|
## How to install for testing
|
|
326
404
|
|