Module: JSS::SelfServable
- Includes:
- Uploadable
- Included in:
- ConfigurationProfile, MobileDeviceApplication, PatchPolicy, Policy
- Defined in:
- lib/jss/api_object/self_servable.rb,
lib/jss.rb
Overview
A mix-in module for handling Self Service data for objects in the JSS.
The JSS objects that have Self Service data return it in a :self_service subset, which have somewhat similar data, i.e. a hash with at least these keys:
-
:self_service_description
-
:self_service_icon
-
:feature_on_main_page
-
:self_service_categories
Config Profiles in self service have this key:
-
:security
Additionally, items that apper in macOS Slf Svc have these keys:
-
:self_service_display_name
-
:install_button_text
-
:reinstall_button_text
-
:force_users_to_view_description
-
:notification
-
:notification_location # PENDING API FIX
-
:notification_subject
-
:notification_message
See the attribute definitions for details of these values and structures.
Including this module in an APIObject subclass will give it matching attributes with ‘self_service_’ appended if needed, e.g. #self_service_feature_on_main_page
Classes including this module MUST:
-
call #add_self_service_xml(xmldoc) in their #rest_xml method
IMPORTANT: Since SelfServable also includes #Uploadable, for uploading icons, see that module for its requirements.
Constant Summary collapse
- SELF_SERVABLE =
Constants
true
- PROFILE_REMOVAL_BY_USER =
{ always: 'Always', never: 'Never', with_auth: 'With Authorization' }.freeze
- MAKE_AVAILABLE =
'Make Available in Self Service'.freeze
- AUTO_INSTALL =
'Install Automatically'.freeze
- AUTO_INSTALL_OR_PROMPT =
'Install Automatically/Prompt Users to Install'.freeze
- PATCHPOL_SELF_SERVICE =
‘Make Available in Self Service’ in the UI
'selfservice'.freeze
- PATCHPOL_AUTO =
‘Install Automatically’ in the UI
'prompt'.freeze
- DEFAULT_INSTALL_BUTTON_TEXT =
'Install'.freeze
- DEFAULT_REINSTALL_BUTTON_TEXT =
'Reinstall'.freeze
- DEFAULT_FORCE_TO_VIEW_DESC =
false
- NOTIFICATION_TYPES =
{ ssvc_only: 'Self Service', ssvc_and_nctr: 'Self Service and Notification Center' }.freeze
- DFT_NOTIFICATION_TYPE =
:ssvc_only
- USER_URL_BASE =
'jamfselfservice://content?entity='.freeze
- USER_URL_EXEC_ACTION =
'execute'.freeze
- USER_URL_VIEW_ACTION =
'view'.freeze
- SELF_SERVICE_CLASSES =
This hash contains the details about the inconsistencies of how Self Service data is dealt with in the API data of the different self-servable classes.
- in_self_service_data_path: Array, In the API data hash (the @init_data) where to find the value indicicating that a thing is in self service. e.g. [:self_service, :use_for_self_service] means @init_data[:self_service][:use_for_self_service] - in_self_service: Object, In the path defined above, what value means the thing IS in self service - not_in_self_service: Object, In the path defined above, what value means the thing IS NOT in self service - self_service_subset: Symbol. Which key of the init data hash contains the self service data. If not defined, its :self_service, but PatchPolcies use :user_interaction - targets: Array<Symbol>, the array contains either :macos, :ios, or both. - payload: Symbol, The thing that is deployed by self service, one of: :policy, :app, :profile, :patchpolicy (ebooks are considered apps) - can_display_in_categories: Boolean, when adding 'self service categories' can the thing be 'displayed in' those categories? - can_feature_in_categories: Boolean, when adding 'self service categories' can the thing be 'featured in' those categories? - notifications_supported: either nil (not supported), :ssvc_only, or :ssvc_and_nctr NOTE: when notifications are supported for :ssvc_only, its due to a bug in the handling of the XML (two separate values are using the same XML element tag <notification>) Items that support both have a <notifications> subset inside the <self_service> subset - notification_reminders: if true, supports notification reminders. Only true for items that have a <notifications> subset - url_entity: the 'entity' value used in user-urls for this SSVc item.
It’s unfortunate that this is needed in order to keep all the self service ruby code in this one module.
{ JSS::Policy => { in_self_service_data_path: %i[self_service use_for_self_service], in_self_service: true, not_in_self_service: false, targets: [:macos], payload: :policy, can_display_in_categories: true, can_feature_in_categories: true, notifications_supported: :ssvc_only, url_entity: 'policy' }, JSS::PatchPolicy => { in_self_service_data_path: %i[general distribution_method], in_self_service: PATCHPOL_SELF_SERVICE, not_in_self_service: PATCHPOL_AUTO, self_service_subset: :user_interaction, targets: [:macos], payload: :patchpolicy, can_display_in_categories: false, can_feature_in_categories: false, notifications_supported: :ssvc_and_nctr, notification_reminders: true }, JSS::MacApplication => { # in_self_service_data_path was finally implemnted in JamfPro 10.9 # Jamf Product Issue [PI-003773] in_self_service_data_path: [:general, :deployment_type], in_self_service: MAKE_AVAILABLE, not_in_self_service: AUTO_INSTALL_OR_PROMPT, targets: [:macos], payload: :app, can_display_in_categories: true, can_feature_in_categories: true, url_entity: 'app' # OTHER BUG: no notification options seem to be changable via the API }, JSS::OSXConfigurationProfile => { in_self_service_data_path: %i[general distribution_method], in_self_service: MAKE_AVAILABLE, not_in_self_service: AUTO_INSTALL, targets: [:macos], payload: :profile, can_display_in_categories: true, can_feature_in_categories: true, notifications_supported: :ssvc_only, url_entity: 'configprofile' }, JSS::EBook => { in_self_service_data_path: %i[general deployment_type], in_self_service: MAKE_AVAILABLE, not_in_self_service: AUTO_INSTALL_OR_PROMPT, targets: %i[macos ios], payload: :app, # ebooks are handled the same way as apps, it seems, can_display_in_categories: true, can_feature_in_categories: true, notifications_supported: :ssvc_only, url_entity: 'ebook' }, JSS::MobileDeviceApplication => { in_self_service_data_path: %i[general deployment_type], in_self_service: MAKE_AVAILABLE, not_in_self_service: AUTO_INSTALL_OR_PROMPT, targets: [:ios], payload: :app, can_display_in_categories: true, can_feature_in_categories: false }, JSS::MobileDeviceConfigurationProfile => { in_self_service_data_path: %i[general deployment_method], in_self_service: MAKE_AVAILABLE, not_in_self_service: AUTO_INSTALL, targets: [:ios], payload: :profile, can_display_in_categories: false, can_feature_in_categories: false } }.freeze
Instance Attribute Summary collapse
-
#icon ⇒ JSS::Icon?
(also: #self_service_icon)
The icon used in self-service.
-
#in_self_service ⇒ Boolean
(also: #in_self_service?)
readonly
Is this thing available in Self Service?.
-
#self_service_categories ⇒ Array<Hash>
readonly
Each Hash has these keys about the category - :id => [Integer] the JSS id of the category - :name => [String] the name of the category.
-
#self_service_description ⇒ String
The verbage that appears in SelfSvc for this item.
-
#self_service_display_name ⇒ String
(also: #self_service_dislay_name)
The name to display in macOS Self Service.
-
#self_service_feature_on_main_page ⇒ Boolean
Only applicable to macOS targets.
-
#self_service_force_users_to_view_description ⇒ Boolean
Should an extra window appear before the user can install the item? (OSX SSvc only).
-
#self_service_install_button_text ⇒ String
defaults to ‘Install’.
-
#self_service_notification_message ⇒ String
The message text of the notification.
-
#self_service_notification_subject ⇒ String
object name.
-
#self_service_notification_type ⇒ Symbol
How should notifications be sent either :ssvc_only or :ssvc_and_nctr.
-
#self_service_notifications_enabled ⇒ Boolean
(also: #self_service_notifications_enabled?)
Should jamf send notifications to self service?.
-
#self_service_reinstall_button_text ⇒ String
defaults to ‘Reinstall’.
-
#self_service_reminder_frequency ⇒ Integer
How often (in days) should reminders be given.
-
#self_service_reminders_enabled ⇒ Boolean
(also: #self_service_reminders_enabled?)
Should self service give reminders by displaying the notification repeatedly?.
-
#self_service_removal_password ⇒ String
readonly
The password needed for removal, in plain text.
-
#self_service_user_removable ⇒ Symbol
One of the keys in PROFILE_REMOVAL_BY_USER.
Instance Method Summary collapse
-
#add_self_service_category(new_cat, display_in: true, feature_in: false) ⇒ void
(also: #set_self_service_category, #change_self_service_category)
Add or change one of the categories for this item in self service.
-
#add_to_self_service ⇒ void
Add this object to self service if not already there.
-
#create ⇒ Object
HACK: ity hack hack…
-
#remove_from_self_service ⇒ void
Remove this object from self service if it’s there.
-
#remove_self_service_category(cat) ⇒ void
Remove a category from those for this item in SSvc.
-
#self_service_execute_url ⇒ String
The url to view this thing in Self Service.
-
#self_service_payload ⇒ Symbol
What does this object deploy to the device via self service?.
-
#self_service_targets ⇒ Array<Symbol>
What devices types can get this thing in Self Service.
-
#self_service_view_url ⇒ String
The url to view this thing in Self Service.
-
#update ⇒ Object
HACK: ity hack hack…
-
#upload(type, local_file) ⇒ String
included
from Uploadable
Upload a file to the JSS via the REST Resource of the object to which this module is mixed in.
-
#user_removable? ⇒ Boolean?
Can this thing be removed by the user?.
Instance Attribute Details
#icon ⇒ JSS::Icon? Also known as: self_service_icon
Returns The icon used in self-service.
246 247 248 |
# File 'lib/jss/api_object/self_servable.rb', line 246 def icon @icon end |
#in_self_service ⇒ Boolean (readonly) Also known as: in_self_service?
Returns Is this thing available in Self Service?.
242 243 244 |
# File 'lib/jss/api_object/self_servable.rb', line 242 def in_self_service @in_self_service end |
#self_service_categories ⇒ Array<Hash> (readonly)
Each Hash has these keys about the category
-
:id => [Integer] the JSS id of the category
-
:name => [String] the name of the category
Most objects also include one or both of these keys:
-
:display_in => [Boolean] should the item be displayed in this category in SSvc? (not MobDevConfProfiles)
-
:feature_in => [Boolean] should the item be featured in this category in SSVC? (macOS targets only)
269 270 271 |
# File 'lib/jss/api_object/self_servable.rb', line 269 def self_service_categories @self_service_categories end |
#self_service_description ⇒ String
Returns The verbage that appears in SelfSvc for this item.
253 254 255 |
# File 'lib/jss/api_object/self_servable.rb', line 253 def self_service_description @self_service_description end |
#self_service_display_name ⇒ String Also known as: self_service_dislay_name
Returns The name to display in macOS Self Service.
250 251 252 |
# File 'lib/jss/api_object/self_servable.rb', line 250 def self_service_display_name @self_service_display_name end |
#self_service_feature_on_main_page ⇒ Boolean
Only applicable to macOS targets
257 258 259 |
# File 'lib/jss/api_object/self_servable.rb', line 257 def self_service_feature_on_main_page @self_service_feature_on_main_page end |
#self_service_force_users_to_view_description ⇒ Boolean
Returns Should an extra window appear before the user can install the item? (OSX SSvc only).
300 301 302 |
# File 'lib/jss/api_object/self_servable.rb', line 300 def self_service_force_users_to_view_description @self_service_force_users_to_view_description end |
#self_service_install_button_text ⇒ String
defaults to ‘Install’
293 294 295 |
# File 'lib/jss/api_object/self_servable.rb', line 293 def @self_service_install_button_text end |
#self_service_notification_message ⇒ String
Returns The message text of the notification.
315 316 317 |
# File 'lib/jss/api_object/self_servable.rb', line 315 def @self_service_notification_message end |
#self_service_notification_subject ⇒ String
object name.
312 313 314 |
# File 'lib/jss/api_object/self_servable.rb', line 312 def self_service_notification_subject @self_service_notification_subject end |
#self_service_notification_type ⇒ Symbol
Returns How should notifications be sent either :ssvc_only or :ssvc_and_nctr.
308 309 310 |
# File 'lib/jss/api_object/self_servable.rb', line 308 def self_service_notification_type @self_service_notification_type end |
#self_service_notifications_enabled ⇒ Boolean Also known as: self_service_notifications_enabled?
Returns Should jamf send notifications to self service?.
303 304 305 |
# File 'lib/jss/api_object/self_servable.rb', line 303 def self_service_notifications_enabled @self_service_notifications_enabled end |
#self_service_reinstall_button_text ⇒ String
defaults to ‘Reinstall’
297 298 299 |
# File 'lib/jss/api_object/self_servable.rb', line 297 def @self_service_reinstall_button_text end |
#self_service_reminder_frequency ⇒ Integer
Returns How often (in days) should reminders be given.
323 324 325 |
# File 'lib/jss/api_object/self_servable.rb', line 323 def self_service_reminder_frequency @self_service_reminder_frequency end |
#self_service_reminders_enabled ⇒ Boolean Also known as: self_service_reminders_enabled?
Returns Should self service give reminders by displaying the notification repeatedly?.
319 320 321 |
# File 'lib/jss/api_object/self_servable.rb', line 319 def self_service_reminders_enabled @self_service_reminders_enabled end |
#self_service_removal_password ⇒ String (readonly)
Returns The password needed for removal, in plain text.
289 290 291 |
# File 'lib/jss/api_object/self_servable.rb', line 289 def self_service_removal_password @self_service_removal_password end |
#self_service_user_removable ⇒ Symbol
Returns one of the keys in PROFILE_REMOVAL_BY_USER.
286 287 288 |
# File 'lib/jss/api_object/self_servable.rb', line 286 def self_service_user_removable @self_service_user_removable end |
Instance Method Details
#add_self_service_category(new_cat, display_in: true, feature_in: false) ⇒ void Also known as: set_self_service_category, change_self_service_category
This method returns an undefined value.
Add or change one of the categories for this item in self service
433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 |
# File 'lib/jss/api_object/self_servable.rb', line 433 def add_self_service_category(new_cat, display_in: true, feature_in: false) new_cat = JSS::Category.map_all_ids_to(:name, api: @api)[new_cat] if new_cat.is_a? Integer feature_in = false if display_in == false raise JSS::NoSuchItemError, "No category '#{new_cat}' in the JSS" unless JSS::Category.all_names(:refresh, api: @api).include? new_cat raise JSS::InvalidDataError, 'display_in must be true or false' unless display_in.jss_boolean? raise JSS::InvalidDataError, 'feature_in must be true or false' unless feature_in.jss_boolean? new_data = { name: new_cat } new_data[:display_in] = display_in if @self_service_data_config[:can_display_in_categories] new_data[:feature_in] = feature_in if @self_service_data_config[:can_feature_in_categories] # see if this category is already among our categories. idx = @self_service_categories.index { |c| c[:name] == new_cat } if idx @self_service_categories[idx] = new_data else @self_service_categories << new_data end @need_to_update = true end |
#add_to_self_service ⇒ void
This method returns an undefined value.
Add this object to self service if not already there.
619 620 621 622 623 624 |
# File 'lib/jss/api_object/self_servable.rb', line 619 def add_to_self_service return nil unless @self_service_data_config[:in_self_service_data_path] return nil if in_self_service? @in_self_service = true @need_to_update = true end |
#create ⇒ Object
HACK: ity hack hack… remove when jamf fixes these bugs
673 674 675 676 677 |
# File 'lib/jss/api_object/self_servable.rb', line 673 def create resp = super force_notifications_on if @need_ss_notification_activation_hack resp end |
#remove_from_self_service ⇒ void
This method returns an undefined value.
Remove this object from self service if it’s there.
630 631 632 633 634 635 |
# File 'lib/jss/api_object/self_servable.rb', line 630 def remove_from_self_service return nil unless @self_service_data_config[:in_self_service_data_path] return nil unless in_self_service? @in_self_service = false @need_to_update = true end |
#remove_self_service_category(cat) ⇒ void
This method returns an undefined value.
Remove a category from those for this item in SSvc
466 467 468 469 |
# File 'lib/jss/api_object/self_servable.rb', line 466 def remove_self_service_category(cat) @self_service_categories.reject! { |c| c[:name] == cat || c[:id] == cat } @need_to_update = true end |
#self_service_execute_url ⇒ String
Returns The url to view this thing in Self Service.
337 338 339 340 |
# File 'lib/jss/api_object/self_servable.rb', line 337 def self_service_execute_url return nil unless @self_service_data_config[:url_entity] "#{USER_URL_BASE}#{@self_service_data_config[:url_entity]}&id=#{id}&action=#{USER_URL_EXEC_ACTION}" end |
#self_service_payload ⇒ Symbol
What does this object deploy to the device via self service?
659 660 661 |
# File 'lib/jss/api_object/self_servable.rb', line 659 def self_service_payload @self_service_data_config[:payload] end |
#self_service_targets ⇒ Array<Symbol>
What devices types can get this thing in Self Service
650 651 652 |
# File 'lib/jss/api_object/self_servable.rb', line 650 def self_service_targets @self_service_data_config[:targets] end |
#self_service_view_url ⇒ String
Returns The url to view this thing in Self Service.
330 331 332 333 |
# File 'lib/jss/api_object/self_servable.rb', line 330 def self_service_view_url return nil unless @self_service_data_config[:url_entity] "#{USER_URL_BASE}#{@self_service_data_config[:url_entity]}&id=#{id}&action=#{USER_URL_VIEW_ACTION}" end |
#update ⇒ Object
HACK: ity hack hack… remove when jamf fixes these bugs
665 666 667 668 669 |
# File 'lib/jss/api_object/self_servable.rb', line 665 def update resp = super force_notifications_on if @need_ss_notification_activation_hack resp end |
#upload(type, local_file) ⇒ String Originally defined in module Uploadable
Upload a file to the JSS via the REST Resource of the object to which this module is mixed in.
#user_removable? ⇒ Boolean?
Can this thing be removed by the user?
641 642 643 644 |
# File 'lib/jss/api_object/self_servable.rb', line 641 def user_removable? return nil unless self_service_payload == :profile @self_service_user_removable != :never end |