Home

Get Requests

The -QueryParameters Parameter is used when appending filters,sorting,paging limits and more to a GET method API call. When used effectively, these can be a powerful way to return only the data you want.

As a best practice, consider the type of information you want to receive and include it as a shaping parameter. If all you need is a computer name and/or ID, include the query parameter ?shaping=machine limited. You can still filter on additional criteria, but performance is improved by not retrieving useless fields.

Inventory Examples:

Return Machines with Encryption status of "Fully Encrypted"

Get-SmaMachineInventory -Server https://kace.example.com -Org Default -Credential (Get-Credential) -QueryParameters "?shaping=machine limited&filtering=machine_bitlocker_volume.conversion_status eq fully encrypted"

TIP: You can display a nice table of the resulting computers/status by saving the query above to a variable* $encrypted, then:

$encrypted.Machines | %{[pscustomobject]@{'Computer'=($_.Name);'Conversion Status'='Fully Encrypted'}}

Return SMA inventory machines with title 'Arduino' installed:

Get-SmaMachineInventory -Server https://kace.example.com -Org Default -QueryParameters "?filtering=software.name eq arduino" -Credential (Get-Credential)

Return all inventory members of smart label named `D - SmartLabel - Test`

Get-SmaMachineInventory -Server https://kace.example.com -Org Default -Credential (Get-Credential) -QueryParameters "?shaping=machine all&paging=limit ALL&filtering=label.name eq D - SmartLabel - Test"

Find the registry uninstall strings of all Software Inventory VMWare products

$result = Get-SmaSoftwareInventory -Server https://kace.example.com -Org Default -Credential (Get-Credential) -QueryParameters "?paging=limit ALL&shaping=software ALL&filtering=software.name co vmware"

$result.Software | Select Name,Display_Version,Uninstall_String

Service Desk Examples

Create a new Service Desk ticket with New-SmaServiceDeskTicket. This will submit a new ticket for an SMA user with an ID of 1 into a Service Desk queue with an ID of 1 and a category with an ID of 1234.

NOTE: IDs can often be found when hovering over a url. For example, hovering over a queue shows ?id=1, revealing it's queue ID is 1.

$NewTicket = @{
    'Tickets' = @(
        @{
            'title'       = "My Title"
            'hd_queue_id' = 1 # ID of desired queue
            'submitter'   = 1 # ID of submitter
            "custom_1"    = 'value to populate custom field 1 with'
            "custom_4"    = 'value to populate custom field 4 with'
            "category"    = 1234 # ID of category to set
        }
    )
}

New-SmaServiceDeskTicket -Server 'https://kace.example.com' -Credential (Get-Credential) -Body $NewTicket

Get-SmaServiceDeskTicket

Get information about a service desk ticket, with parameter shaping:

PS $queryparameters = "?shaping= hd_ticket all,status limited,owner limited,submitter limited,category limited"
PS $t = Get-SmaServiceDeskTicket -Server $testserver -Credential $cred -TicketID 1234 -QueryParameters $queryparameters

PS $t.Tickets

title              : This is my awesome ticket
custom_1           : value of field custom_1
custom_2           :
custom_4           :
custom_3           :
is_manual_due_date : 0
cc_list            :
resolution         : i rock.
created            : 2018-10-01 11:54:36
modified           : 2018-10-01 14:46:41
id                 : 1234
hd_queue_id        : 1
status             : @{id=123; name=Closed; ordinal=7; state=closed}
owner              : @{id=2; user_name=artisanbytecrafter; email=email@example.com; full_name=abc}
submitter          : @{id=1; user_name=submittername; email=submitter@example.com; full_name=submitter}
category           : @{id=1; name=Queue Name::Category Name}
sla_dates          : {}

** Scripting Examples**

New-SmaScriptTask

Add a new task to an existing script

This is a table of Task IDs

Task Name	Task ID	Parameters
Verify a path exists	6	path
Log a message	27	type,message

$taskparams = @{
    'attempts' = 2
    'onFailure' = 'break'
    'onRemediationFailure' = @(
        @{
            'id'= 27
            'params'= [ordered]@{
                'type'='status'
                'message'='test remediation message2'
            }
        }
    )
}
New-SmaScriptTask -Server https://kace.example.com -Org Default -Credential (Get-Credential) -ScriptID 1234 -Body $taskparams

Invoke-SmaScript

Run a script against an array of machines

Invoke-SmaScript -Server 'https://kace.example.com' -Credential (Get-Credential) -ScriptID 1234 -TargetMachineIDs 5678,2345,4567

Duplicate a Script

This example uses Get-SmaScript to retrieve the attributes of an existing script, removes the ID and name fields, then creates a new script with a new name that is a copy of the source script.

$OldScript = <ID_of_script_to_duplicate_here>
$NewScriptName = "Copy-MyNewScriptName"

$ToDuplicate = Get-SmaScript -Server https://kace.example.com -Credential (Get-Credential) -ScriptID $OldScript
$ToDuplicate.psobject.properties.remove('id')
$ToDuplicate.psobject.properties.remove('name')
$ToDuplicate | Add-Member -NotePropertyName 'name' -NotePropertyValue $NewScriptName
$hashtable = @{}
foreach( $property in $ToDuplicate.psobject.properties.name )
{
    $hashtable[$property] = $ToDuplicate.$property
}

$NewScript = @{
    'Scripts' =@(
        $hashtable
    )
}

New-SmaScript -Server $server -Credential $credentials -Body $NewScript