Helping jamfHelper

Helping jamfHelper

helping-jamfhelper

General Overview


jamfHelper is a nifty little utility included with Jamf’s Casper Suite that can be used to display information, get user input, or even trigger custom events all from the command line or your own custom scripts.

There are a number of useful options that can be used to customize the look, feel and functionality of the jamfHelper window. From heads-up notifications, to user selected delay options, to locking the screen, I will do my best to demonstrate some of these uses as well as how each of jamfHelper’s options work.

The jamfHelper executable can be found inside of the jamfHelper.app at:

/Library/Application Support/JAMF/bin/jamfHelper.app/Contents/MacOS/jamfHelper

This executable can be called directly from the command line making it ideal for use in custom scripts. Calling it with the
-help flag will print out a brief help message, but my goal here is to give a more complete description of how to use jamfHelper than is available in its help documentation.

Window Types


At its core jamfHelper is designed to display information to the user and it does this by opening a display window. It has three distinct types of windows: the Utility window, the Heads-Up Display window, and the Full Screen window. There are a few similarities between each type of window, but its their differences that make jamfHelper such a unique and viable tool. Because jamfHelper’s only required option is -windowType, it makes the most sense to cover each type of window and it capabilities.

Utility Windows

The Utility window is a highly customizable window type and can be used to produce dialog windows that look professional.

utility windowType

UTILITY – Making things look official.

Utility windows can be customized with buttons, a dropdown menu, timeout features, and more. It is displayed with:
-windowType utility

Full Screen Windows

By far the most unique of the three window types. The Full Screen window will cover the entire screen and block all user input, making very useful if you need to keep a user from interrupting a critical update.

fullscreen windowType

FULL SCREENGetting things done behind the scenes.

⚠ WARNING ⚠: Once this mode is activated, it will either have to be terminated via a remote command, put into the background and killed later, or via proper threading. ( ^C will not save you, and you WILL have to reboot your computer).

Fullscreen windows are created by specifying:  -windowType fs

Heads-Up Display Windows

The most versatile of all three window types, with a darker look and feel, the HUD window can be configured in every way a Utility window can (and then some).

hud-example

HUD – For everything else.

The HUD window is also the only window that has a close button, which makes it ideal for notification messages that don’t require any user input. They are displayed by specifying:  -windowType hud

The Basics


There are a couple key options in jamfHelper that you will find yourself using in almost every instance:

-title, -heading, -description, -icon, -button1 and -button2.

jamfHelper example

Each option labeled as itself, and a Casper Suite icon.

These particular options are pretty straight forward, and may be all you need to introduce this UI into your scripts. Taken directly from -help:

The example above would be called from terminal as:

/Library/Application\ Support/JAMF/bin/jamfHelper.app/Contents/MacOS/jamfHelper -windowType utility -icon /Library/Application\ Support/JAMF/bin/Management\ Action.app/Contents/Resources/Self\ Service.icns -title "Title" -heading "Heading" -description "Description" -button1 "button1" -button2 "button2"

As you can see, jamfHelper commands tend to get pretty verbose, pretty quickly. The main perpetrators being the path to the executable itself, and the absolute path to the icon. I’ll be truncating these two items for future examples.

Button Basics


Buttons are the only method for user interaction with jamfHelper windows. If pressed,  -button1 will return 0, and
-button2 will return 2 (except when -showDelayOptions is also specified, but we’ll get to that later).

By capturing jamfHelper’s output, you can dictate what your scripts will do. For example:

-button1 will always appear on the right, and  -button2 on the left (even if  -button1 isn’t specified)

That’s pretty much all to it. You could start using jamfHelper with these options alone and it would be a useful tool. However, there’s a little more to explore.

Advanced Usage


Now, if you’ve ever used jamfHelper before, you’ll know that it has some… erhm… quirks to it. Everything I’ve described thus far has been pretty intuitive, but there are also some oddities about jamfHelper that can make it frustrating to use at times. The general way jamfHelper operates can make it somewhat difficult to determine what each flag does. Sometimes, you can specify a flag that won’t appear to do anything at all, or maybe, you’ll use a flag that should work but doesn’t.  The rest of this post was meant to clear up some of these “gotchas” as much as I was able.

jamfHelper does not complain or exit if given incorrect flags or improper arguments. It simply works with what you give it and tries to do its best with what it has, but (in my opinion) this lack of feedback makes it somewhat difficult to isolate bugs or improper use. For example:

 

selection-example

Now, if we were to change the command slightly, we get:

selection-example-bug

Wait… Where’s the dropdown menu!?

The dropdown menu that -showDelayOptions is supposed to display is missing entirely. Which is odd, because the last command we ran is almost identical to the first one.

What actually happened is that  "-1, 0, 300, 86400" was interpreted by jamfHelper as an option, causing -showDelayOptions to be called without any parameters and thusly seen as a malformed option. Instead of quitting immediately with an error message, jamfHelper goes on with what it has and displays the description text and the button.

