Module: Jamf::Client::JamfHelper::ClassMethods

Defined in:
lib/jamf/client/jamf_helper.rb

Overview

class Methods

Instance Method Summary collapse

Instance Method Details

#jamf_helper(window_type = :hud, **opts) ⇒ Integer

Note:

the -startlaunchd and -kill options are not available in this implementation, since they don’t work at the moment (casper 9.4). -startlaunchd seems to be required to NOT use launchd, and when it’s ommited, an error is generated about the launchd plist permissions being incorrect.

A wrapper for the jamfHelper command, which can display a window on the client machine.

The first parameter must be a symbol defining what kind of window to display. The options are

  • :hud - creates an Apple “Heads Up Display” style window

  • :utility or :util - creates an Apple “Utility” style window

  • :fs or :full_screen or :fullscreen - creates a full screen window that restricts all user input WARNING: Remote access must be used to unlock machines in this mode

The remaining options Hash can contain any of the options listed. See below for descriptions.

The value returned is the Integer exitstatus/stdout (both are the same) of the jamfHelper command. The meanings of those integers are:

  • 0 - Button 1 was clicked

  • 1 - The Jamf Helper was unable to launch

  • 2 - Button 2 was clicked

  • 3 - Process was started as a launchd task

  • XX1 - Button 1 was clicked with a value of XX seconds selected in the drop-down

  • XX2 - Button 2 was clicked with a value of XX seconds selected in the drop-down

  • 239 - The exit button was clicked

  • 240 - The “ProductVersion” in sw_vers did not return 10.5.X, 10.6.X or 10.7.X

  • 243 - The window timed-out with no buttons on the screen

  • 250 - Bad “-windowType”

  • 254 - Cancel button was select with delay option present

  • 255 - No “-windowType”

If the :abandon_process option is given, the integer returned is the Process ID of the abondoned process running jamfHelper.

See also /Library/Application\ Support/JAMF/bin/jamfHelper.app/Contents/MacOS/jamfHelper -help

Parameters:

  • window_type (Symbol) (defaults to: :hud) —

    The type of window to display

  • opts (Hash) —

    the options for the window

Options Hash (**opts):

  • :window_position (Symbol, nil) —

    one of [ nil, :ul, :ll. :ur, :lr ] Positions window in the upper right, upper left, lower right or lower left of the user’s screen If no input is given, the window defaults to the center of the screen

  • :title (String) —

    Sets the window’s title to the specified string

  • :heading (String) —

    Sets the heading of the window to the specified string

  • :align_heading (Symbol) —

    one of [:right, :left, :center, :justified, :natural] Aligns the heading to the specified alignment

  • :description (String) —

    Sets the main contents of the window to the specified string

  • :align_description (Symbol) —

    one of [:right, :left, :center, :justified, :natural] Aligns the description to the specified alignment

  • :icon (String, Pathname) —

    Sets the windows image field to the image located at the specified path

  • :icon_size (Integer) —

    Changes the image frame to the specified pixel size

  • :full_screen_icon (any value) —

    Scales the “icon” to the full size of the window. Note: Only available in full screen mode

  • :button1 (String) —

    Creates a button with the specified label

  • :button2 (String) —

    Creates a second button with the specified label

  • :default_button (Integer) —

    either 1 or 2 Sets the default button of the window to the specified button. The Default Button will respond to “return”

  • :cancel_button (Integer) —

    either 1 or 2 Sets the cancel button of the window to the specified button. The Cancel Button will respond to “escape”

  • :timeout (Integer) —

    Causes the window to timeout after the specified amount of seconds Note: The timeout will cause the default button, button 1 or button 2 to be selected (in that order)

  • :show_delay_options (String, Array<Integer>) —

    A String of comma-separated Integers, or an Array of Integers. Enables the “Delay Options Mode”. The window will display a dropdown with the values passed through the string

  • :countdown (any value) —

    Displays a string notifying the user when the window will time out

  • :align_countdown (Symbol) —

    one of [:right, :left, :center, :justified, :natural] Aligns the countdown to the specified alignment

  • :lock_hud (Boolean) —

    Removes the ability to exit the HUD by selecting the close button

  • :abandon_process (Boolean) —

    Abandon the jamfHelper process so that your code can exit. This is mostly used so that a policy can finish while a dialog is waiting (possibly forever) for user response. When true, the returned value is the process id of the abandoned jamfHelper process.

  • :output_file (String, Pathname) —

    Save the output of jamfHelper (the exit code) into this file. This is useful when using abandon_process. The output file can be examined later to see what happened. If this option is not provided, no output is saved.

  • :arg_string (String) —

    The jamfHelper commandline args as a single String, the way you’d specify them in a shell. This is appended to any Ruby options provided when calling the method. So calling:

    Jamf::Client.jamf_helper :hud, title: 'This is a title', arg_string: '-heading "this is a heading"'

    will run

    jamfHelper -windowType hud -title 'this is a title' -heading "this is a heading"

    When using this, be careful not to specify the windowType, since it’s generated by the first, required, parameter of this method.

