New PowerShell Function: Get-JCSystemApp — What device has ‘x’ software and ‘y’ version

[jworkman]

Admins need to know which of their JumpCloud systems have specific softwares installed and of what version in order to make decisions and effectively manage their fleet. This week, the newest version of JumpCloud PowerShell Module was updated to include a new cmdlet called Get-JCSystemApp. This new function was designed to help admins answer the question “What device has ‘X’ software installed and ‘Y’ version”.

Function Overview:

JumpCloud devices store details about software installed on Windows/ Linux and macOS systems through a service called System Insights. Software for each system type is available within the JumpCloud console and through our API.

Gathering this data for all systems can be a chore without specific knowledge of the JumpCloud API. The Get-JCSystemApp function aims to help administrators find this data quickly and efficiently.

Function Parameters

The Get-JCSystemApp function can search across all systems in a JumpCloud organization to find software installed on Windows/ Linux and/or macOS systems. The scope of searches can be focused or broadly performed. The examples below will outline how to use the tool most efficiently and to perform searches when the name of a software isn’t exactly known.

At its core, Get-JCSystemApp is a function that can return all Applications (for macOS), Programs (for Windows) and Linux Packages (for Linux systems). Without providing any additional parameters, Get-JCSystemApp will return all installed software for each system in its given organization.

Detailed parameter documentation is published for this function but at a high level, searches can be filtered by os type, individual systems, software name and software version. Each corresponding parameter systemOS, SystemID, name, version can be used to limit the scope of returned software.

Searching for all macOS systems that have “Google Chrome” installed becomes a matter of specifying the correct parameter set. In this case:

Get-JCSystemApp -Name "Google Chrome" -SystemOS "macOS"

Note: Software names are case-sensitive

One additional parameter for Get-JCSystemApp is provided to help administrators identify applications of which they do not know the exact case-sensitive name and that is the search parameter. The exact use case for this parameter will be covered in this post but it's worth mentioning that it is less performant than providing Get-JCSystemApp with the exact case-sensitive name of the software being searched.

Use Examples:

General Use

Example 1: Find systems that have Google Chrome installed

To return systems with Google Chrome installed, the following search can be performed:

Get-JCSystemApp -Name "Google Chrome"

In the specific case of Google Chrome, the exact case-sensitive name: “Google Chrome” is the same record name for Windows and macOS systems. As such, both Windows and macOS systems would be returned in the results list. Reporting can get tricky as the table properties for Windows and macOS systems are different. 

Example 2: Find macOS systems that have Slack installed

To return only macOS systems with “Slack” installed, the following search can be performed

Get-JCSystemApp -Name "Slack" -SystemOS "macOS"

In this example, only macOS systems with Slack installed would be returned. 

Example 3: Find Windows systems that have Microsoft Edge version ‘y’ installed

To return only the windows systems with “Microsoft Edge” Installed and running “109.0.1518.69”, the following query can be performed:

Get-JCSystemApp -name "Microsoft Edge" -SystemOS "Windows" -version "109.0.1518.69"

This will return a list of systems that are Windows devices, have Microsoft Edge version 109.0.1518.69 installed.

Note: For Windows/ Linux systems the “Version” property is used to query the version of software installed. macOS devices have no such property and instead the “BundleShortVersion” is queried instead.

Example 4: Find systems that have VS Code installed but the name of the software is not known.

If the exact case-sensitive name of a software title isn’t known, the search parameter can be used to identify the name of a software title as it’s stored in the System Insights database. 

In this example, say that we want to get a list of macOS and Windows systems that have “Microsoft Visual Studio Code” installed. What is the software name and is it consistent for macOS and Windows systems?

We could try the following queries

Get-JCSystemApp -Name "VS Code" -SystemOS macOS

Get-JCSystemApp -Name "Microsoft Visual Studio Code" -SystemOS windows

However neither query returns a result.

If we knew of at least one system that had VS Code installed, we could go gather it’s systemID and run the following query:

Get-JCSystemApp -Name "Microsoft Visual Studio Code" -SystemID 6123b79fdc842b15a96e5ade -Search

