Module: Xolo::Admin::Processing

Defined in:
lib/xolo/admin/processing.rb

Overview

Methods that execute the xadm commands and their options

Constant Summary collapse

SEARCH_ATTRIBUTES =

Title attributes that are used for ‘xadm search’

%i[title display_name description publisher app_name app_bundle_id].freeze
SERVER_STATUS_ROUTE =

Routes for server admins

'/maint/state'
SERVER_CLEANUP_ROUTE = 
'/maint/cleanup'
SERVER_ROTATE_LOGS_ROUTE = 
'/maint/rotate-logs'
SERVER_UPDATE_CLIENT_DATA_ROUTE = 
'/maint/update-client-data'
SERVER_LOG_LEVEL_ROUTE = 
'/maint/set-log-level'
SERVER_SHUTDOWN_ROUTE = 
'/maint/shutdown-server'
LOG_LEVELS =

We can’t pull this from Xolo::Server::Log::LEVELS, because we don’t want to require that file here, it’ll complain about the lack of sinatra and such.

%w[debug info warn error fatal].freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(extender) ⇒ Object

when this module is extended



50
51
52
 
# File 'lib/xolo/admin/processing.rb', line 50

def self.extended(extender)
  Xolo.verbose_extend extender, self
end

.included(includer) ⇒ Object

when this module is included



45
46
47
 
# File 'lib/xolo/admin/processing.rb', line 45

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

Instance Method Details

#add_title ⇒ void

This method returns an undefined value.

Add a title to Xolo



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/xolo/admin/processing.rb', line 237

def add_title
  return unless confirmed? "Add title '#{cli_cmd.title}'"

  opts_to_process.title = cli_cmd.title
  read_uninstall_script

  new_title = Xolo::Admin::Title.new opts_to_process

  # TMP TESTING
  # puts 'DEBUG: opts_to_process:'
  # opts_to_process.to_h.each do |k, v|
  #   puts "  #{k}: #{v}"
  # end
  # return

  response_data = new_title.add(server_cnx)

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end
  if response_data[:progress_stream_url_path]
    display_progress response_data[:progress_stream_url_path]
  else
    puts '# No progress stream URL returned'
    return
  end

  # Upload the ssvc icon, if any?
  upload_ssvc_icon new_title

  speak "Title '#{cli_cmd.title}' has been added to Xolo.\nEnsure there's at least one version to enable piloting and deployment"
rescue StandardError => e
  handle_processing_error e
end

#add_version ⇒ void

This method returns an undefined value.

Add a version to a title to Xolo



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
 
# File 'lib/xolo/admin/processing.rb', line 511

def add_version
  return unless confirmed? "Add version '#{cli_cmd.version}' to title '#{cli_cmd.title}'"

  opts_to_process.title = cli_cmd.title
  opts_to_process.version = cli_cmd.version

  title_obj = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  new_vers = Xolo::Admin::Version.new opts_to_process
  response_data = new_vers.add(server_cnx)

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]

  # Upload the pkg, if any?
  upload_pkg(new_vers) unless title_obj.autopkg_enabled?

  speak 'It can take up to 15 minutes for the version to be available via Jamf and Self Service.'
rescue StandardError => e
  handle_processing_error e
end

#confirmed?(action) ⇒ Boolean

get confirmation for an action that requires it

Parameters:

  • action (String) —

    A short description of what we’re about to do, e.g. “Add version ‘1.2.3’ to title ‘cool-app’”

Returns:

  • (Boolean) —

    did we get confirmation?



1219
1220
1221
1222
1223
1224
1225
 
# File 'lib/xolo/admin/processing.rb', line 1219

def confirmed?(action)
  return true unless need_confirmation?

  puts "About to: #{action}"
  print 'Are you sure? (y/n): '
  STDIN.gets.chomp.downcase.start_with? 'y'
end

#delete_title ⇒ void

This method returns an undefined value.

Delete a title in Xolo



359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/xolo/admin/processing.rb', line 359

def delete_title
  return unless confirmed? "Delete title '#{cli_cmd.title}' and all its versions"

  response_data = Xolo::Admin::Title.delete cli_cmd.title, server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]

  speak "Title '#{cli_cmd.title}' has been deleted from Xolo."
rescue StandardError => e
  handle_processing_error e
end

#delete_version ⇒ void

This method returns an undefined value.

Delete a title in Xolo



648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/xolo/admin/processing.rb', line 648

def delete_version
  return unless confirmed? "Delete version '#{cli_cmd.version}' from title '#{cli_cmd.title}'"

  response_data = Xolo::Admin::Version.delete cli_cmd.title, cli_cmd.version, server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]
rescue StandardError => e
  handle_processing_error e
end

#deploy_version ⇒ void

This method returns an undefined value.

Deploy a version of a title in Xolo to one or more computers or computer groups



602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
 
# File 'lib/xolo/admin/processing.rb', line 602

