Module: JSS::SelfServable

Included in:
OSXConfigurationProfile
Defined in:
lib/jss-api/api_object/self_servable.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 all have similar data, a hash with at least these keys:

  • :self_service_description

  • :self_service_icon

Most also have:

  • :feature_on_main_page

  • :self_service_categories

iOS Profiles in self service have this key:

  • :security

Additionally, items that apper in OS X SlfSvc 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 and calling #parse_self_service in the subclass’s constructor will give it matching attributes with ‘self_service_’ appended if needed, e.g. #self_service_feature_on_main_page

If the subclass is creatable or updatable, calling #self_service_xml returns a REXML element representing the Self Service subset, to be included with the #rest_xml output of the subclass.

Classes including this module must:

  • Define the constant SELF_SERVICE_TARGET which contains either :osx or :ios

  • Define the constant SELF_SERVICE_PAYLOAD which contains one of :policy, :profile, or :app

  • Call #parse_self_service in the subclass’s constructor after calling super

  • Include the result of #self_service_xml in their #rest_xml output

  • Define the method #in_self_service? which returns a Boolean indicating that the item is available in self service. Different API objects indicate this in different ways.

  • Define the method #user_removable? which returns Boolean indicating that the item (a profile) can be removed by the user in SSvc. OS X profiles store this in the :user_removable key of the :general subset as a boolean, whereas iOS profiles stor it in :security as one of 3 strings

Notes:

  • Self service icons cannot be modified via this code. Use the Web UI.

  • There an API bug in handling categories, and all but the last one are ommitted. Until this is fixed, categories cannot be saved via this code since that would cause data-loss when more than one category is applied.

Constant Summary collapse

SELF_SERVABLE =

Constants

true
IOS_PROFILE_REMOVAL_OPTIONS = 
["Always", "With Authorization", "Never"]

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#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

  • :display_in => [Boolean] should the item be displayed in this category in SSvc? (OSX SSvc only)

  • :feature_in => [Boolean] should the item be featured in this category in SSVC? (OSX SSvc only)

NOTE: as of Casper 9.61 there’s a bug in the JSON output from the API, and only the last category is returned, if more than one are set.

Returns:

  • (Array<Hash>) —

    The categories in which this item should appear in SSvc



133
134
135
 
# File 'lib/jss-api/api_object/self_servable.rb', line 133

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



107
108
109
 
# File 'lib/jss-api/api_object/self_servable.rb', line 107

def self_service_description
  @self_service_description
end

#self_service_feature_on_main_page ⇒ Boolean

Returns Should this item feature on the main page of SSvc?.

Returns:

  • (Boolean) —

    Should this item feature on the main page of SSvc?



120
121
122
 
# File 'lib/jss-api/api_object/self_servable.rb', line 120

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)



150
151
152
 
# File 'lib/jss-api/api_object/self_servable.rb', line 150

def self_service_force_users_to_view_description
  @self_service_force_users_to_view_description
end

#self_service_icon ⇒ Hash (readonly)

The Hash contains these keys with info about the icon:

  • :filename => [String] The name of the image file uploaded to the JSS

  • :uri => [String] the URI for retriving the icon

  • :id => [Integer] the JSS id number for the icon (not all SSvc items have this)

  • :data => [String] the icon image encoded as Base64 (not all SSvc items have this)

Returns:

  • (Hash) —

    The icon that appears in SelfSvc for this item



117
118
119
 
# File 'lib/jss-api/api_object/self_servable.rb', line 117

def self_service_icon
  @self_service_icon
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)



147
148
149
 
# File 'lib/jss-api/api_object/self_servable.rb', line 147

def self_service_install_button_text
  @self_service_install_button_text
end

#self_service_security ⇒ Hash (readonly)

The keys are

  • :removal_disallowed => [String] one of the items in IOS_PROFILE_REMOVAL_OPTIONS

  • :password => [String] if :removal_disallowed is “With Authorization”, this contains the passwd (in plaintext) needed to remove the profile.

NOTE that the key should be called :removal_allowed, since ‘Never’ means it can’t be removed.

Returns:

  • (Hash) —

    The security settings for iOS profiles in SSvc



144
145
146
 
# File 'lib/jss-api/api_object/self_servable.rb', line 144

def self_service_security
  @self_service_security
end

Instance Method Details

#add_self_service_category(new_cat, display_in = true, feature_in = false) ⇒ void Also known as: change_self_service_category

This method returns an undefined value.

Add or change one of the categories for this item in SSvc.

Parameters:

  • new_cat (String) —

    the name of a category for this item in SelfSvc

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

    should this item appear in the SelfSvc page for the new category?

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

    should this item be featured in the SelfSvc page for the new category?