Which will return a single result:

Without the ‘search’ parameter, the ‘Name’ parameter performs case-sensitive searches. While case-sensitive searches are more performant than using the ‘search’ parameter, they rely on an administrator knowing the name of every software title. In the case for a windows device, the name recorded in the database is “Microsoft Visual Studio Code (User)” 

Now, what’s the difference between windows and mac, let’s perform a similar search but on all macOS devices:

Get-JCSystemApp -Name "Code" -SystemOS "macOS" -Search

In this example, the entire “macOS” group of systems is being queried given the case that we didn’t know a systemID of a system that had VS Code installed. This query will always take longer than searching an individual system.

This query will return many results but the item we are looking for is titled: “Visual Studio Code” — a slight difference than the Windows Application.

After figuring out what the recorded name of a software title is on Windows and macOS devices we can finally run two queries to quickly query the devices that have VS Code installed:

Windows:

$windows = Get-JCSystemApp -Name "Microsoft Visual Studio Code (User)" -SystemOS Windows

macOS:

$mac = Get-JCSystemApp -Name "Visual Studio Code" -SystemOS macOS

Note: Windows and macOS data for installed applications differs slightly from one another. It’s a good assumption that the BundleShortVersion is the ‘version’ of an application installed on macOS but some software vendors may choose to record this value in a different field.

Example 5: Return all macOS software across all devices

To return all macOS software titles the following query can be performed:

Get-JCSystemApp -SystemOS "macOS"

This will gather all macOS applications from the corresponding System Insights table and return those applications. This queries runtime is a function of the number of devices within an organization.

Example 6: Return all software from one device

To return all applications from a single system, simply pass in the systems ID

Get-JCSystemApp -SystemID "5e90f19ecc99d210ecb3406c"

This query will determine the system’s OS type and gather the recorded application data for that single system.

Extended Use

Use the output of Get-JCSystemApp and create a device group

When it’s time to take action on devices that don’t have a specific version of software, a system group can be created and individual devices updated with JumpCloud Commands or Software Management.

In the case that an administrator needs to deploy “Slack” to macOS devices that do not currently have that application installed, the Get-JCSystemApp function can be used to scope systems for installation.

In order to obtain a list of systems that do not have some software installed, two queries must first be made:

1. A list of all macOS systems
2. A list of macOS systems that have “Slack” installed

To obtain a list of all macOS systems:

$systems = Get-JCSystem -os "Mac OS X"

The systems variable will contain a list of all macOS systems

To obtain a list of all macOS systems with “Slack” installed:

$slack = Get-JCSystemApp -SystemOS macOS -Name "Slack"

The ‘slack’ variable will contain a list of all macOS systems with slack installed, including their installed versions and application information. 

Finally to create a list of systems without “Slack” installed, simply run:

$missing = $systems | Where-Object { $_._id -notin $slack.systemID }

The resulting variable ‘missing’ will contain a list of systems that are not in the ‘slack’ variable — meaning a list of all systems that do not have “Slack” installed can then be used to create a system group.

To quickly create a system group from this list of systems, run the following code snippet:

New-JCSystemGroup -GroupName "macOS-Missing-Slack"
$missing | ForEach-Object { Add-JCSystemGroupMember -GroupName "macOS-Missing-Slack" -SystemID $_._id }

This will create a new system group titled “macOS-Missing-Slack” and populate the group with the list of systems that do not have “Slack” installed. From there, commands or VPP Applications can be assigned to this system group to deploy the missing “Slack” application.

Create CSV Reports

To create CSV reports the ConvertTo-CSV and Out-File cmdlets can be used in conjunction with Get-JCSystemApp. 

In powershell, most objects can be converted into a CSV object, output from Get-JCSystemApp is no different. To create a CSV, an object must first be generated.

To get a list of systems with “Firefox” installed and save the output as a CSV:

$apps = Get-JCSystemApp -SystemOS "macOS" -Name "Firefox"
$apps | ConvertTo-CSV | Out-File ~/firefoxReport.CSV