def deploy_version
  return unless confirmed? "Deploy Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}' via MDM?"

  unless json? || quiet?
    puts "Deploying Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}' to computers: #{ARGV.join(', ')}"
    puts "Groups: #{opts_to_process[:groups].join(', ')}" unless opts_to_process[:groups].pix_empty?
  end

  response = Xolo::Admin::Version.deploy(
    cli_cmd.title,
    cli_cmd.version,
    server_cnx,
    groups: opts_to_process[:groups],
    computers: ARGV
  )

  return if quiet?

  if json?
    puts JSON.pretty_generate(response)
    return
  end

  puts "Results: Deployment of Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"
  puts '---------------------------------------------------------------'
  response[:removals].each do |removal|
    type = removal[:device] ? 'Computer' : 'Group'
    name = removal[:device] || removal[:group]
    puts "Removed #{type} '#{name}' from targets: #{removal[:reason]}"
  end

  response[:queuedCommands].each do |cmd|
    puts "Sent MDM deployment to #{cmd[:device]}, Command UUID: #{cmd[:commandUuid]}"
  end

  response[:errors].each do |err|
    puts "Error deploying to #{err[:device]}: #{err[:reason]}"
  end
rescue StandardError => e
  handle_processing_error e
end

#display_patch_report_summary(data, rpt_title) ⇒ void

This method returns an undefined value.

Show a summary of the patch report data

Parameters:

  • data (Array<Hash>) —

    the patch report data



918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
 
# File 'lib/xolo/admin/processing.rb', line 918

def display_patch_report_summary(data, rpt_title)
  version_counts = {}
  unknown = 0
  data.each do |d|
    if d[:version] == Xolo::UNKNOWN || d[:version].pix_empty?
      unknown += 1
      next
    end

    vers = Gem::Version.new(d[:version])
    version_counts[vers] ||= 0
    version_counts[vers] += 1
  end

  header_row = ['Version', 'Number of Installs']
  title = "Summary #{rpt_title}"

  summary_data = []
  summary_data << ['All Versions', data.size] unless rpt_title.include? 'Version'

  version_counts.keys.sort.reverse.each do |vers|
    summary_data << [vers, version_counts[vers]]
  end
  summary_data << ['Unknown', unknown] if unknown.positive? && !rpt_title.include?('Version')

  if json?
    puts JSON.pretty_generate(summary_data.to_h)
    return
  end

  show_text generate_report(summary_data, header_row: header_row, title: title)
end

#display_progress(url_path) ⇒ void

This method returns an undefined value.

Start displaying the progress of a long-running task on the server but only if we aren’t –quiet

Raises:



1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
 
# File 'lib/xolo/admin/processing.rb', line 1231

def display_progress(url_path)
  # in case it's nil
  return unless url_path

  # always make note of the path in the history
  add_progress_history_entry url_path
  return if quiet?

  # if any line of the contains 'ERROR' we can skip
  # any post-stream processing.
  @streaming_error = false

  streaming_cnx.get url_path

  raise Xolo::ServerError, 'There was an error while streaming the server progress.' if @streaming_error
end

#do_local_testing ⇒ Object

Just output lots of local things, for testing

Comment/uncomment as needed



1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
 
# File 'lib/xolo/admin/processing.rb', line 1278

def do_local_testing
  puts '-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+'
  puts Xolo::Admin::Title.release_to_all_allowed?(server_cnx)

  ###################
  # puts
  # puts '-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+'
  # puts 'GLOBAL OPTS:'
  # puts '----'
  # global_opts.to_h.each do |k, v|
  #   puts "..#{k} => #{v}"
  # end

  ###################
  # puts
  # puts "COMMAND: #{cli_cmd.command}"

  ###################
  # puts
  # puts "TITLE: #{cli_cmd.title}"

  ###################
  # puts
  # puts "VERSION: #{cli_cmd.version}"

  ###################
  # puts
  # puts 'CURRENT OPT VALUES:'
  # puts 'The values the object had before xadm started working on it.'
  # puts 'If the object is being added, these are the default or inherited values'
  # puts '----'
  # current_opt_values.to_h.each do |k, v|
  #   puts "..#{k} => #{v}"
  # end

  ###################
  # puts
  # puts 'COMMAND OPT VALUES:'
  # puts 'The command options collected by xadm, merged with the'
  # puts 'current values, to be applied to the object'
  # puts '----'
  # opts = walkthru? ? walkthru_cmd_opts : cli_cmd_opts
  # opts.to_h.each do |k, v|
  #   puts "..#{k} => #{v}"
  # end

  ###################
  # puts 'CookieJar:'
  # puts "  Session: #{Xolo::Admin::CookieJar.session_cookie}"
  # puts "  Expires: #{Xolo::Admin::CookieJar.session_expires}"

  ###################
  # puts 'getting /state'
  # resp = server_cnx.get '/state'
  # puts "#{resp.body}"

  # ###################
  # puts 'Listing currently known titles:'
  # all_titles = Xolo::Admin::Title.all_titles server_cnx
  # puts all_titles

  # # ###############
  # already_there = all_titles.include? cli_cmd.title
  # puts "all titles contains our title: #{already_there}"
  # if already_there
  #   puts 'deleting the title first'
  #   resp = Xolo::Admin::Title.delete cli_cmd.title, server_cnx
  #   puts "Delete Status: #{resp.status}"
  #   puts 'Delete Body:'
  #   puts resp.body
  # end

  # # ###################
  # process_method = Xolo::Admin::Options::COMMANDS[cli_cmd.command][:process_method]
  # puts
  # puts "Processing command opts using method: #{process_method}"
  # resp = send process_method if process_method
  # puts "Add Status: #{resp.status}"
  # puts 'Add Body:'
  # puts resp.body
  # puts

  # ##################
  # puts 're-fetching...'
  # title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  # puts "title class: #{title.class}"
  # puts 'title to_h:'
  # puts title.to_h
  # puts

  # ##################
  # puts 'updating...'
  # title.self_service = false
  # resp = title.update server_cnx
  # puts "Update Status: #{resp.status}"
  # puts 'Update Body:'
  # puts resp.body
  # puts

  ###################
  # puts 'running jamf_package_names'
  # puts jamf_package_names

  ###################
  # puts 'running ted_titles'
  # puts ted_titles

  ##################
  # puts
  # puts 'DONE'
