Class: JSS::ConfigurationProfile

Inherits:
APIObject show all
Includes:
Categorizable, Scopable, SelfServable, Sitable, Updatable
Defined in:
lib/jss/api_object/configuration_profile.rb,
lib/jss.rb

Overview

The parent class of OSXConfigurationProfile and MobileDeviceConfigurationProfile

Note that the profile payloads and the profile UUID cannot be edited or updated with this via this class. Use the web UI.

See Also:

Constant Summary collapse

DISTRIBUTION_METHODS =

The possible values for the distribution_method/deployment_method

['Install Automatically', 'Make Available in Self Service'].freeze
SELF_SERVICE_DIST_METHOD =

which DISTRIBUTION_METHODS means we're in self service?

'Make Available in Self Service'.freeze
REDEPLOY_NEWLY_ASSIGNED =

when a change is made, which in-scope machines should get the changed profile?

'Newly Assigned'.freeze
REDEPLOY_ALL = 
'All'.freeze
SELF_SERVICE_PAYLOAD =

Our SelfService deploys profiles

:profile
SITE_SUBSET =

Where is the Site data in the API JSON?

:general
CATEGORY_SUBSET =

Where is the Category in the API JSON?

:general
CATEGORY_DATA_TYPE =

How is the category stored in the API data?

Hash

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ ConfigurationProfile

See JSS::APIObject#initialize



99
100
101
102
103
104
105
 
# File 'lib/jss/api_object/configuration_profile.rb', line 99

def initialize(args = {})
  super
  @description = @main_subset[:description]
  @uuid = @main_subset[:uuid]
  @redeploy_on_update = @main_subset[:redeploy_on_update]
  @payloads = @main_subset[:payloads]
end

Instance Attribute Details

#description ⇒ String

Returns the description of this profile.

Returns:

  • (String) —

    the description of this profile



79
80
81
 
# File 'lib/jss/api_object/configuration_profile.rb', line 79

def description
  @description
end

#icon ⇒ JSS::Icon? Also known as: self_service_icon Originally defined in module SelfServable

Returns The icon used in self-service.

Returns:

  • (JSS::Icon, nil) —

    The icon used in self-service

#in_self_service ⇒ Boolean (readonly) Also known as: in_self_service? Originally defined in module SelfServable

Returns Is this thing available in Self Service?.

Returns:

  • (Boolean) —

    Is this thing available in Self Service?

#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable

Returns do we have unsaved changes?.

Returns:

  • (Boolean) —

    do we have unsaved changes?

#payloads ⇒ String (readonly)

Returns the plist containing the payloads for this profile. NOT Updatable.

Returns:

  • (String) —

    the plist containing the payloads for this profile. NOT Updatable



92
93
94
 
# File 'lib/jss/api_object/configuration_profile.rb', line 92

def payloads
  @payloads
end

#redeploy_on_update ⇒ String (readonly)

Returns When a change is made to the profile, which scoped machines should get the changes? This will always contain REDEPLOY_NEWLY_ASSIGNED when fetched, but can be set to REDEPLOY_ALL via the redeploy_to_all: parameter to #update & #save. After the update is complete, it reverts to REDEPLOY_NEWLY_ASSIGNED.

Returns:

  • (String) —

    When a change is made to the profile, which scoped machines should get the changes? This will always contain REDEPLOY_NEWLY_ASSIGNED when fetched, but can be set to REDEPLOY_ALL via the redeploy_to_all: parameter to #update & #save. After the update is complete, it reverts to REDEPLOY_NEWLY_ASSIGNED



89
90
91
 
# File 'lib/jss/api_object/configuration_profile.rb', line 89

def redeploy_on_update
  @redeploy_on_update
end

#scope ⇒ Object Originally defined in module Scopable

Attribtues

#self_service_categories ⇒ Array<Hash> (readonly) Originally defined in module SelfServable

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

#self_service_description ⇒ String Originally defined in module SelfServable

Returns The verbage that appears in SelfSvc for this item.

Returns:

  • (String) —

    The verbage that appears in SelfSvc for this item

#self_service_display_name ⇒ String Also known as: self_service_dislay_name Originally defined in module SelfServable

Returns The name to display in macOS Self Service.

Returns:

  • (String) —

    The name to display in macOS Self Service.

#self_service_feature_on_main_page ⇒ Boolean Originally defined in module SelfServable

Only applicable to macOS targets

Returns:

  • (Boolean) —

    Should this item feature on the main page of SSvc?

#self_service_force_users_to_view_description ⇒ Boolean Originally defined in module SelfServable

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)

