Remote API Access

You can run a rule programmatically by sending a request to the API. First you will need to create an API key, please follow the steps below.

Currently, API Keys created in Loome Monitor will have the same permissions as an administrator. In future, API Keys will have specific roles attached to them.

How to Create an API Key

On the Remote API Access page, you can manage Remote API Keys for Loome Monitor.

You can find the Remote Access page from the dropdown menu.

Remote access page

To create an API Key, click on the Create Key button in the top-right corner.

Create an API key

Your key will display below.

Find your API key

You can then copy this key using the Copy button on the left of the key.

Copy your API key

If you would like to delete an API key, please click on Delete on the right of the key.

Delete an API key

Working with the Loome Monitor API

Like Loome Integrate, Loome Monitor exposes a REST API that can be used to interact with Loome Monitor programmatically. Whilst the API is language agnostic, this example is written in PowerShell and has been tested with PowerShell 5, and can be used from this version onwards.

Currently, Loome Monitor does not expose API documentation. API documentation will be exposed in the future.

Using PowerShell to Run a Rule

The following PowerShell script includes functions for executing rules:

There are three variables that need to be changed in the PowerShell script to match your own Loome instance:

  1. $ClientId
    • This is the Client ID of the API key created in Loome Monitor in the guide above.
  2. $AlertIdToExecute
    • This is the ID of the rule that will be run
    • This can be retrieved by going to the rule editor and grabbing the last numeric value in the URL
    • ID to execute
  3. $SelectedHost (Optional)
    • US Clients can change this to $US, it will have a default of $AU

The script will:

  1. Kick off the execution for the provided rule ID (the rule in step 2 above)
  2. Await the completion of the execution
  3. Once the execution has finished, if the execution failed it will throw an error with the reason for the failure.

# Enter your client ID here.
$ClientId = "";

# 1. Provide the ID of the Alert to execute here.
$AlertIdToExecute = 0;

# For AU
$AU = @{
    "IdsHostname" = "identity-au.perspectiveilm.com";
    "ApiHostname" = "monitor-api-au.loomesoftware.com";
};

# For US
$US = @{
    "IdsHostname" = "identity-us.perspectiveilm.com";
    "ApiHostname" = "monitor-api-us.loomesoftware.com";
}

# Change this to your selected host respectively.
$SelectedHost = $AU;

$TokenBody = @{
    "grant_type"    = "client_credentials";
    "client_id"     = $ClientId;
    "client_secret" = $ClientId;
    "scope"         = "webApi"
};

$BaseUrl = "https://$($SelectedHost['ApiHostname'])/api/v1/";

$AccessToken = ((Invoke-WebRequest -Uri "https://$($SelectedHost['IdsHostname'])/connect/token" -Method Post -Body $TokenBody).Content | ConvertFrom-Json).access_token;
$AccessHeaders = @{"Authorization" = "bearer $AccessToken" }

<#
    .SYNOPSIS
        Returns the URL for the Monitor API, based on a provided path.
    .EXAMPLE
        $Url = Get-MonitorApiUrl "rulesets/executions/12"
#>
function Get-MonitorApiUrl ([string]$Path) {
    return $BaseUrl + $Path;
}

<#
    .SYNOPSIS
        Invokes an in Monitor, returning the created execution object.
    
    .EXAMPLE
        $AlertExecution = Invoke-MonitorAlert -AlertId $AlertId;
#>
function Invoke-MonitorAlert ([int]$AlertId) {  
    $Url = Get-MonitorApiUrl "rulesets/$AlertId/execute";
    $Res = Invoke-WebRequest -Method Post -Uri $Url -Headers $AccessHeaders -ContentType "application/json"
    return ($Res.Content | ConvertFrom-Json)
}

<#
    .SYNOPSIS
        Returns the execution object from Monitor for a particular execution ID.
#>
function Get-MonitorAlertExecution ([int]$AlertExecutionId) {
    $Url = Get-MonitorApiUrl "rulesets/executions/$AlertExecutionId";
    $Res = Invoke-WebRequest -Method Get -Uri $Url -Headers $AccessHeaders -ContentType "application/json";
    return ($Res.Content | ConvertFrom-Json)
}

<#
    .SYNOPSIS
        Returns true if the provided status is a completed status.
    .EXAMPLE
        $IsComplete = Test-StatusComplete $Execution.Status;
#>
function Test-StatusComplete ([string]$Status) {
    return ($Status -eq "Success") -or ($Status -eq "Failure") -or ($Status -eq "Cancelled");
}

<#
    .SYNOPSIS
        Watches the execution of the Monitor alert execution, only finishing when
        the alert itself has finished.

    .EXAMPLE
        Watch-MonitorAlertExecution -AlertExecutionId 27;
#>
function Watch-MonitorAlertExecution (
    [int]$AlertExecutionId,
    [int]$PollSeconds = 30) {
    $Execution = $null;
    $IsRunning = $false;

    do {
        $Execution = Get-MonitorAlertExecution -AlertExecutionId $AlertExecutionId;
        $IsRunning = (Test-StatusComplete $Execution.Status) -eq $false;
        # When the Alert is still running, wait for a specified amount of seconds and try again.
        if ($IsRunning) {
            Write-Output "Alert Execution $AlertExecutionId is '$($Execution.Status)', waiting $PollSeconds seconds before checking status again...";
            Start-Sleep -Seconds $PollSeconds;
        }
    } while ($IsRunning);

    if ($Execution.Status -ne "Success") {
        # Throw the failure as an exception so it can be used in an Integrate Powershell Core task.
        throw "Alert execution $AlertExecutionId failed with status '$($Execution.Status)' (Reason: $($Execution.Message))";
    }
    else {
        Write-Output "Alert execution $AlertExecutionId completed successfully!";
    }
}

<#
    EXAMPLE RULESET EXECUTION
#>

# 1. Kick off the execution in the Monitor API
$Execution = Invoke-MonitorAlert -AlertId $AlertIdToExecute;
Write-Output "Alert has been executed with an execution ID of $AlertIdToExecute";
# 2. Call the watch method to wait on the execution until its complete.
Watch-MonitorAlertExecution -AlertExecutionId $Execution.ruleExecutionId