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 => { # TODO: add the correct values when Jamf fixes this bug
    in_self_service_data_path: nil, # [:general, :distribution_method],
    in_self_service: nil, # MAKE_AVAILABLE,
    not_in_self_service: nil, # 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

Instance Method Summary collapse

Instance Attribute Details

#icon ⇒ JSS::Icon? Also known as: self_service_icon

Returns The icon used in self-service.

Returns:

  • (JSS::Icon, nil) —

    The icon used in self-service



244
245
246
 
# File 'lib/jss/api_object/self_servable.rb', line 244

def icon
  @icon
end

#in_self_service ⇒ Boolean (readonly) Also known as: in_self_service?

Returns Is this thing available in Self Service?.

Returns:

  • (Boolean) —

    Is this thing available in Self Service?



240
241
242
 
# File 'lib/jss/api_object/self_servable.rb', line 240

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)

Returns:

  • (Array<Hash>) —

    The categories in which this item should appear in SSvc



267
268
269
 
# File 'lib/jss/api_object/self_servable.rb', line 267

def self_service_categories
  @self_service_categories
end

#self_service_description ⇒ String

Returns The verbage that appears in SelfSvc for this item.

Returns:

  • (String) —

    The verbage that appears in SelfSvc for this item



251
252
253
 
# File 'lib/jss/api_object/self_servable.rb', line 251

def self_service_description
  @self_service_description
end

#self_service_display_name ⇒ String (readonly)

Returns The name to display in macOS Self Service.

Returns:

  • (String) —

    The name to display in macOS Self Service.



248
249
250
 
# File 'lib/jss/api_object/self_servable.rb', line 248

def self_service_display_name
  @self_service_display_name
end

#self_service_feature_on_main_page ⇒ Boolean

Only applicable to macOS targets

Returns:

  • (Boolean) —

    Should this item feature on the main page of SSvc?



255
256
257
 
# File 'lib/jss/api_object/self_servable.rb', line 255

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).

Returns:

  • (Boolean) —

    Should an extra window appear before the user can install the item? (OSX SSvc only)



298
299
300
 
# File 'lib/jss/api_object/self_servable.rb', line 298

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’

Returns:

  • (String) —

    The text label on the install button in SSvc (OSX SSvc only)



291
292
293
 
# File 'lib/jss/api_object/self_servable.rb', line 291

def self_service_install_button_text
  @self_service_install_button_text
end

#self_service_notification_message ⇒ String

Returns The message text of the notification.

Returns:

  • (String) —

    The message text of the notification



313
314
315
 
# File 'lib/jss/api_object/self_servable.rb', line 313

def self_service_notification_message
  @self_service_notification_message
end

#self_service_notification_subject ⇒ String

object name.

Returns:

  • (String) —

    The subject text of the notification. Defaults to the



310
311
312
 
# File 'lib/jss/api_object/self_servable.rb', line 310

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.

Returns:

  • (Symbol) —

    How should notifications be sent either :ssvc_only or :ssvc_and_nctr



306
307
308
 
# File 'lib/jss/api_object/self_servable.rb', line 306

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?.

Returns:

  • (Boolean) —

    Should jamf send notifications to self service?



301
302
303
 
# File 'lib/jss/api_object/self_servable.rb', line 301

def self_service_notifications_enabled
  @self_service_notifications_enabled
end

#self_service_reinstall_button_text ⇒ String

defaults to ‘Reinstall’

Returns:

  • (String) —

    The text label on the reinstall button in SSvc (OSX SSvc only)



295
296
297
 
# File 'lib/jss/api_object/self_servable.rb', line 295

def self_service_reinstall_button_text
  @self_service_reinstall_button_text
end

#self_service_reminder_frequency ⇒ Integer

Returns How often (in days) should reminders be given.

Returns:

  • (Integer) —

    How often (in days) should reminders be given



321
322
323
 
# File 'lib/jss/api_object/self_servable.rb', line 321

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?.

Returns:

  • (Boolean) —

    Should self service give reminders by displaying the notification repeatedly?



317
318
319
 
# File 'lib/jss/api_object/self_servable.rb', line 317

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.

Returns:

  • (String) —

    The password needed for removal, in plain text.



287
288
289
 
# File 'lib/jss/api_object/self_servable.rb', line 287

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.

Returns:

  • (Symbol) —

    one of the keys in PROFILE_REMOVAL_BY_USER



284
285
286
 
# File 'lib/jss/api_object/self_servable.rb', line 284

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

Parameters:

  • new_cat (String, Integer) —

    the name or id of a category where this object should appear in SelfSvc

  • display_in (Boolean) (defaults to: true) —

    should this item appear in the SelfSvc page for the category? Only meaningful in applicable classes

  • feature_in (Boolean) (defaults to: false) —

    should this item be featured in the SelfSvc page for the category? Only meaningful in applicable classes. NOTE: this will always be false if display_in is false.

Raises:



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/jss/api_object/self_servable.rb', line 429

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.



615
616
617
618
619
620
 
# File 'lib/jss/api_object/self_servable.rb', line 615

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



669
670
671
672
673
 
# File 'lib/jss/api_object/self_servable.rb', line 669

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.



626
627
628
629
630
631
 
# File 'lib/jss/api_object/self_servable.rb', line 626

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

Parameters:

  • cat (String, Integer) —

    the name or id of the category to remove



462
463
464
465
 
# File 'lib/jss/api_object/self_servable.rb', line 462

def remove_self_service_category(cat)
  @self_service_categories.reject! { |c| c[:name] == cat || c[:id] == cat }
  @need_to_update = true
end

#self_service_dislay_name=(new_val) ⇒ void

This method returns an undefined value.

Parameters:

  • new_val (String) —

    The display name of the item in SSvc

Raises:



358
359
360
361
362
363
364
 
# File 'lib/jss/api_object/self_servable.rb', line 358

def self_service_dislay_name=(new_val)
  new_val.strip!
  return nil if @self_service_dislay_name == new_val
  raise JSS::InvalidDataError, 'Only macOS Self Service items have display names' unless self_service_targets.include? :macos
  @self_service_dislay_name = new_val
  @need_to_update = true
end

#self_service_execute_url ⇒ String

Returns The url to view this thing in Self Service.

Returns:

  • (String) —

    The url to view this thing in Self Service



335
336
337
338
 
# File 'lib/jss/api_object/self_servable.rb', line 335

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?

Returns:

  • (Symbol) —

    :profile, :app, or :policy



655
656
657
 
# File 'lib/jss/api_object/self_servable.rb', line 655

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

Returns:

  • (Array<Symbol>) —

    An array of :macos, :ios, or both.



646
647
648
 
# File 'lib/jss/api_object/self_servable.rb', line 646

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.

Returns:

  • (String) —

    The url to view this thing in Self Service



328
329
330
331
 
# File 'lib/jss/api_object/self_servable.rb', line 328

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



661
662
663
664
665
 
# File 'lib/jss/api_object/self_servable.rb', line 661

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.

Parameters:

  • type (Symbol) —

    the type of upload happening. Must be one of the keys defined in the class’s UPLOAD_TYPES Hash.

  • local_file (String, Pathname) —

    String or Pathname pointing to the locally-readable file to be uploaded.

Returns:

  • (String) —

    The xml response from the server.

Raises:

#user_removable? ⇒ Boolean?

Can this thing be removed by the user?

Returns:

  • (Boolean, nil) —

    nil means ‘not applicable’



637
638
639
640
 
# File 'lib/jss/api_object/self_servable.rb', line 637

def user_removable?
  return nil unless self_service_payload == :profile
  @self_service_user_removable != :never
end