Mastodon

PS Module Update: KaceSma v2.0 (beta) Available Now! [UPDATED]

Kace Nov 13, 2019

UPDATE 12/2/2019: KaceSMA v2.0 is now out of beta and is considered GA (Generally Available)

What's New, What's Changed, and Why

Author disclaimer: I am not an employee of Quest, nor do I work for them in any capacity. This module is community (me) authored and supported.

The original KaceSMA module was first published to the Powershell Gallery on September 13, 2018. Since then, I've added new capabilities as they became available from new and updated API endpoints of the Kace SMA (Systems Management Appliance). This has worked well enough up until now. So why the change?

There have been a few major areas that, as I use the module and gather feedback from others who do as well, I realized there was still a lot of room for improvement. While nobody enjoys breaking changes, they can be a good thing in the long run. It's my hope that once scripts and processes are updated to support the new experience and features, the overall experience will be a lot smoother.

A New Authentication Method

The way you authenticate to the Kace SMA has been completely redesigned. It's still the same technology behind the curtains, but now you only need to authenticate once per session. This is done with a new cmdlet, Connect-SmaServer. Specify the server, org, and credentials you want to connect to, and you're done.

PS> Connect-SmaServer -Server 'https://kace.example.com' -Org 'Default' -Credential (Get-Credential)
Connect to an SMA Appliance

You'll receive a token that can be used on any requests within the same session (i.e. a script or console session). This token expires just like the web GUI login session, and follows the same timeout. Now, you can request additional endpoints without the need to specify Server, Credential, and Org in every call.

Completely Overhauled Help Docs

Originally, documentation was split between traditional comment-based help (CBH) and an online wiki. The wiki was more examples and FAQ, and the CBH was more technical explanation- parameter object types, etc. These have been combined into a more modern help system, powered by PlatyPS. You'll still be able to use Get-Help from the console, however if you specify the -Online switch, the help docs will open in a browser window in a much more readable markdown format. Also, the help documents will be much easier to update in the future.

The wiki FAQ page will stay, but the examples are now rolled into the comment based help. Of course, you can also browse all the help docs in the /docs folder of the project repository.

Pipeline Support

Get-PipelineSupport | Yes-Please

One of the most exciting new features in KaceSMA version 2.0 is the ability to utilize the pipeline for tasks. Previously, you could not chain a Get- cmdlet to a Set- and had to resort to using something like 1..5 | % {Get-SmaAsset -ID $_ -Server ... -Org ... -Credential ...}

With pipeline support, you'll be able to do this, for example:

Get-SmaServiceDeskTicket -Id 123 | Get-SmaServiceDeskTicketChanges
Utilize the pipeline to chain commands together

As long as the preceding value is of the right type (or can be converted to the right type) OR has a property of the correct name (Id) this will work.

Miscellaneous Updates and Fixes

Parameters now have named positions  in places it makes sense, like specifying an ID. So, you can now simply run Get-SmaAsset 1234 and return the result without specifying -Id. Additionally, all parameters previously titled MachineId, AssetId, or NodeId are all simply now `-Id`, although the old names are still present on each cmdlet as an alias. This was done to accommodate the new pipeline input feature.

Where are New-SmaScript and Get-SmaArchiveAsset?

These cmdlets were removed pending fixes in the upstream API. They have been reported as bugs to Quest, and will be reinstated once they are confirmed to return correct data.

What Do I Need To Change To Make My Scripts Compatible?

First, you'll want to authenticate within your script. This can be accomplished with the Connect-SmaServer cmdlet.

Once authenticated, any pre 2.0 logic like this:

$Result = Get-SmaMachineInventory -MachineId 123 ...
$Result.Machines
Old Method

will need to be updated to remove the .Machines property, as they return natively now.

$Result = Get-SmaMachineInventory -Id 123
$Result
New Method

This was done to accommodate the new pipeline input and also save time with unnecessary nesting.

Check It Out

You can check out the project on GitHub or download it from the Powershell Gallery.

ArtisanByteCrafter/KaceSMA
A module for interacting with a Quest Kace Systems Management Appliance API via Powershell. - ArtisanByteCrafter/KaceSMA
KaceSMA is fully open source, and MIT licensed
KaceSMA 2.0.0-beta
A module for interacting with a Quest SMA Appliance and Powershell objects. Requests are submitted to the appliance API and returned as actionable objects. You can run existing scripts, create new script tasks, gather machine and asset information, and much more. New actions are being added as they …

Tags