Casper-HC: the friendly HipChat plugin

Hello all.

The last time I posted on this blog I was still working in the IT department at Jamf. I happen to still be working at Jamf, but after five years of watching the IT team grow up I was approached with an opportunity to make a difference within our Cloud & Delivery team (Jamf Cloud) as a System Administrator.  You’ll likely hear more about that as time goes on.

Now, I wouldn’t have taken any job that didn’t involve me writing lots, and lots, of Python code, and as it so happens I’m currently in the middle of building an API using my all-time favorite microframework: Flask.

In the month leading up to my transition I tried to burn through code-completion (in my book that means the application was in a fully usable state if not feature complete) on several web apps that I had rolling. I’ve been given permission to push all of these to the Jamf IT GitHub page so you’ll see a series of blog posts detailing each of them.

Those projects include:

  • Casper-HC
    (This post)
  • QuickDNS 2
    A front-end to a DNS (bind9) that allows the creation of randomized and chosen names and managing those names using a RESTful API.
  • Apple School Manager Photo Server
    A side-project for Jamf that allowed numerous Jamf Pro servers to demo Apple School Manager’s photo integration (a bit of a niche).
  • Avatar Server (Employee Photos)
    An internal employee photo service that mimics the way photos are delivered from Gravatar with options for scaling and auto-cropping. This was originally written for us to be able to use Facewall in our Minneapolis office lobby.

So, about Casper-HC…

When webhooks finally, finally, came into Jamf Pro with v9.93 I was very excited about what that meant for the next generations of plugins/integrations that could start to be developed. I had openly talked about a bare-bones HipChat plugin that I had been working on and my desire to build real time notifications into its features. I had also talked about doing the same with Slack.

We’re an Atlassian shop so HipChat got my attention first (sorry…).

casper-hc-installed.png

Casper-HC is the friendly HipChat plugin to Jamf Pro:

https://github.com/jamfit/Casper-HC

The original (internal) plugin I wrote for HipChat and Jamf Pro was purely a search interface in chat format. Type some commands into a room with some search terms and you’ll get nicely rendered results back.

The all-new plugin is a Flask application that is installed per-room (not globally) and makes much better use of HipChat’s API framework. All of the original search functionality has been preserved, improved, and I’ve integrated the new webhooks to provide notifications.

Get started.

When you install the plugin into a room you’ll get the nice notification you see above providing a randomized endpoint for you to send webhook events to. This is partly security through obscurity as there are no authentication options from the Jamf Pro server to the destination. It also links the inbound webhook to the appropriate chatroom.

If authentication makes its way into the product I can add in support.

An extra step of configuring a service account for accessing the REST API is required before using the search features, but notifications are immediately available. This allows you to install the plugin into rooms that will purely display notifications without any other features.

Follow the suggestion to type casper help to learn more.

casper-hc-help.png

Not all the help text has been implemented at this time, but we can see that enabling a service account is done on the configuration page for the plugin for this room. Heading there gives us a very bare bones screen for entering a URL, username, and a password for the JSS.

 

casper-hc-configure.png

Clicking Save will perform a quick test to the Jamf Pro server to verify the account can actually authenticate against it. Upon success the username and password are encrypted and saved in the database and you will receive two notifications.

 

casper-hc-configured.png

casper-hc-configured-notify.png

A future feature would be to verify the service account has all the required permissions for the search functions. That currently isn’t being handled.

What all does it do?

While not a huge deal, you can always grab your current version of the Jamf Pro server.

casper-hc-version.png

Right away notifications were available to setup in the new room. You might have noticed that all of the system notifications from the plugin are shown in purple. Different types of notifications will have different colors to help them stand out in high traffic rooms and in some cases provide a little context to what occurred.

casper-hc-notifications.png

The following webhooks are supported:

  • ComputerAdded
  • ComputerCheckIn
  • ComputerInventoryCompleted
  • JSSShutdown
  • JSSStartup
  • MobileDeviceCheckIn
  • MobileDeviceEnrolled
  • MobileDeviceUnEnrolled
  • PatchSoftwareTitleUpdated
  • RestAPIOperation

Some of those could easily flood a chat room which is where installing across multiple rooms comes in handy. One trick with RestAPIOperation notifications is that the plugin, for the installed room, will ignore API notifications triggered by the service account for that room, but those API calls would appear in another room also receiving API notifications.

The search functionality covers computers, mobile devices, and users. As a design choice I skipped the “slash” command convention and made the plugin listen for room messages beginning with “casper” and then the appropriate keyword. The regular expressions support shortnames for each of them so you can type quicker:

  • c|omputer|s
  • m|obile|s
  • u|ser|s

casper-hc-computers1.png

All of the search commands follow the same syntax of:

casper [command] (search string)

Computer and mobile device searches take advantage of the */match/* endpoints in the API. This effectively replicates the functionality of being logged into Jamf Pro and using the search boxes. When searching these devices you can:

  • Use wildcards (*)
  • Matches on most device identifiers and location data
  • Return single and list results

Users are a little different in that they have no similar feature in the API. Instead, you can match a user by passing either the matching username or email address for their record (no wildcards here).

Nearly every notification contains a weblink back to the original object in the Jamf Pro web interface. This makes the plugin extremely handy for techs by eliminating a large number of clicks in order to get to the device records of interest. If you have a chat room setup to receive notifications for support tickets you can search that user immediately without leaving the window (this is what the buzzword “chat-ops” refers to).

How do you start using it?

As I mentioned earlier, Casper-HC is just a Flask app. It requires a MySQL database for the backend and a web server for the front end, but it isn’t dependent upon any specific platform. You can find some more instructions on getting up and running in both a test and production environment in the README file for the project’s repository.

The running plugin that is being used for chat rooms at Jamf is deployed as a Docker container. You can find the setup for this here:

https://github.com/jamfit/Casper-HC-Docker

The docker-compose setup launches three containers: Nginx, Casper-HC + uWSGI, and MySQL. A data volume is created to persist the database between container tear-downs. You can find out more in the README at the link.

If you decide to follow suit with deploying Casper-HC as a containerized app you will want to create a service to periodically run a mysqldump and backup your database.

Are there future plans?

With my move out of IT I won’t be directly working on improving the plugin for my own use any longer, but if people were to begin using it and open issues on the GitHub page for bug fixes and feature requests I can pick up the work or others can contribute to improving the plugin.

A few of the features I had planned on getting to:

  • Get computer/mobile/user group memberships in chat
  • View advanced search results in chat
  • Non-destructive MDM commands from HipChat cards (card actions)
  • File uploads to Jamf Pro (via chat attachments)

If your org uses HipChat and Jamf Pro, I’d like to encourage you to try it out and send some feedback my way.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s