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.

API Keys created before the 26th of September 2023 will have the permissions of an administrator. Previously created API Keys that did not have an application role will remain with administrator permissions, but can be modified by you as needed.

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 Add API Key button in the top-right corner.

Create an API key

Provide a description that will identify where and how this key is used.

Then choose an expiry date. After this date, this API Key will no longer work.

API key description and expiry date

You can view and copy your Client ID and Client secret.

Client ID and Client secret

Next, you can click on the Networking tab to apply firewall rules.

You can optionally add your client IPv4 address or firewall rules to this API Key.

API key rules

If you add your client IPv4 address, it will display your Start IPv4 Address and End IPv4 Address.

If you add a firewall rule, you can then choose the Rule Name, Start IPv4 Address and End IPv4 Address, and click Save.

Click on Save at the bottom right to save the API Key.

Your key will display in the API Key table.

Find your API key

Edit an API Key

You can edit the details of this key using Edit on the right of the key.

Edit API key

Copy an API Key

You can then copy this key by right-clicking on the key and clicking Copy.

Or by editing the key, and using the Copy button on the right of the key.

Copy your API key

Delete an 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

Add an API Key to a Role

You can add an API Key either to an overall application role in the tenant or to a project role in a specific project.

Select a role from the tabs at the top of the page, click Add User, and then choose API Keys as the member type.

Choose user type

Choose an API Key from the dropdown and click Submit.

Choose role

This API Key will have the permissions of this role.

After it has been added, you can use the Client ID of this API Key to access Loome Monitor programmatically. The level of access will be the application role or project role of the 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.

We recommend using Loome’s Postman collection. You can easily generate scripts using the Postman collection in your preferred code language.

Set up Prerequisites

You will need to set up prerequisites to use Loome programmatically.

You can first set up script prerequisites according to our guide here.

Set up a Script using Loome’s Postman Collection

Choose a task on the left panel under Monitor.

(The endpoints your API Key can use will depend on the role you have added it to above.)

Provide any required details in fields such as the URL, Params or Body.

Choose the code format for your preferred language.

Copy the code for your script using the button on the right.

API steps

Please note that these endpoints are subject to change.

You can learn more about each API endpoint using the documentation button on the right.

API docs

If you get a Forbidden 403 error, it means your Client ID does not have the required minimum privilege to run the job. Other errors can inform you that the job has failed.

If you receive errors that contain Bad Request and/or Unauthorised 401, this most likely means your Client ID has been removed from the corresponding tenant.

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