This is not the only way this can happen either, as not every option works with every -windowType, and some options are reliant on the use of others (e.g.  -countdown requires -timeout). If an option is not meant to work with the specified -windowType, is dependent on additional options, or an option is given incorrect parameters, it will be ignored entirely by jamfHelper without any feedback whatsoever.

Full Screen Windows


Full Screen windows are, by far, the most limiting window. They cannot have buttons or dropdown menus, and even  -timeout doesn’t work.

The only options available with -windowType fs are: -icon, -heading, -description, and -fullScreenIcon.

⚠ WARNING ⚠: Full Screen Windows will lock you out of your computer unless used properly. If you REALLY need to see how it works, use this script:

-fullScreenIcon requires -icon. It also disables  -heading and  -description.

Now if you were to use a general icon with -fullScreenIcon, all you would see is a big black screen with a giant icon. This option is best used when you have very specific formatting needs or more elements than are allowed in a jamfHelper window. You can make a custom image to display whatever information you want, and then block out the entire screen.

Display Text


Some of this was covered above, but for the sake of completeness I have included it here as well with some additional information.

All text flags appear to accept any form of printable characters including unicode (I have not tried control characters besides newline).

There doesn’t appear to be any character limit for this string, but will trail off with an ellipsis if the title is too long for the window.

Also doesn’t appear to have any character limits, and jamfHelper will resize the window (as well as it can) to accommodate the entire heading.

While -title and -heading behave very uniformly, I have noticed some odd things about -description. Because jamfHelper automatically resizes the window based upon various factors ( -iconSize, -heading, etc.) text specified in with -description can display haphazardly at times.

I have noticed scenarios where a few words are left off the end, or a sentence is cut off after a newline. Although, this can usually be fixed by padding -heading  with a few spaces or adding 5-10 pixels to -iconSize. jamfHelper does, however, appear to be consistant with -description, meaning, if it appears correctly given a static set of options, it will always appear the same way across any set of machines or times it is executed. So check your output, tweak a few things ( -iconSize is my go-to) and if you are happy with the way it appears, you can be confident that it will continue to appear uniformly.

NOTE: -description could also be considered a “required” argument due to the fact that there is a weird bug where if -description is omitted or left blank, it will default to the last -description used by the last instance of jamfHelper.

Text Alignment


These arguments are meant for aligning text as desired. They are pretty straight forward given that you also specify -description, -heading, and -countdown.

NOTE: -countdown is dependent on  -timeout, making  -alignCountdown dependent on both.

Icons


Although they aren’t necessary, icons are a nice addition to any dialog window. jamfHelper supports a number of image types.

As long as the path to an image is valid, jamfHelper can typically use that image as an icon. Icons work with every  -windowType. I tested a number of image types and jamfHelper displayed almost all of them. The image types I tested were:

Supported:         ICNS, PNG, JPG/JPEG, TIFF, PDF, and GIF (although GIFs are not animated).

Unsupported:    SVG

This isn’t an exhaustive list, and there may be additional supported/unsupported image formats.

pixels must be in the form of an integer, (e.g. -iconSize 120) and can be no smaller than 15 (The system will throw a CALayerInvalidGeometry exception). I’ve had issues where -iconSize will modify the size of the jamfHelper window, but not the image itself. Because jamfHelper automatically resizes the window based on several factors, I have used  -iconSize to fix odd formatting bugs with  -description.

Dropdown Menu


-showDelayOptions adds a dropdown menu to the jamfHelper window that will give a user the option to select an amount of time.

Arguments supplied to this flag should be in the form of seconds and jamfHelper will automatically convert them to a human readable format (i.e. 300 becomes “5 minutes”, 3600 becomes “1 hour”, etc.) The selection is then pre-appended (in seconds) to the return value of the button pressed (without delineation).

The way buttons work is slightly changed as well. Where -button1 would normally return 0, now it returns XX1 (where XX is the user selection in seconds). The same notation goes for -button2, which returns  XX2 .

So assuming jamfHelper was called with the following options:

The result would be:

showdelayoptions-window

Depending on the selection, and which button was pressed, the return values would be:

showdelayoptions

The last example 214748364 is actually the upper limit of -showDelayOptions, any number that is larger will return unpredictably. The numbers given do not have to be in any specific order, but it’s typically good form to go from least to greatest. If text is given (instead of a number) -showDelayOptions replaces it with  0 (a.k.a “Start now”). Specifying negative numbers will display properly in the dropdown menu, but will not return a predictable value.

Default Buttons


jamfHelper is also able to map the return (enter) and escape (esc) keys to certain buttons. These options do not affect -windowType fs.

This works as expected and in the case of both the hud and utility  -windowType. The default button will be highlighted.