#self_service_install_button_text ⇒ String Originally defined in module SelfServable

defaults to 'Install'

Returns:

  • (String) —

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

#self_service_notification_message ⇒ String Originally defined in module SelfServable

Returns The message text of the notification.

Returns:

  • (String) —

    The message text of the notification

#self_service_notification_subject ⇒ String Originally defined in module SelfServable

object name.

Returns:

  • (String) —

    The subject text of the notification. Defaults to the

#self_service_notification_type ⇒ Symbol Originally defined in module SelfServable

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

#self_service_notifications_enabled ⇒ Boolean Also known as: self_service_notifications_enabled? Originally defined in module SelfServable

Returns Should jamf send notifications to self service?.

Returns:

  • (Boolean) —

    Should jamf send notifications to self service?

#self_service_reinstall_button_text ⇒ String Originally defined in module SelfServable

defaults to 'Reinstall'

Returns:

  • (String) —

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

#self_service_reminder_frequency ⇒ Integer Originally defined in module SelfServable

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

Returns:

  • (Integer) —

    How often (in days) should reminders be given

#self_service_reminders_enabled ⇒ Boolean Also known as: self_service_reminders_enabled? Originally defined in module SelfServable

Returns Should self service give reminders by displaying the notification repeatedly?.

Returns:

  • (Boolean) —

    Should self service give reminders by displaying the notification repeatedly?

#self_service_removal_password ⇒ String (readonly) Originally defined in module SelfServable

Returns The password needed for removal, in plain text.

Returns:

  • (String) —

    The password needed for removal, in plain text.

#self_service_user_removable ⇒ Symbol Originally defined in module SelfServable

Returns one of the keys in PROFILE_REMOVAL_BY_USER.

Returns:

  • (Symbol) —

    one of the keys in PROFILE_REMOVAL_BY_USER

#uuid ⇒ String (readonly)

Returns the uuid of this profile. NOT Updatable.

Returns:

  • (String) —

    the uuid of this profile. NOT Updatable



82
83
84
 
# File 'lib/jss/api_object/configuration_profile.rb', line 82

def uuid
  @uuid
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 Originally defined in module SelfServable

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:

#add_to_self_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

Add this object to self service if not already there.

#category=(new_cat) ⇒ void Originally defined in module Categorizable

This method returns an undefined value.

Change the category of this object. Any of the NON_CATEGORIES values will unset the category

Parameters:

  • new_cat (Integer, String) —

    The new category

Raises:

#category_assigned? ⇒ Boolean Also known as: categorized? Originally defined in module Categorizable

Does this object have a category assigned?

Returns:

  • (Boolean) —

    Does this object have a category assigned?

#category_id ⇒ Integer Originally defined in module Categorizable

The id of the category for this object.

Returns:

  • (Integer) —

    The id of the category for this object.

#category_name ⇒ String Also known as: category Originally defined in module Categorizable

The name of the category for this object. For backward compatibility, this is aliased to just 'category'

Returns:

  • (String) —

    The name of the category for this object.

#category_object ⇒ JSS::Category Originally defined in module Categorizable

The JSS::Category instance for this object's category

Returns:

  • (JSS::Category) —

    The JSS::Category instance for this object's category

#create ⇒ Object Originally defined in module SelfServable

HACK: ity hack hack… remove when jamf fixes these bugs

#evaluate_new_category(new_cat) ⇒ Array<String, Integer> Originally defined in module Categorizable

Given a category name or id, return the name and id TODO: use APIObject.exist? and/or APIObject.valid_id

Parameters:

  • new_cat (String, Integer) —

    The name or id of a possible category

Returns:

  • (Array<String, Integer>) —

    The matching name and id, which may be nil.

#name=(newname) ⇒ void Originally defined in module Updatable

This method returns an undefined value.

Change the name of this item Remember to #update to push changes to the server.

Parameters:

  • newname (String) —

    the new name

Raises:

#parse_scope ⇒ void Originally defined in module Scopable

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.

This method returns an undefined value.

Call this during initialization of objects that have a scope and the scope instance will be created from @init_data

#parsed_payloads ⇒ Hash

The @payloads Plist, parsed into a Ruby object

Returns:

  • (Hash) —

    the parsed payloads plist.



125
126
127
 
# File 'lib/jss/api_object/configuration_profile.rb', line 125

def parsed_payloads
  JSS.parse_plist @payloads
end

#payload_content ⇒ Array<Hash>

Returns the individual payloads from the payload Plist.

Returns:

  • (Array<Hash>) —

    the individual payloads from the payload Plist



131
132
133
 