end

#edit_title ⇒ void

This method returns an undefined value.

Edit/Update a title in Xolo



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/xolo/admin/processing.rb', line 277

def edit_title
  return unless confirmed? "Edit title '#{cli_cmd.title}'"

  opts_to_process.title = cli_cmd.title
  read_uninstall_script

  # if we were passed a new uninstall script, remove the uninstall ids
  if opts_to_process.uninstall_script && opts_to_process.uninstall_script != Xolo::ITEM_UPLOADED
    opts_to_process.uninstall_ids = []
  end

  # if we were passed uninstall ids, remove the uninstall script
  opts_to_process.uninstall_script = nil unless opts_to_process.uninstall_ids.pix_empty?

  title = Xolo::Admin::Title.new opts_to_process
  response_data = title.update server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]

  # Upload the ssvc icon, if any?
  upload_ssvc_icon title

  speak "Title '#{cli_cmd.title}' has been updated in Xolo."
rescue StandardError => e
  handle_processing_error e
end

#edit_version ⇒ void

This method returns an undefined value.

Edit/Update a version in Xolo



574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
 
# File 'lib/xolo/admin/processing.rb', line 574

def edit_version
  return unless confirmed? "Edit Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"

  opts_to_process.title = cli_cmd.title
  opts_to_process.version = cli_cmd.version
  vers = Xolo::Admin::Version.new opts_to_process

  response_data = vers.update server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]

  # Upload the pkg, if any?
  upload_pkg(vers)

  speak "Version '#{cli_cmd.version}' of title '#{cli_cmd.title}' has been updated in Xolo."
rescue StandardError => e
  handle_processing_error e
end

#freeze ⇒ void

This method returns an undefined value.

Freeze one or more computers for a title in Xolo



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/xolo/admin/processing.rb', line 380

def freeze
  conf_msg = <<~ENDMSG
    Freeze computers for title '#{cli_cmd.title}'.
    They will not update beyond their installed version,
    even it the title is not installed at all.
  ENDMSG

  return unless confirmed? conf_msg

  title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  response_data = title.freeze ARGV, cli_cmd_opts.users_given, server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  if json?
    puts JSON.pretty_generate(response_data)
    return
  end

  rpt_title = "Results for freezing Title '#{cli_cmd.title}'"
  header = %w[Computer Result]
  report = generate_report(response_data.to_a, header_row: header, title: rpt_title)
  show_text report
rescue StandardError => e
  handle_processing_error e
end

#handle_processing_error(err) ⇒ Object

Handle errors while processing xadm commands



1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
 
# File 'lib/xolo/admin/processing.rb', line 1251

def handle_processing_error(err)
  # puts "Err: #{err.class} #{err}"
  case err
  when Faraday::Error
    begin
      jsonerr = parse_json err.response_body
      errmsg = "#{jsonerr[:error]} [#{err.response_status}]"

    # if we got a faraday error, but it didn't contain
    # JSON, return just the error body, or the error itself
    rescue StandardError
      msg = err.response_body if err.respond_to?(:response_body)
      msg ||= err.to_s
      errmsg = "#{err.class.name.split('::').last}: #{msg}"
    end # begin
    raise err.class, errmsg

  else
    raise err
  end # case
end

#list_available_titles ⇒ void

This method returns an undefined value.

List Available titles for subscription



1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
 
# File 'lib/xolo/admin/processing.rb', line 1083

def list_available_titles
  data = jamf_available_titles.sort_by { |t| t[:app_name].downcase }
  data.map! do |t|
    {
      display_name: t[:app_name],
      publisher: t[:publisher],
      patch_source: t[:source_name],
      title_id: t[:name_id],
      current_version: t[:current_version],
      last_modified: t[:last_modified]
    }
  end

  if json?
    puts JSON.pretty_generate(data)
    return
  end

  title = 'Titles Available for Subscription'
  header = %w[DisplayName Publisher PatchSource TitleID]
  lines = data.map { |t| [t[:display_name], t[:publisher], t[:patch_source], t[:title_id]] }

  show_text generate_report(lines, header_row: header, title: title)
end

#list_categories ⇒ void

This method returns an undefined value.

List all the SSVC categories in jamf pro



1112
1113
1114
1115
1116
1117
1118
1119
 
# File 'lib/xolo/admin/processing.rb', line 1112

