Using PowerShell to invoke a Custom Tool using the REST API

You are here:

Every Custom Tool in System Frontier has a REST API that is exposed, which allows external applications and processes to execute the tool while still enforcing the least privilege RBAC model. A Custom Tool can be any command-line script or executable, including PowerShell, VBScript, Batch, Python, etc.

The following PowerShell snippet will execute a Custom Tool in System Frontier and return the results as an object.

In the example, “NumberOfTries” is a Custom Field that would normally grab input from the user when running the tool via the web UI.

The “CustomToolID” should match the Custom Tool you are wanting to invoke.

Multiple servers can be targeted by separating them with semicolons.

$jobURI = "http://frontierwebsrv/api/job"

$taskList = @()

# Task #1 Parameters
# ==============================================================================================
# Target String Required For a Computer, this is the hostname or IP address. Separate
# multiple entries by semicolon.
# ? ? Optional Other name / value pairs that correspond to Custom Fields in 
# System Frontier.
# Example: NumberOfTries will match the Custom Field name 
# Custom[NumberOfTries] in the arguments section of the 
# Custom Tool being executed.
# ==============================================================================================
$parameters = @{
Target = "APPSRV01;DBSSRV12"
NumberOfTries = 4
}

# Task #1
# ==============================================================================================
# CustomToolsID GUID Required GUID of the Custom Tool to be executed in System Frontier
# TargetClass String Required Computer is the only valid class that can be targeted for now.
# Parameters Array Required Name / value pairs corresponding to input parameters for the
# Custom Tool being executed. Defined above.
# ==============================================================================================
$task = @{
CustomToolID = "3D9DC890-7FF7-48AF-8A8D-C48395927A54"
TargetClass = "Computer"
Parameters = $parameters
}

# Add Task #1 to the task array
$taskList += $task

$jsonBody = ConvertTo-Json $taskList

# Create a new job to execute this task via the REST API, using the currently logged on user's credentials
"Call Custom Tool REST API..."
$jobID = Invoke-RestMethod -Method Post -Uri "$jobURI" -Body $jsonBody -ContentType 'application/json' -UseDefaultCredentials

# If successful, a valid GUID will be returned. If not, an empty GUID will be returned (00000000-0000-0000-0000-000000000000).
if (($jobID -ne $null) -and ($jobID -ne "00000000-0000-0000-0000-000000000000"))
{
"Job ID: $jobID"

$complete = $false

do
{
# Call the Job API again, this time passing in the Job ID. If valid, a job object will be returned where eaching
# task will be populated in the Tasks array of the job.
$jobResultsURI = "$($jobURI)/$($jobID)"
$response = Invoke-RestMethod -Method Get -Uri "$jobResultsURI" -UseDefaultCredentials

# Wait for the job to NOT be in a Ready or Running status
if ((0,2).Contains($response[0].Status) -eq $false)
{
$complete = $true
}
else
{
"Waiting for job to complete..."
Start-Sleep -Seconds 1
}
} until ($complete -eq $true)

# All the task data is here
"Results..."
$response[0].Tasks
}
else
{
"Error: Job was not created."
}

Permissions

The user account making the REST call must be a user in System Frontier belonging to at least one role with appropriately scoped RunCustomTool permission.

Job Engine Status Codes

The following is a breakdown of status codes that can be returned by the job engine.

0 = Ready
1 = Disabled
2 = Running
3 = Cancelled
4 = Failed
5 = Completed
6 = Not authorized
7 = Not licensed

Tags:
Was this article helpful?
Dislike 1