Raises:



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/jss-api/api_object/self_servable.rb', line 258

def add_self_service_category (new_cat, display_in = true, feature_in = false)
  new_cat.strip!
  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 JSS::TRUE_FALSE.include? display_in
  raise JSS::InvalidDataError, "feature_in must be true or false" unless JSS::TRUE_FALSE.include? feature_in
  
  new_data = {:name => new_cat, :display_in => display_in, :feature_in => feature_in }
  
  # see if this category is already among our categories.
  idx = @self_service_categories.index{|c| c[new_cat]}
  
  if idx 
    @self_service_categories[idx] = new_data
  else
    @self_service_categories << new_data
  end
  
  @need_to_update = true
end

#parse_self_service ⇒ void

This method returns an undefined value.

Call this during initialization of objects that have a self_service subset and the self_service attributes will be populated (as primary attributes) from @init_data



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/jss-api/api_object/self_servable.rb', line 165

def parse_self_service
  @init_data[:self_service] ||= {}
  ss_data = @init_data[:self_service]
  
  @self_service_description = ss_data[:self_service_description]
  @self_service_icon = ss_data[:self_service_icon]
  
  @self_service_feature_on_main_page = ss_data[:feature_on_main_page]
  
  # TEMPORARY - until JAMF fixes the category data in JSON
  @self_service_categories = [
    ss_data[:self_service_categories][:category]
  ]
  
  # make this an empty hash if needed
  @self_service_security = ss_data[:security] || {}
  
  # if this is an osx profile, set @self_service_security[:removal_disallowed] to "Always" or "Never" 
  # to indicate the boolean :user_removable
  if @init_data[:general].keys.include? :user_removable
    @self_service_security[:removal_disallowed] = @init_data[:general][:user_removable] ? "Always" : "Never"
  end
  
  @self_service_install_button_text = ss_data[:install_button_text]
  @self_service_force_users_to_view_description = ss_data[:force_users_to_view_description]

end

#profile_can_be_removed(new_val) ⇒ void

This method returns an undefined value.

Set whether or when the user can remove a profile installed with SSvc

Parameters:

  • new_val (String) —

    one of the values in PROFILE_REMOVAL_OPTIONS, or true or false

Raises:



298
299
300
301
302
303
304
305
306
307
 
# File 'lib/jss-api/api_object/self_servable.rb', line 298

def profile_can_be_removed (new_val)
  
  new_val = "Always" if new_val === true 
  new_val = "Never" if new_val === false
  
  return nil if new_val == @self_service_security[:removal_disallowed]
  raise JSS::InvalidDataError, "" unless IOS_PROFILE_REMOVAL_OPTIONS.include? new_val
  
  @self_service_security[:removal_disallowed] = new_val
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) —

    the name of the category to remove



285
286
287
288
289
 
# File 'lib/jss-api/api_object/self_servable.rb', line 285

def remove_self_service_category= (cat)
  return nil unless @self_service_categories.map{|c| c[:name]}.include? cat
  @self_service_categories.reject!{|c| c[:name]}
  @need_to_update = true
end

#self_service_xml ⇒ REXML::Element

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return a REXML <location> element to be included in the rest_xml of objects that have a Location subset

Returns:

  • (REXML::Element) 


319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/jss-api/api_object/self_servable.rb', line 319

def self_service_xml
  
  ssvc = REXML::Element.new('self_service')
  
  return ssvc unless self.in_self_service?
  
  ssvc.add_element('self_service_description').text = @self_service_description
  ssvc.add_element('feature_on_main_page').text = @self_service_feature_on_main_page
  
  ### TEMPORARY - re-enable this when the category bug is fixed.
  
#       cats = ssvc.add_element('self_service_categories')
#       @self_service_categories.each do |cat|
#         catelem = cats.add_element('category')
#         catelem.add_element('name').text = cat[:name]
#         catelem.add_element('display_in').text = cat[:display_in] if cat.keys.include? :display_in
#         catelem.add_element('feature_in').text = cat[:feature_in] if cat.keys.include? :feature_in
#       end
  
  unless @self_service_security.empty?
    sec = ssvc.add_element('security')
    sec.add_element('removal_disallowed').text = @self_service_security[:removal_disallowed] if @self_service_security[:removal_disallowed]
    sec.add_element('password').text = @self_service_security[:password] if @self_service_security[:password]
  end
  
  ssvc.add_element('install_button_text').text = @self_service_install_button_text if @self_service_install_button_text
  ssvc.add_element('force_users_to_view_description').text = @self_service_force_users_to_view_description unless @self_service_force_users_to_view_description.nil?

  return ssvc
end