def list_categories
  if json?
    puts JSON.pretty_generate(jamf_category_names)
    return
  end

  list_in_cols 'Categories in Jamf Pro:', jamf_category_names.sort_by(&:downcase)
end

#list_frozen ⇒ void

This method returns an undefined value.

list the computers that are frozen for a title in Xolo



414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/xolo/admin/processing.rb', line 414

def list_frozen
  title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  frozen_computers = title.frozen server_cnx
  if debug?
    puts "DEBUG: response_data: #{frozen_computers}"
    puts
  end

  if json?
    puts JSON.pretty_generate(frozen_computers)
    return
  end

  if frozen_computers.empty?
    puts "# No computers are frozen for Title '#{cli_cmd.title}'"
    return
  end

  rpt_title = "Frozen Computers for Title '#{cli_cmd.title}'"
  header = %w[Computer User]
  report = generate_report(frozen_computers.to_a, header_row: header, title: rpt_title)
  show_text report
rescue StandardError => e
  handle_processing_error e
end

#list_groups ⇒ void

This method returns an undefined value.

List all the computer groups in jamf pro



1070
1071
1072
1073
1074
1075
1076
1077
 
# File 'lib/xolo/admin/processing.rb', line 1070

def list_groups
  if json?
    puts JSON.pretty_generate(jamf_computer_group_names)
    return
  end
  header = "Computer Groups in Jamf Pro.\n# Those starting with 'xolo-' are used internally by Xolo and not shown."
  list_in_cols header, jamf_computer_group_names.sort_by(&:downcase)
end

#list_titles ⇒ void

This method returns an undefined value.

List all titles in Xolo



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/xolo/admin/processing.rb', line 201

def list_titles
  titles = Xolo::Admin::Title.all_title_objects(server_cnx)

  if json?
    puts JSON.pretty_generate(titles.map(&:to_h))
    return
  end

  if titles.empty?
    puts "# No Titles in Xolo! Add one with 'xadm add-title <title>'"
    return
  end

  report_title = 'All titles in Xolo'
  header = %w[Title Created By SSvc? Released Latest]
  data = titles.map do |t|
    [
      t.title,
      t.creation_date.to_date,
      t.created_by,
      t.self_service || false,
      t.released_version,
      t.latest_version
    ]
  end
  data.sort_by! { |d| d[0].downcase } # sort by title

  show_text generate_report(data, header_row: header, title: report_title)
rescue StandardError => e
  handle_processing_error e
end

#list_versions ⇒ void

This method returns an undefined value.

List all versions of a title in Xolo



477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
 
# File 'lib/xolo/admin/processing.rb', line 477

def list_versions
  versions = Xolo::Admin::Version.all_version_objects(cli_cmd.title, server_cnx)

  if json?
    puts JSON.pretty_generate(versions.map(&:to_h))
    return
  end

  if versions.empty?
    puts "# No versions for Title '#{cli_cmd.title}'"
    return
  end

  report_title = "All versions of '#{cli_cmd.title}' in Xolo"
  header = %w[Vers Created By Released By Status]
  data = versions.sort_by(&:creation_date).map do |v|
    [
      v.version,
      v.creation_date.to_date,
      v.created_by,
      v.release_date&.to_date,
      v.released_by,
      v.status
    ]
  end
  show_text generate_report(data, header_row: header, title: report_title)
rescue StandardError => e
  handle_processing_error e
end

#opts_to_process ⇒ OpenStruct

Which opts to process, those from walkthru, or from the CLI?

Returns:

  • (OpenStruct) —

    the opts to process



62
63
64
 
# File 'lib/xolo/admin/processing.rb', line 62

def opts_to_process
  @opts_to_process ||= walkthru? ? walkthru_cmd_opts : cli_cmd_opts
end

#patch_report ⇒ void

This method returns an undefined value.

Show the patch report for a title or version in xolo



838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
 
# File 'lib/xolo/admin/processing.rb', line 838

def patch_report
  # since there is no actual version 'unknown'
  # we'll fetch all of them and extract the onese we want
  if cli_cmd.version == Xolo::UNKNOWN
    cli_cmd.version = nil
    report_unknown = true
  else
    report_unknown = false
  end

  if cli_cmd.version
    vers = Xolo::Admin::Version.fetch cli_cmd.title, cli_cmd.version, server_cnx
    data = vers.patch_report_data(server_cnx)
    rpt_title = "Patch Report for Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"
    all_versions = false
  else
    title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
    data = title.patch_report_data(server_cnx)
    data.select! { |d| d[:version] == Xolo::UNKNOWN } if report_unknown
    rpt_title = "Patch Report for Title '#{cli_cmd.title}'"
    all_versions = true
  end

  if data.empty?

    puts "# #{rpt_title}"
    puts '# No Data Found'

    return
  end

  if cli_cmd_opts.summary
    display_patch_report_summary(data, rpt_title)
    return
  end

  if json?
    puts JSON.pretty_generate(data)
    return
  end

  # NOTE: The order of things in this array must match
  # that in each array of the data, below
  header_row = %w[Computer User]
  header_row << 'Version' if all_versions
  header_row << 'LastContact'

  header_row << 'OS' if cli_cmd_opts.os
  header_row << 'Dept' if cli_cmd_opts.dept
  header_row << 'Building' if cli_cmd_opts.building
  header_row << 'Site' if cli_cmd_opts.site
  header_row << 'Frozen' if cli_cmd_opts.frozen
  header_row << 'JamfID' if cli_cmd_opts.id

  # See note above about the order of items in each sub-array
  data = data.map do |d|
    last_contact = Time.parse(d[:lastContactTime]).localtime.strftime('%F %T')
    comp_ary = [d[:computerName], d[:username]]
    comp_ary << d[:version] if all_versions
    comp_ary << last_contact

    comp_ary << d[:operatingSystemVersion] if cli_cmd_opts.os
    comp_ary << d[:departmentName] if cli_cmd_opts.dept
    comp_ary << d[:buildingName] if cli_cmd_opts.building
    comp_ary << d[:siteName] if cli_cmd_opts.site
    comp_ary << d[:frozen] if cli_cmd_opts.frozen
    comp_ary << d[:deviceId] if cli_cmd_opts.id
    comp_ary
  end

  show_text generate_report(data, header_row: header_row, title: rpt_title)