Returns:

  • (Integer) —

    the exit status of the jamfHelper command. See above.

Raises:



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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
232
233
234
235
236
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
272
273
274
275
276
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
308
 
# File 'lib/jamf/client/jamf_helper.rb', line 186

def jamf_helper(window_type = :hud, **opts)
  raise Jamf::UnmanagedError, 'The jamfHelper app is not installed properly on this computer.' unless JAMF_HELPER.executable?

  unless JAMF_HELPER_WINDOW_TYPES.include? window_type
    raise Jamf::InvalidDataError, "The first parameter must be a window type, one of :#{JAMF_HELPER_WINDOW_TYPES.keys.join(', :')}."
  end

  # start building the arg array

  args = ['-startlaunchd', '-windowType', JAMF_HELPER_WINDOW_TYPES[window_type]]

  opts.keys.each do |opt|
    case opt
    when :window_position
      raise Jamf::InvalidDataError, ":window_position must be one of :#{JAMF_HELPER_WINDOW_POSITIONS.join(', :')}." unless \
        JAMF_HELPER_WINDOW_POSITIONS.include? opts[opt].to_sym

      args << '-windowPosition'
      args << opts[opt].to_s

    when :title
      args << '-title'
      args << opts[opt].to_s

    when :heading
      args << '-heading'
      args << opts[opt].to_s

    when :align_heading
      raise Jamf::InvalidDataError, ":align_heading must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless \
        JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym

      args << '-alignHeading'
      args << opts[opt].to_s

    when :description
      args << '-description'
      args << opts[opt].to_s

    when :align_description
      raise Jamf::InvalidDataError, ":align_description must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless \
        JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym

      args << '-alignDescription'
      args << opts[opt].to_s

    when :icon
      args << '-icon'
      args << opts[opt].to_s

    when :icon_size
      args << '-iconSize'
      args << opts[opt].to_s

    when :full_screen_icon
      args << '-fullScreenIcon'

    when :button1
      args << '-button1'
      args << opts[opt].to_s

    when :button2
      args << '-button2'
      args << opts[opt].to_s

    when :default_button
      raise Jamf::InvalidDataError, ":default_button must be one of #{JAMF_HELPER_BUTTONS.join(', ')}." unless \
        JAMF_HELPER_BUTTONS.include? opts[opt]

      args << '-defaultButton'
      args << opts[opt].to_s

    when :cancel_button
      raise Jamf::InvalidDataError, ":cancel_button must be one of #{JAMF_HELPER_BUTTONS.join(', ')}." unless \
        JAMF_HELPER_BUTTONS.include? opts[opt]

      args << '-cancelButton'
      args << opts[opt].to_s

    when :timeout
      args << '-timeout'
      args << opts[opt].to_s

    when :show_delay_options
      args << '-showDelayOptions'
      args << JSS.to_s_and_a(opts[opt])[:arrayform].join(', ')

    when :countdown
      args << '-countdown' if opts[opt]

    when :align_countdown
      raise Jamf::InvalidDataError, ":align_countdown must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless \
        JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym

      args << '-alignCountdown'
      args << opts[opt].to_s

    when :lock_hud
      args << '-lockHUD' if opts[opt]

    end # case opt
  end # each do opt

  cmd = Shellwords.escape JAMF_HELPER.to_s
  args.each { |arg| cmd << " #{Shellwords.escape arg}" }
  cmd << " #{opts[:arg_string]}" if opts[:arg_string]
  cmd << " > #{Shellwords.escape opts[:output_file]}" if opts[:output_file]

  if opts[:abandon_process]
    pid = Process.fork
    if pid.nil?
      # In child
      exec cmd
    else
      # In parent
      Process.detach(pid)
      pid
    end
  else
    system cmd
    $CHILD_STATUS.exitstatus
  end
end