Module: Xolo::Server::Mixins::VersionTedAccess

Included in:
Version
Defined in:
lib/xolo/server/mixins/version_ted_access.rb

Overview

This is mixed in to Xolo::Server::Version to define Version/Patch-related access to the Title Edit server

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(includer) ⇒ Object

when this module is included



32
33
34
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 32

def self.included(includer)
  Xolo.verbose_include includer, self
end

Instance Method Details

#create_patch_in_ted ⇒ void

This method returns an undefined value.

Create a new version in the title editor

TODO: allow specification of version_order, probably by accepting a value for the ‘previous_version’?



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 50

def create_patch_in_ted
  progress "Title Editor: Creating Patch '#{version}' of SoftwareTitle '#{title}'", log: :info
  ted_title.patches.add_patch(
    version: version,
    minimumOperatingSystem: min_os,
    releaseDate: publish_date,
    reboot: reboot,
    standalone: standalone
  )
  new_patch = ted_title.patches.patch version

  set_patch_killapps
  set_patch_capabilites
  set_ted_patch_component_criteria ttl_obj: title_object

  self.ted_id_number = new_patch.patchId
end

#delete_patch_from_ted ⇒ Integer

Delete from the title editor

Returns:

  • (Integer) —

    title editor id



322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 322

def delete_patch_from_ted
  patch_id = ted_title.patches.versions_to_patchIds[version]
  if patch_id
    progress "Title Editor: Deleting Patch '#{version}' of SoftwareTitle '#{title}'", log: :info
    ted_title.patches.delete_patch patch_id

  else
    log_debug "Title Editor: No id for Patch '#{version}' of SoftwareTitle '#{title}', nothing to delete"
  end

  ted_id_number
rescue Windoo::NoSuchItemError
  ted_id_number
end

#enable_ted_patch ⇒ void

This method returns an undefined value.

For a patch to be enabled in the Title Editor, it needs at least a component criterion and one capability. Xolo enforces those when the patch is created, so from the title editor’s view it should be OK from the start.

But Xolo can’t really do anything with it until there’s a Jamf Package object and an uploaded installer. So once we have those, this method is called to enable the patch.

Parameters:



314
315
316
317
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 314

def enable_ted_patch
  progress "Title Editor: (Re-)Enabling Patch '#{version}' of SoftwareTitle '#{title}'", log: :info
  ted_patch(refresh: true).enable
end

#get_patch_component_criteria_params(ttl_obj) ⇒ Array

get the param values for patch component criteria from the title object, which may be setting them via an update

Parameters:

Returns:

  • (Array) —

    the values for the component criteria



249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 249

def get_patch_component_criteria_params(ttl_obj)
  app_name, app_bundle_id, ea_name = nil

  if ttl_obj.updating?
    if ttl_obj.changes_for_update.dig :app_name, :new
      app_name = ttl_obj.changes_for_update[:app_name][:new]
      app_bundle_id = ttl_obj.changes_for_update[:app_bundle_id][:new]
    else
      ea_name = ttl_obj.ted_ea_key
    end
  elsif ttl_obj.app_name
    app_name = ttl_obj.app_name
    app_bundle_id = ttl_obj.app_bundle_id
  else
    ea_name = ttl_obj.ted_ea_key
  end

  [app_name, app_bundle_id, ea_name]
end

#repair_ted_patch ⇒ Object

Ensure all the TEd items for this version are correct based on the server data.



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 345

def repair_ted_patch
  progress "Title Editor: Repairing Patch '#{version}' of SoftwareTitle '#{title}'", log: :info

  Xolo::Server::Version::ATTRIBUTES.each do |attr, deets|
    ted_attribute = deets[:ted_attribute]
    # if there's no ted_attribute, this isn't a value stored in the Title Editor
    next unless ted_attribute

    real_val = send(attr)
    ted_val = ted_patch.send(ted_attribute)
    next if ted_val == real_val

    # These changes happen in real time on the Title Editor server, no need to #save
    progress "Title Editor: Repairing patch attribute '#{ted_attribute}': #{ted_val} -> #{real_val}"
    ted_patch.send "#{ted_attribute}=", real_val
  end
  set_patch_killapps
  set_patch_capabilites
  set_ted_patch_component_criteria ttl_obj: title_object
  enable_ted_patch unless ted_patch(refresh: true).enabled?
end

#set_app_component(comp, app_name, app_bundle_id) ⇒ void

This method returns an undefined value.



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 282

def set_app_component(comp, app_name, app_bundle_id)
  comp.criteria.add_criterion(
    name: 'Application Title',
    operator: 'is',
    value: app_name
  )

  comp.criteria.add_criterion(
    name: 'Application Bundle ID',
    operator: 'is',
    value: app_bundle_id
  )

  comp.criteria.add_criterion(
    name: 'Application Version',
    operator: 'is',
    value: version
  )
end

#set_ea_component(comp, ea_name) ⇒ void

This method returns an undefined value.



271
272
273
274
275
276
277
278
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 271

def set_ea_component(comp, ea_name)
  comp.criteria.add_criterion(
    type: 'extensionAttribute',
    name: ea_name,
    operator: 'is',
    value: version
  )
end

#set_patch_capabilites ⇒ void

This method returns an undefined value.

Set the capabilities for this version in the title editor. This is a collection of criteria that define which computers can install this version.

At the very least we enforce the required minimum OS. and optional maximim OS.

TODO: Allow xadm to specify other capability criteria?



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
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
192
193
194
195
196
197
198
199
200
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 148