# File 'lib/jss/api_object/configuration_profile.rb', line 131

def payload_content
  parsed_payloads['PayloadContent']
end

#payload_content=(new_content) ⇒ void

This method returns an undefined value.

Parameters:

  • new_content (Array<Hash>) —

    replace the payload content entirely.

    The 'payload' of a config profile is an XML Plist. The top-level key of that plist 'PayloadContent' contains an Array of Dicts, each one being a part of the payload for the profile.

    When replacing the PayloadContent Array, using this method, provide a ruby Array full of ruby hashes, and they will be converted to a Plist and embedded into the API XML appropriately.

    WARNING: This is experimental! Editing the Plist Payload of a Config profile may break the profile. Make sure you test on a fake profile before using this method in production.



151
152
153
154
155
156
157
 
# File 'lib/jss/api_object/configuration_profile.rb', line 151

def payload_content=(new_content)
  payload_plist_data = parsed_payloads
  payload_plist_data['PayloadContent'] = new_content
  @payloads = JSS.xml_plist_from new_content
  @need_to_update = true
  @update_payloads = true
end

#payload_types ⇒ Array<String>

Returns the PayloadType of each payload (e.g. com.apple.caldav.account).

Returns:

  • (Array<String>) —

    the PayloadType of each payload (e.g. com.apple.caldav.account)



161
162
163
 
# File 'lib/jss/api_object/configuration_profile.rb', line 161

def payload_types
  payload_content.map { |p| p['PayloadType'] }
end

#remove_from_self_service ⇒ void Originally defined in module SelfServable

This method returns an undefined value.

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

#remove_self_service_category(cat) ⇒ void Originally defined in module SelfServable

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

#save(redeploy_to_all: false) ⇒ Object

wrapper with param



175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/jss/api_object/configuration_profile.rb', line 175

def save(redeploy_to_all: false)
  if @in_jss
    raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?

    update redeploy_to_all: redeploy_to_all
  else
    raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?

    create
  end
end

#self_service_execute_url ⇒ String Originally defined in module SelfServable

Returns The url to view this thing in Self Service.

Returns:

  • (String) —

    The url to view this thing in Self Service

#self_service_payload ⇒ Symbol Originally defined in module SelfServable

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

Returns:

  • (Symbol) —

    :profile, :app, or :policy

#self_service_targets ⇒ Array<Symbol> Originally defined in module SelfServable

What devices types can get this thing in Self Service

Returns:

  • (Array<Symbol>) —

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

#self_service_view_url ⇒ String Originally defined in module SelfServable

Returns The url to view this thing in Self Service.

Returns:

  • (String) —

    The url to view this thing in Self Service

#should_update ⇒ void Originally defined in module Scopable

This method returns an undefined value.

When the scope changes, it calls this to tell us that an update is needed.

#site=(new_site) ⇒ void Originally defined in module Sitable

This method returns an undefined value.

Change the site of this object. Any of the NON_SITES values will unset the site

Parameters:

  • new_site (Integer, String) —

    The new site

Raises:

#site_assigned? ⇒ Boolean Originally defined in module Sitable

Does this object have a site assigned?

Returns:

  • (Boolean) —

    Does this object have a site assigned?

#site_id ⇒ Integer Originally defined in module Sitable

The id of the site for this object.

Returns:

  • (Integer) —

    The id of the site for this object.

#site_name ⇒ String Also known as: site Originally defined in module Sitable

The name of the site for this object. For backward compatibility, this is aliased to just 'site'

Returns:

  • (String) —

    The name of the site for this object.

#site_object ⇒ JSS::Site Originally defined in module Sitable

The JSS::Site instance for this object's site

Returns:

  • (JSS::Site) —

    The JSS::Site instance for this object's site

#unset_category ⇒ void Originally defined in module Categorizable

This method returns an undefined value.

Set the category to nothing

#unset_site ⇒ void Originally defined in module Sitable

This method returns an undefined value.

Set the site to nothing

#update(redeploy_to_all: false) ⇒ Object

clear flag after updating



166
167
168
169
170
171
172
 
# File 'lib/jss/api_object/configuration_profile.rb', line 166

def update(redeploy_to_all: false)
  @redeploy_on_update = redeploy_to_all ? REDEPLOY_ALL : REDEPLOY_NEWLY_ASSIGNED
  super()
  # always reset to newly assigned
  @redeploy_on_update = REDEPLOY_NEWLY_ASSIGNED
  @update_payloads = nil
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? Originally defined in module SelfServable

Can this thing be removed by the user?

Returns:

  • (Boolean, nil) —

    nil means 'not applicable'