Module: JSS::SelfServable

Includes:
Uploadable
Included in:
ConfigurationProfile, MobileDeviceApplication, 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:

  • :install_button_text

  • :force_users_to_view_description

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

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

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: [: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
  },
  JSS::PatchPolicy => {
    in_self_service_data_path: [:general, :distribution_method],
    in_self_service: PATCHPOL_SELF_SERVICE,
    not_in_self_service: PATCHPOL_AUTO,
    targets: [:macos],
    payload: :patchpolicy,
    can_display_in_categories: false,
    can_feature_in_categories: false
  },
  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
  },
  JSS::OSXConfigurationProfile => {
    in_self_service_data_path: [: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
  },
  JSS::EBook => {
    in_self_service_data_path: [:general, :deployment_type],
    in_self_service: MAKE_AVAILABLE,
    not_in_self_service: AUTO_INSTALL_OR_PROMPT,
    targets: [:macos, :ios],
    payload: :app, # ebooks are handled the same way as apps, it seems,
    can_display_in_categories: true,
    can_feature_in_categories: true
  },
  JSS::MobileDeviceApplication => {
    in_self_service_data_path: [: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: [: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



199
200
201
 
# File 'lib/jss/api_object/self_servable.rb', line 199

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?



195
196
197
 
# File 'lib/jss/api_object/self_servable.rb', line 195

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



219
220
221
 
# File 'lib/jss/api_object/self_servable.rb', line 219

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



203
204
205
 
# File 'lib/jss/api_object/self_servable.rb', line 203

def self_service_description
  @self_service_description
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?



207
208
209
 
# File 'lib/jss/api_object/self_servable.rb', line 207

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)



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

def self_service_force_users_to_view_description
  @self_service_force_users_to_view_description
end

#self_service_install_button_text ⇒ String

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

Returns:

  • (String) —

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



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

def self_service_install_button_text
  @self_service_install_button_text
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.



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

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



236
237
238
 
# File 'lib/jss/api_object/self_servable.rb', line 236

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:



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/jss/api_object/self_servable.rb', line 314

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.



411
412
413
414
415
416
 
# File 'lib/jss/api_object/self_servable.rb', line 411

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

#remove_from_self_service ⇒ void

This method returns an undefined value.

Remove this object from self service if it’s there.



422
423
424
425
426
427
 
# File 'lib/jss/api_object/self_servable.rb', line 422

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



346
347
348
349
 
# File 'lib/jss/api_object/self_servable.rb', line 346

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

#self_service_payload ⇒ Symbol

What does this object deploy to the device via self service?

Returns:

  • (Symbol) —

    :profile, :app, or :policy



451
452
453
 
# File 'lib/jss/api_object/self_servable.rb', line 451

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.



442
443
444
 
# File 'lib/jss/api_object/self_servable.rb', line 442

def self_service_targets
  @self_service_data_config[:targets]
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’



433
434
435
436
 
# File 'lib/jss/api_object/self_servable.rb', line 433

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