Module: JSS::SelfServable

Includes:
Uploadable
Included in:
MobileDeviceApplication, OSXConfigurationProfile, 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() in their #rest_xml method

IMPORTANT: Since SelfServable also includes #Updatable, 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
DEFAULT_INSTALL_BUTTON_TEXT = 
'Install'.freeze
SELF_SERVICE_CLASSES = 
{
  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::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



159
160
161
 
# File 'lib/jss/api_object/self_servable.rb', line 159

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?



155
156
157
 
# File 'lib/jss/api_object/self_servable.rb', line 155

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



179
180
181
 
# File 'lib/jss/api_object/self_servable.rb', line 179

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



163
164
165
 
# File 'lib/jss/api_object/self_servable.rb', line 163

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?



167
168
169
 
# File 'lib/jss/api_object/self_servable.rb', line 167

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)



205
206
207
 
# File 'lib/jss/api_object/self_servable.rb', line 205

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)



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

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.



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

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



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

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:



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/jss/api_object/self_servable.rb', line 274

def add_self_service_category(new_cat, display_in: true, feature_in: false)
  new_cat = JSS::Category.map_all_ids_to(:name)[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).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.



367
368
369
370
371
372
 
# File 'lib/jss/api_object/self_servable.rb', line 367

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.



378
379
380
381
382
383
 
# File 'lib/jss/api_object/self_servable.rb', line 378

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



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

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



407
408
409
 
# File 'lib/jss/api_object/self_servable.rb', line 407

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.



398
399
400
 
# File 'lib/jss/api_object/self_servable.rb', line 398

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’



389
390
391
392
 
# File 'lib/jss/api_object/self_servable.rb', line 389

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