def set_patch_capabilites
  # creating a new patch? Just use the current values
  if creating?
    min = min_os
    max = max_os

  # updating an existing patch? Use the new values if they exist
  # noting that a nil new value for max_os means its being removed
  elsif updating?
    return unless changes_for_update&.key?(:max_os) || changes_for_update&.key?(:min_os)

    # min gets reset even if it didn't change and it can't be empty.
    min = changes_for_update.dig(:min_os, :new) || min_os

    # if max is changing and its nil, its being removed, so won't be re-added
    # if its not changing, keep the current value
    max = changes_for_update&.key?(:max_os) ? changes_for_update[:max_os][:new] : max_os

    # delete the existing criteria
    ted_patch.capabilities.delete_all_criteria

  elsif repairing?
    min = min_os
    max = max_os
    # delete the existing criteria
    ted_patch.capabilities.delete_all_criteria

  else
    return
  end
  return unless min || max

  msg = "Title Editor: Setting min_os capability for Patch '#{version}' of SoftwareTitle '#{title}' to '#{min}'"
  progress msg, log: :info

  # min os - one is always required
  ted_patch.capabilities.add_criterion(
    name: 'Operating System Version',
    operator: 'greater than or equal',
    value: min
  )

  return unless max

  msg = "Title Editor: Setting max_os capability for Patch '#{version}' of SoftwareTitle '#{title}' to '#{max}'"
  progress msg, log: :debug

  ted_patch.capabilities.add_criterion(
    name: 'Operating System Version',
    operator: 'less than or equal',
    value: max
  )
end

#set_patch_killapps ⇒ void

This method returns an undefined value.

Set any killapps for this version in the title editor.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 103

def set_patch_killapps
  # creating a new patch
  if creating?
    kapps = killapps

  # updating - delete and replace with any new ones
  elsif updating?
    return unless changes_for_update.key? :killapps

    kapps = changes_for_update[:killapps][:new]
    ted_patch.killApps.delete_all_killApps

  # repairing delete and replace with current, to ensure values are correct.
  elsif repairing?
    kapps = killapps
    ted_patch.killApps.delete_all_killApps
  else
    return
  end
  return if kapps.pix_empty?

  # set the current values
  kapps.each do |ka_str|
    msg = "Title Editor: Setting killApp '#{ka_str}' for Patch '#{version}' of SoftwareTitle '#{title}'"
    progress msg, log: :info

    name, bundleid = ka_str.split(Xolo::SEMICOLON_SEP_RE)
    ted_patch.killApps.add_killApp(
      appName: name,
      bundleId: bundleid
    )
  end
end

#set_ted_patch_component_criteria(app_name: nil, app_bundle_id: nil, ea_name: nil, ttl_obj: nil) ⇒ void

This method returns an undefined value.

Set the component criteria for this version in the title editor.

This is a collection of criteria that define which computers have this version installed

Parameters:

  • app_name (String) (defaults to: nil) —

    the name of the app to use in app-based requirements, must be used with app_bundle_id, cannot be used with ea_name

  • app_bundle_id (String) (defaults to: nil) —

    the bundle id of the app to use in app-based requirements must be used with app_name, cannot be used with ea_name

  • ea_name (String) (defaults to: nil) —

    the name of the EA to use in EA-based requirements (the ted_ea_key) Cannot be used with app_name or app_bundle_id

  • ttl_obj (Xolo::Server::Title) (defaults to: nil) —

    the title object with the values



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 220

def set_ted_patch_component_criteria(app_name: nil, app_bundle_id: nil, ea_name: nil, ttl_obj: nil)
  if ttl_obj
    app_name, app_bundle_id, ea_name = get_patch_component_criteria_params(ttl_obj)

  elsif !((app_name && app_bundle_id) || ea_name)
    raise Xolo::MissingDataError, 'Must provide either ea_name or app_name & app_bundle_id, or ttl_obj'
  end

  type = ea_name ? 'Extension Attribute (version_script)' : 'App'
  msg = "Title Editor: Setting #{type}-based component criteria for Patch '#{version}' of SoftwareTitle '#{title}'"
  progress msg, log: :info

  # delete any already there and make a new one
  ted_patch.delete_component
  ted_patch.add_component name: title, version: version
  comp = ted_patch.component

  ea_name ? set_ea_component(comp, ea_name) : set_app_component(comp, app_name, app_bundle_id)

  # SHouldn't be needed here, is called in both create and update
  # enable_ted_patch
end

#ted_patch_url ⇒ String

Returns the URL for the Title Editor Web App page for this patch.

Returns:

  • (String) —

    the URL for the Title Editor Web App page for this patch



339
340
341
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 339

def ted_patch_url
  "https://#{Xolo::Server.config.ted_hostname}/patches/#{ted_id_number}"
end

#update_patch_in_ted ⇒ void

This method returns an undefined value.

Update version/patch in the title editor directly. This never called when updating versions via changes to the title - that process calls the sub-methods directly.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/xolo/server/mixins/version_ted_access.rb', line 74

def update_patch_in_ted
  progress "Title Editor: Updating Patch '#{version}' SoftwareTitle '#{title}'", log: :info

  Xolo::Server::Version::ATTRIBUTES.each do |attr, deets|
    ted_attribute = deets[:ted_attribute]
    next unless ted_attribute

    new_val = new_data_for_update[attr]
    old_val = send(attr)
    next if new_val == old_val

    # These changes happen in real time on the Title Editor server, no need to #save
    log_debug "Title Editor: Updating patch attribute '#{ted_attribute}': #{old_val} -> #{new_val}"
    ted_patch.send "#{ted_attribute}=", new_val
  end

  set_patch_killapps if changes_for_update[:killapps]
  set_patch_capabilites if changes_for_update[:min_os] || changes_for_update[:max_os]

  # This should not be needed here - its only affected by changes to the title, and
  # those are handled by the title object calling the same method
  #
  # set_ted_patch_component_criteria ttl_obj: title_object
end