Module: JSS::SelfServable

Includes:
Uploadable
Included in:
ConfigurationProfile, MacApplication, 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 (but not JSS::MacApplication)

  • :install_button_text

  • :reinstall_button_text (but not JSS::MacApplication)

  • :force_users_to_view_description

  • :notification

  • :notification_location # PENDING API FIX, and also, not JSS::MacApplication

  • :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: %i[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,
    notifications_supported: :ssvc_and_nctr,
    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



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

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?



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

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



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

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



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

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.

Returns:

  • (String) —

    The name to display in macOS Self Service.



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

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?



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

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)



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

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)



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

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



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

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



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

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



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

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?



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

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)



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

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



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

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?



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

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.



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

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



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

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:



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/jss/api_object/self_servable.rb', line 435

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.



621
622
623
624
625
626
 
# File 'lib/jss/api_object/self_servable.rb', line 621

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



675
676
677
678
679
 
# File 'lib/jss/api_object/self_servable.rb', line 675

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.



632
633
634
635
636
637
 
# File 'lib/jss/api_object/self_servable.rb', line 632

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



468
469
470
471
 
# File 'lib/jss/api_object/self_servable.rb', line 468

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.

Returns:

  • (String) —

    The url to view this thing in Self Service



337
338
339
340
341
 
# 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?

Returns:

  • (Symbol) —

    :profile, :app, or :policy



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

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.



652
653
654
 
# File 'lib/jss/api_object/self_servable.rb', line 652

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



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

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



667
668
669
670
671
 
# File 'lib/jss/api_object/self_servable.rb', line 667

def update
  resp = super
  force_notifications_on if @need_ss_notification_activation_hack
  resp
end

#upload(type, local_file, force_ipa_upload: false) ⇒ Boolean Originally defined in module Uploadable

instance method wrapper for class method

Upload a file to the JSS to be stored with this instance of the class mixing in the Uploadable module

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.

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

    Should the server upload the .ipa file to JCDS or AWS if such are confgured for use?

Returns:

  • (Boolean) —

    was the upload successful?

Raises:

#user_removable? ⇒ Boolean?

Can this thing be removed by the user?

Returns:

  • (Boolean, nil) —

    nil means 'not applicable'



643
644
645
646
 
# File 'lib/jss/api_object/self_servable.rb', line 643

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