rescue StandardError => e
  handle_processing_error e
end

#read_uninstall_script ⇒ void

This method returns an undefined value.

if we have an uninstall script, read it in



313
314
315
316
317
 
# File 'lib/xolo/admin/processing.rb', line 313

def read_uninstall_script
  return unless opts_to_process.uninstall_script.to_s.start_with? '/'

  opts_to_process.uninstall_script = Pathname.new(opts_to_process.uninstall_script).read
end

#release_version ⇒ void

This method returns an undefined value.

Release a version of a title in Xolo



667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
 
# File 'lib/xolo/admin/processing.rb', line 667

def release_version
  return unless confirmed? "Release Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"

  opts_to_process.title = cli_cmd.title

  title = Xolo::Admin::Title.new opts_to_process
  response_data = title.release server_cnx, version: cli_cmd.version

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]
  speak "Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}' has been released."
rescue StandardError => e
  handle_processing_error e
end

#repair ⇒ void

This method returns an undefined value.

run a repair on a title or version



807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
 
# File 'lib/xolo/admin/processing.rb', line 807

def repair
  if cli_cmd.version
    conf_msg = "Repair Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"
  else
    conf_msg =  +"Repair Title '#{cli_cmd.title}'"
    conf_msg << ' and all of its versions' if opts_to_process[:versions]
  end

  return unless confirmed?(conf_msg)

  if cli_cmd.version
    vers = Xolo::Admin::Version.fetch cli_cmd.title, cli_cmd.version, server_cnx
    response_data = vers.repair server_cnx
  else
    title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
    response_data = title.repair server_cnx, versions: opts_to_process[:versions]
  end
  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  display_progress response_data[:progress_stream_url_path]
rescue StandardError => e
  handle_processing_error e
end

#rotate_server_logs ⇒ void

This method returns an undefined value.

rotate the server logs



1007
1008
1009
1010
1011
1012
1013
1014
 
# File 'lib/xolo/admin/processing.rb', line 1007

def rotate_server_logs
  return unless confirmed? 'Rotate the Xolo Server logs'

  result = server_cnx.post(SERVER_ROTATE_LOGS_ROUTE).body
  puts result[:result]
rescue StandardError => e
  handle_processing_error e
end

#run_test_route ⇒ void

This method returns an undefined value.

run the cleanup get the /test route to do whatever testing it does. during testing - this will return all kinds of things.



1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
 
# File 'lib/xolo/admin/processing.rb', line 1156

def run_test_route
  cli_cmd.command = 'test'
  if ARGV.include? '--quiet'
    global_opts.quiet = true
    puts "Set global_opts.quiet = true : #{global_opts.quiet}"
  end

   test: true
  resp = server_cnx.get('/default_min_os').body.first.to_s
  puts "RESPONSE:\n#{resp}"
  return unless resp[:progress_stream_url_path]

  puts
  if global_opts.quiet
    puts 'given --quiet, not showing progress'
  else
    puts 'Streaming progress:'
    display_progress resp[:progress_stream_url_path]
  end

  pkg_to_upload = Pathname.new '/path/to/some/file.pkg'
  puts "Uploading Test File #{pkg_to_upload.size} bytes... "
  upload_test_file(pkg_to_upload)

  puts 'All Done!'
rescue StandardError => e
  msg = e.respond_to?(:response_body) ? "#{e}\nRespBody: #{e.response_body}" : e.to_s
  puts "TEST ERROR: #{e.class}: #{msg}"
  puts e.backtrace
end

#save_client_code ⇒ void

This method returns an undefined value.

Save the xolo client tool from the gem’s data dir to a desired dir or /tmp



1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
 
# File 'lib/xolo/admin/processing.rb', line 1126