This code snippet will gather the macOS systems that have Firefox installed, convert the output to CSV format and finally write the file to the home directory as “firefoxReport.CSV”.

Any number of reports can be generated with the Get-JCSystemApp function. An entire list of macOS applications can be saved in the same manner:

$apps = Get-JCSystemApp -SystemOS "macOS"
$apps | ConvertTo-CSV | Out-File ~/macOSApplicationReport.CSV

Note: This query may take a while to run for larger organizations due to the fact that all application data is being returned per macOS system.

Note: properties between Windows/ Linux and macOS systems differ, it’s recommended to create CSV reports for each type of OS separately. If a Get-JCSystemApp query returns results of multiple OS types, converting the entire set of results to CSV will produce unintended results. Namely the default properties of the first result would be used to cast headers for the remaining objects — the resulting CSV would only contain headers of the first result type. 

This can be solved for however. In a previous example, we determined that “Google Chrome” was the same application name in both Windows and MacOS devices, the following query could be used to save the results from multiple OS devices to a single CSV.  

$apps = Get-JCSystemApp -name "Google Chrome"
$list | Select -Property Name, SystemID, version, bundleShortVersion
$list | ConvertTo-CSV | Out-File ~/chromeReport.CSV

In this code snippet example we take advantage of the Select-Object cmdlet. By selecting only the Name, SystemID, version and bundleShortVersion properties from the results, we effectively build a new object, one which is exportable as CSV as the only headers are defined from the Select-Object cmdlet. In this example it’s clear that the macOS entries do not have a ‘version’ property nor do the windows devices have a ‘bundleShortVersion’ property. Either way this report can be exported as one single file.

We hope this command is helpful for those looking to automate groups or gather data about applications on your JumpCloud devices.

[ohad]

Is there a non-windows way to do this?  reports within the products? python script? 

[bwitzig_Zen · Accepted solution]

I believe the powershell module uses the "newer" version which is cross platform :). 

[SharaqAfzaal]

I ran the following command to get Firefox installed on the Windows devices it gave me an empty CSV file result, when I selected the -SystemOS "macOS" it provided me with complete details. Only the issue with with Windows how it behaves like this 
$apps = Get-JCSystemApp -Name "Firefox" -SystemOS "windows"
$apps | ConvertTo-CSV | Out-File ~/Firefox.CSV

[paul-mb]

This is brilliant. Thanks so much.

I needed to create a group for devices which had a specific app installed and edited your code to fit my purpose, using Slack as the example:

$systems = Get-JCSystem -os "Mac OS X"
$slack = Get-JCSystemApp -SystemOS macOS -Name "Slack"
$hasSlack = $systems | Where-Object { $_._id -in $slack.systemID }
New-JCSystemGroup -GroupName "macOS Slack Installed"
$hasSlack | ForEach-Object { Add-JCSystemGroupMember -GroupName "macOS Slack Installed" -SystemID $_._id }

[TH4DDEUS]

Is there a version of this command to get installed versions of Homebrew? since it does not live in /Applications the GetSystemApp command does not find it.

[urvashi]

@jworkman is this something you can help with?

[jworkman]

@TH4DDEUS, this data would not record homebrew applications sadly. Homebrew applications are binary apps which are not recorded in this data set. 

[rahulsoni]

Can we uninstall application via command from system ID 

[jworkman]

Yes you can perform almost any action you'd like with commands but probably not in the way you are thinking @rahulsoni. You would need to write a command with the instructions to uninstall your unique software. Every software is different so please refer to the software vendor for specific instructions. 

[micjagger09]

Hello! For the command below, I would also like to include the attribute 'username' for the bound user on the machines. But when I try to add the get-jcsystemuser | select username command, it only returns the username column in the csv report. Can someone show me how to get all the Get-JCsystem attributes included with the report, along with the usernames that are bound to the machines? Thanks in advance!

$systems = Get-JCSystem -os "Mac OS X"
$slack = Get-JCSystemApp -SystemOS macOS -Name "Slack"
$missing = $systems | Where-Object { $_._id -notin $slack.systemID } | export-csv macs_missing_slack.csv