By default, -windowType hud will respond to the esc key as a shortcut to closing the window (returning code 239-lockHUD can be used to disable this functionality. -cancelButton overwrites this default.

Both -defaultButton and -cancelButton are dependent on -button1 and/or  -button2.

Miscellaneous


NOTE: -countdown can only be used in conjunction with -timeout.

-lockHUD can only be used with -windowType hud. Apart from removing the close button, it also removes the esc key functionality (unless -cancelButton is specified).

Speculation


Does nothing as far as I am able to tell.

If used, jamfHelper immediately exits with  3 … That’s it.

This option is very confusing as it seems to immediately (and only) kill the instance of jamfHelper that uses it. As far as I was able to tell, it seems to leave all other instances of jamfHelper alone. Because you are immediately killing the jamfHelper window that uses this flag, it essentially makes the flag as useful as not calling jamfHelper at all.

It is pretty obvious that these two flags are tied to each other in some way, but how they are meant to work is a mystery to me.

I originally assumed that you could use -startlaunchd to start jamfHelper in the background, and continue on with a script. Then afterwards, you could use -kill to reap the original jamfHelper window. I tested this for the better portion of 2 days before I finally gave up and called JAMF support, but they were not able to provide any answers or additional documentation.

Real World Examples


What good is all of this information if you can’t think of any way to use it Well my friend, let me share with you the way I originally used jamfHelper. Cool thing about jamfHelper windows is that they can work on top of the login window. If you were to make your own LaunchAgent, maybe something to the tune of:

You could essentially block a user from login as long as /path/to/some/triggerfile existed. If you replace the icon with something institutionally relevant, have a script touch that triggerfile at startup, and then delete the file after finishing. You have one a very viable use of jamfHelper.

Here at the Marriott Library, we used jamfHelper to notify consultants about maintenance errors on checkout laptops for students before the laptop was checked out. So if a maintenance error occurred the login window would appear as:

loginwindow

This would give a consultant the ability to quickly identify an issue and choose another laptop to checkout. Beyond just the notification, we wanted to give consultants the ability to re-run maintenance right from the jamfHelper window. This was easy, because we could just add a button! However, there were some complications. Because our maintenance process requires a reliable connection to the network, and can take a very long time to run, we needed some additional functionality to test that maintenance could be run properly.

We created some functions that could be used to test if the power adapter was connected and if the system was currently using an ethernet connection.

Because we could add whatever text we wanted (including unicode), we came up with a script that would dynamically create a jamfHelper window as the system power or ethernet connection changed. When “Connect” was pressed, two more windows were spawned in place of the one above:

waiting-for-power

This window stays open until a power adapter is plugged in.

First the system would wait for power, then for an ethernet based connection. Each window would stay open as long the service was not detected. If the user pressed cancel, it would cycle back to the original window with the “Connect” button.

waiting-for-ethernet

This window stays open until a Thunderbolt Ethernet connection is detected.

Once both system states were detected, the user was then finally presented the original window but with a different option:

With this window, a user could run maintenance right from the login window.

This would then kick off our maintenance program. The LaunchAgent used to start the script was tied to the login window and to a specific error log that was only created if maintenance failed. If a user logged in, the jamfHelper windows would disappear, and the dialog windows would not display if maintenance succeeded. This script has allowed us to rely on our consultants to fix a multitude of common issues, saving time for all of us, all while keeping our laptop checkouts moving smoothly.

I included the basic forms of the code below.

Presentation


Here is a presentation from the University of Utah’s October MacAdmin Meeting:

helping-jamfhelper-presentation

 

More


Here’s a decently sanitized version of the script I was describing above, I had to change some of the paths and supporting files so that it would run on any computer with jamfHelper installed, but you can go through and modify what you need to if you want to play around with it.

 

6 Comments
  • Ross Derewianko (@PingRD)
    Posted at 16:51h, 10 October Reply

    Awesome writeup! The one other thing thats slowly been worked on is, Someone Over at JAMF is building a gui to build your helper.
    https://github.com/JAMFSupport/JAMF-Helper-GUI

    • Sam Forester
      Posted at 17:48h, 10 October Reply

      Thanks, I’m glad you enjoyed it. I’ll take a look at the gui builder. Thanks for the link.

  • uraqt
    Posted at 01:38h, 24 March Reply

    Hi,

    Could you share your jamfHelper scripts in github? I am trying to get a jamfHelper to show the jamf log live.

    Thanks
    C

    • Richard Glaser
      Posted at 20:59h, 28 March Reply

      Hello Chris:

      Thanks for the comment. We will work on sanitizing our jamfHelper scripts and posting either to our github repository, this blog post or both.

    • Sam Forester
      Posted at 22:03h, 31 March Reply

      Hi Chris,

      I added a version of the script to the post, play around with it and tell me what you think.

  • QRAQT
    Posted at 22:31h, 29 March Reply

    Thank you !!!

Leave a Reply