def save_client_code
  dest_dir = ARGV.shift
  dest_dir ||= '/tmp'
  dest_dir = Pathname.new(dest_dir).expand_path
  unless dest_dir.directory? && dest_dir.writable?
    raise ArgumentError,
          "Destination directory '#{dest_dir}' does not exist or is not writable"
  end

  this_file = Pathname.new(__FILE__).expand_path
  # This file is .../gems/xolo-admin-<vers>/lib/xolo/admin/processing.rb
  # so....
  # parent1 = admin
  # parent2 - xolo
  # parent3 = lib
  # parent4 = xolo-admin-<vers>
  # and we want xolo-admin-<vers>/data/client/xolo
  src = this_file.parent.parent.parent.parent + 'data/client/xolo'
  dest = dest_dir + 'xolo'

  src.pix_cp dest
  puts "Saved 'xolo' client tool to '#{dest}'"
end

#search_titles ⇒ void

This method returns an undefined value.

Search for a title in Xolo Looks for the search string (case insensitive) in these attributes:

- title
- display_name
- description
- publisher
- app_name
- app_bundle_id

will output the results showing those attributes

If json? is true, will output the results as a JSON array of hashes containing the full title object.

Parameters:

  • search_str (String) —

    the string to search for



101
102
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
136
137
138
139
 
# File 'lib/xolo/admin/processing.rb', line 101

def search_titles
  search_str = cli_cmd.title
  titles = Xolo::Admin::Title.all_title_objects(server_cnx)

  results = []
  titles.each do |t|
    next unless SEARCH_ATTRIBUTES.any? { |attr| t.send(attr).to_s =~ /#{search_str}/i }

    if json?
      results << t.to_h
      next
    end

    results << title_search_result_str(t, one_line: cli_cmd_opts.summary)
  end # titles.each

  # if json?, output it and we're done
  if json?
    puts JSON.pretty_generate(results)
    return
  end

  # no results?
  if results.empty?
    puts "# No titles matching '#{search_str}'"
    return
  end

  # results found
  puts "# All titles matching '#{search_str}'"
  if cli_cmd_opts.summary
    header = %w[Title Display Publisher Contact Versions]
    show_text generate_report(results, header_row: header, title: nil)
  else
    puts results.join("\n\n")
  end
rescue StandardError => e
  handle_processing_error e
end

#server_cleanup ⇒ void

This method returns an undefined value.

kick off server cleanup



981
982
983
984
985
986
987
988
 
# File 'lib/xolo/admin/processing.rb', line 981

def server_cleanup
  return unless confirmed? 'Run the Xolo Server cleanup process'

  result = server_cnx.post(SERVER_CLEANUP_ROUTE).body
  puts result[:result]
rescue StandardError => e
  handle_processing_error e
end

#server_status ⇒ void

This method returns an undefined value.

Show info about the server status



955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
 
# File 'lib/xolo/admin/processing.rb', line 955

def server_status
  route = cli_cmd_opts.extended ? "#{SERVER_STATUS_ROUTE}?extended=true" : SERVER_STATUS_ROUTE

  data = server_cnx.get(route).body

  if json?
    puts JSON.pretty_generate(data)
    return
  end

  require 'pp'

  header = +'# Xolo Server Status'
  header << ' (extended)' if cli_cmd_opts.extended
  puts header
  puts '##################################################'
  pp data
  nil
rescue StandardError => e
  handle_processing_error e
end

#set_server_log_level ⇒ void

This method returns an undefined value.

set the server log level



1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
 
# File 'lib/xolo/admin/processing.rb', line 1020

def set_server_log_level
  level = ARGV.shift&.downcase
  raise ArgumentError, 'No log level given' unless level

  unless LOG_LEVELS.include? level
    raise ArgumentError, "Invalid log level '#{level}', must be one of #{LOG_LEVELS.join(', ')}"
  end

  return unless confirmed? "Set the Xolo Server log level to '#{level}'?"

  payload = { level: level }
  result = server_cnx.post(SERVER_LOG_LEVEL_ROUTE, payload).body
  puts result[:result]
rescue StandardError => e
  handle_processing_error e
end

#show_changelog ⇒ void

This method returns an undefined value.

show the change log for a title



690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
 
# File 'lib/xolo/admin/processing.rb', line 690

def show_changelog
  title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  changelog = title.changelog(server_cnx)
  if json?
    puts JSON.pretty_generate(changelog)
    return
  end

  output = ["# Changelog for Title '#{cli_cmd.title}'"]
  output << '#' * (output.first.length + 5)
  changelog.each do |change|
    vers_or_title = change[:version] ? "version #{change[:version]}" : 'title'
    output << "#{Time.parse(change[:time]).strftime('%F %T')} #{change[:admin]}@#{change[:host]} changed #{vers_or_title}"

    if change[:msg]
      val = format_multiline_indent(change[:msg], indent: 7)
      output << "  msg: #{val}"

    else
      output << "  Attribute: #{change[:attrib]}"
      from_val = format_multiline_indent(change[:old], indent: 8)
      output << "  From: #{from_val}"
      to_val = format_multiline_indent(change[:new], indent: 6)
      output << "  To: #{to_val}"
    end
    output << nil
  end

  show_text output.join("\n")
rescue StandardError => e
  handle_processing_error e
end

#show_debug(msg) ⇒ Object

TODO: Use this everywhere in admin



77
78
79
80
81
 
# File 'lib/xolo/admin/processing.rb', line 77

def show_debug(msg)
  return unless debug?

  puts "DEBUG: #{msg}"
end

#show_info ⇒ void

This method returns an undefined value.

Show details about a title or version in xolo



727
728
729
 
# File 'lib/xolo/admin/processing.rb', line 727

def show_info
  cli_cmd.version ? show_version_info : show_title_info
end

#show_title_info ⇒ void

This method returns an undefined value.

Show details about a title in xolo



735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
 
# File 'lib/xolo/admin/processing.rb', line 735

def show_title_info
  title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx

  if json?
    puts title.to_json
    return
  end

  urls = title.gui_urls(server_cnx)

  puts "# Info for Title '#{cli_cmd.title}'"
  puts '###################################'

  Xolo::Admin::Title::ATTRIBUTES.each do |attr, deets|
    next if deets[:hide_from_info]
    # description is handled specially below
    next if attr == :description

    value = title.send attr
    value = value.join(Xolo::COMMA_JOIN) if value.is_a? Array
    puts "- #{deets[:label]}: #{value}".pix_word_wrap
  end
  puts '- Description:'
  title.description.lines.each { |line| puts "  #{line.chomp}" } unless title.description.pix_empty?

  puts '#'
  puts '# Web App URLs'
  puts '###################################'
  urls.each { |pagename, url| puts "#{pagename}: #{url}" }
rescue StandardError => e
  handle_processing_error e
end

#show_version_info ⇒ void

This method returns an undefined value.

Show details about a title in xolo



772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
 
# File 'lib/xolo/admin/processing.rb', line 772

def show_version_info
  vers = Xolo::Admin::Version.fetch cli_cmd.title, cli_cmd.version, server_cnx

  if json?
    puts vers.to_json
    return
  end

  urls = vers.gui_urls(server_cnx)

  puts "# Info for Version #{cli_cmd.version} of Title '#{cli_cmd.title}'"
  puts '##################################################'

  Xolo::Admin::Version::ATTRIBUTES.each do |attr, deets|
    next if deets[:hide_from_info]

    value = vers.send attr
    value = value.join(Xolo::COMMA_JOIN) if value.is_a? Array
    puts "- #{deets[:label]}: #{value}".pix_word_wrap
  end

  puts '#'
  puts '# Web App URLs'
  puts '###################################'
  urls.each { |pagename, url| puts "#{pagename}: #{url}" }
  # rescue Faraday::ResourceNotFound
  # puts "No Such Version '#{cli_cmd.version}' of Title '#{cli_cmd.title}'"
rescue StandardError => e
  handle_processing_error e
end

#shutdown_server ⇒ void

This method returns an undefined value.

shutdown the server



1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
 
# File 'lib/xolo/admin/processing.rb', line 1041

def shutdown_server
  return unless confirmed? 'Shutdown the Xolo Server'

  restart = cli_cmd_opts.restart
  action = restart ? 'Restart' : 'Shutdown'
  payload = { restart: restart }

  result = server_cnx.post(SERVER_SHUTDOWN_ROUTE, payload).body
  puts "result[:result] = #{result[:result]}"

  if debug?
    puts "DEBUG: response_data: #{result}"
    puts
  end

  display_progress result[:progress_stream_url_path]

  puts "#{action} complete"
rescue Faraday::ConnectionFailed
  puts "#{action} complete"
rescue StandardError => e
  puts "Error Class: #{e.class}"
  handle_processing_error e
end

#speak(msg) ⇒ void

This method returns an undefined value.

puts a string to stdout, unless quiet? is true

Parameters:

  • msg (String) —

    the string to puts



71
72
73
 
# File 'lib/xolo/admin/processing.rb', line 71

def speak(msg)
  puts msg unless quiet?
end

#thaw ⇒ void

This method returns an undefined value.

Thaw one or more computers for a title in Xolo



444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
 
# File 'lib/xolo/admin/processing.rb', line 444

def thaw
  conf_msg = <<~ENDMSG
    Thaw computers for title '#{cli_cmd.title}'.
    They will again be able to update beyond their installed version.
  ENDMSG

  return unless confirmed? conf_msg

  title = Xolo::Admin::Title.fetch cli_cmd.title, server_cnx
  response_data = title.thaw ARGV, cli_cmd_opts.users_given, server_cnx

  if debug?
    puts "DEBUG: response_data: #{response_data}"
    puts
  end

  if json?
    puts JSON.pretty_generate(response_data)
    return
  end

  rpt_title = "Results for thawing Title '#{cli_cmd.title}'"
  header = %w[Computer Result]
  report = generate_report(response_data.to_a, header_row: header, title: rpt_title)
  show_text report
rescue StandardError => e
  handle_processing_error e
end

#title_search_result_str(title, one_line: false) ⇒ String

From a title, get a String for use in a search report, either multiline or single line

Parameters:

  • title (Xolo::Admin::Title) —

    the title

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

    whether to use single line format

Returns:

  • (String) —

    the string to display for the search result



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/xolo/admin/processing.rb', line 147

def title_search_result_str(title, one_line: false)
  versions = versions_str(title)
  if one_line
    [title.title, title.display_name, title.publisher, title.contact_email, versions]
  else
    titleout = +'#---------------------------------------'
    titleout << "\nTitle: #{title.title}"
    titleout << "\nDisplay Name: #{title.display_name}"
    titleout << "\nPublisher: #{title.publisher}"
    titleout << "\nApp: #{title.app_name}\nBundleID: #{title.app_bundle_id}" if title.app_name
    titleout << "\nVersions: #{versions}"
    titleout << "\nDescription:"
    titleout << "\n#{title.description}"
    titleout
  end # json?
end

#update_client_data ⇒ void

This method returns an undefined value.

force update the client data pkg



994
995
996
997
998
999
1000
1001
 
# File 'lib/xolo/admin/processing.rb', line 994

def update_client_data
  return unless confirmed? 'Force update of the client data package'

  result = server_cnx.post(SERVER_UPDATE_CLIENT_DATA_ROUTE).body
  puts result[:result]
rescue StandardError => e
  handle_processing_error e
end

#update_config ⇒ void

This method returns an undefined value.

update the adm config file using the values from ‘xadm config’ which is a walkthru



187
188
189
190
191
192
193
194
195
 
# File 'lib/xolo/admin/processing.rb', line 187

def update_config
  debug? && puts("DEBUG: opts_to_process: #{opts_to_process}")

  # Xolo::Admin::Configuration::KEYS.each_key do |key|
  #   config.send "#{key}=", opts_to_process[key]
  # end

  config.save_to_file data: opts_to_process.to_h
end

#upload_pkg(version) ⇒ void

This method returns an undefined value.

Upload a pkg in a thread with indeterminate progress feedback (i.e. ‘…Upload in progress’ ) Determining actual progress numbers would require either a locol tool to meter the IO or a server capable of sending it as a progress stream, neither of which is straightforward.

Parameters:

  • version (Xolo::Admin::Version) —

    the version for which we are uploading the pkg. It must have a ‘pkg_to_upload’ that is a pathname to an existing file



548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
 
# File 'lib/xolo/admin/processing.rb', line 548

def upload_pkg(version)
  return unless version.pkg_to_upload.is_a? Pathname

  # TODO: deal with autopkg pkgs, should we be able to do this?

  speak "Uploading #{version.pkg_to_upload.basename}, #{version.pkg_to_upload.pix_humanize_size} to Xolo"
  # start the upload in a thread
  upload_thr = Thread.new { version.upload_pkg(upload_cnx) }

  # check the thread every second, but only update the terminal every 10 secs
  count = 0
  while upload_thr.alive?

    speak "... #{Time.now.strftime '%F %T'} Upload in progress" if (count % 10).zero?
    sleep 1
    count += 1
  end
  speak 'Upload complete, Final upload to distribution points will happen soon.'
rescue StandardError => e
  handle_processing_error e
end

#upload_ssvc_icon(title) ⇒ void

This method returns an undefined value.

Upload the ssvc icon, if any? TODO: progress feedback? Icons should never be very large, so prob. not, to start with

Parameters:



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'lib/xolo/admin/processing.rb', line 326

def upload_ssvc_icon(title)
  return unless title.self_service_icon.is_a? Pathname

  speak 'Pausing to let jamf server catch up before uploading self-service icon...'
  sleep 30
  speak "Uploading self-service icon #{title.self_service_icon.basename}, #{title.self_service_icon.pix_humanize_size} to Xolo."

  wait_for_title_timer = 0
  begin
    title.upload_self_service_icon(upload_cnx)
  rescue Xolo::ConnectionError => e
    speak "Error uploading self-service icon: #{e.message}, trying again in 5 secs"
    # If we get a 404, it might be because the title isn't fully created yet.
    # Wait a bit and try again, up to a certain number of seconds.
    if wait_for_title_timer < 90
      sleep 5
      wait_for_title_timer += 5
      retry
    else
      msg = "Failed to upload icon for Title '#{title}' after retrying for #{wait_for_title_timer} seconds."
      raise Xolo::NoSuchItemError, msg
    end # if
  end # begin

  speak 'Self-service icon uploaded. Will be added to Self Service policies as needed'
rescue StandardError => e
  handle_processing_error e
end

#upload_test_file(pkg_to_upload) ⇒ void

This method returns an undefined value.

Upload a file to the test upload route

Parameters:

  • pkg_to_upload (Pathname) —

    a local file to upload



1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
 
# File 'lib/xolo/admin/processing.rb', line 1194

def upload_test_file(pkg_to_upload)
  route = '/upload/test'

  upfile = Faraday::UploadIO.new(
    pkg_to_upload.to_s,
    'application/octet-stream',
    pkg_to_upload.basename.to_s
  )

  content = { file: upfile }
  # upload the file in a thread
  Thread.new { upload_cnx.post(route) { |req| req.body = content } }

  # when the server starts the upload, it notes the new
  # streaming url for our session[:xolo_id], which we can then fetch and
  # start displaying the progress
  display_progress response_data[:progress_stream_url_path]
end

#versions_str(title) ⇒ String

From a title, get a String with current versions of a title, comma separated with the current released version marked

Parameters:

Returns:

  • (String) —

    the versions string



169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/xolo/admin/processing.rb', line 169

def versions_str(title)
  versions = []
  title.version_order.each do |v|
    versions <<
      if v.to_s == title.released_version.to_s
        "#{v} (released)"
      else
        v
      end
  end
  versions.join(', ')
end