Updating Orion WorldWide Map Node Locations from external data.

When is a Node not a Node?.... When it's an Elephant of course!

No that wasn't an attempt at the world's worst dad joke because we all know nodes are always nodes but sometimes at SolarWinds, we find ourselves collaborating with customers who are using our solutions in some very interesting ways. None more so than a recent example from a customer who needed a mapping solution to display the latest GPS location from devices that are tracking Elephants across the national and regional parks of Africa. 

The Task:

"Use a JSON data source to update the location of the objects in the Orion WorldWide Map."

This can be broken down into the following steps

• Create a JSON data source containing sample data for NodeID, Lat, Long, City.
• Retrieve the data using Powershell.
• Update the WorldMapPoints SWIS Entity and Node Custom Property.

The Solution

1. Create a sample JSON Data Source

To keep this example generic and easier to re-use by others a basic data source was needed. This was a great use case for an Azure function App, off to SO we go then

Courtesy of https://stackoverflow.com/questions/38943858/how-do-i-return-json-from-an-azure-function  resulted in the following code being used. 

#r "Newtonsoft.Json"
using System.Net;
using Newtonsoft.Json;
using System.Text;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
    var myObj = new {latitude ="51.89797", longitude ="-8.47061" ,NodeID="1",City="Cork"};
    var jsonToReturn = JsonConvert.SerializeObject(myObj);
    return new HttpResponseMessage(HttpStatusCode.OK) {
        Content = new StringContent(jsonToReturn, Encoding.UTF8, "application/json")
    };
}

New to Azure function Apps? Check out the guide here https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function

https://jsondataexample.azurewebsites.us/api/JSON returns a basic JSON structure with no hierarchy

{"latitude":"51.89797","longitude":"-8.47061","NodeID":"1","City":"Cork"}

2. Retrieve the data using PowerShell

This one is kept simple too, with no authorization to worry about.

#Connect To WebService to retrieve data
$json = Invoke-WebRequest 'https://jsondataexample.azurewebsites.us/api/JSON' | ConvertFrom-Json

3. Connect to SWIS and update the Entities

# Connect to SWIS
Import-Module SwisPowerShell
Add-PSSnapin SwisSnapin
$hostname = "YourOrionServer"
$swis = Connect-Swis -Hostname $hostname

#----------------------------------------------------------#

#1. Define values for world map points
$WorldMapProps = @{  
   Instance= 'Orion.Nodes';
   Latitude= $json[0].latitude;
   Longitude=$json[0].longitude;
}

#2. Get URI for WorldMap.point based on INstanceId being the same as the NodeID
$Query = 'SELECT  Uri FROM Orion.WorldMap.Point where InstanceID=' + $json[0].NodeID;
$Uri = get-swisData $swis $Query

#3. Update the entity
Set-SwisObject $swis $Uri -Properties $WorldMapProps 

#----------------------------------------------------------#

#----------------------------------------------------------#

#1 Define values for Custom Properties
$CustomProps = @{  
   City= $json[0].City;

}
#2. Get URI for Orion.NodesCustomProperties based on NodeID being the same as the NodeID
$Query = 'SELECT Uri FROM Orion.NodesCustomProperties where NodeID=' + $json[0].NodeID;
$Uri = get-swisData $swis $Query
Set-SwisObject $swis $Uri -Properties $CustomProps 

#----------------------------------------------------------#

And that's it Ok this is an extremely simplistic example.

• There is no Hierarchy in the JSON to iterate through, It's only 1 node.
• The NodeID is provided in the JSON to make it easier to correlate. 
• There are no loops or validation to check if the node is actually on the Map to begin with.
• There is no error handling.

However, this does illustrate one very important aspect of working with the Orion SDK.

Not every entity will have verbs to work with!

Let's take a quick look at SWQL Studio and the Orion.WorldMap.Point Entity.

The Documentation displayed for the entity shows it supports CRUD operations

Manipulating Data Using the Invoke Interface

The SWIS query interface is read-only and cannot be used to insert, update, or delete data. SWIS provides an Invoke interface for users to make changes to Orion. Some entity types define verbs that can be called through this interface. For example, Orion.AlertActive defines an Acknowledge verb that users can use to mark alerts as acknowledged. Because this goes through SWIS, the Acknowledge verb can securely validate that the current user has permission to acknowledge alerts and can record the name of the user doing the acknowledging and the corresponding timestamp.

Manipulating Entities Using the CRUD Interface

SWIS supports an interface for creating, reading, updating, and deleting entities. These create, read, update, and delete (CRUD) operations comprise a generic interface through which you can access any entity type exposed by SWIS and manipulate the entity in a uniform fashion.

However, there may be entity types that do not support this interface or provide only limited support due to technical or design reasons. In these cases, the operations may reject requests.

CRUD operations operate on SWIS Uris. Create returns the Uri of the new entity. Read, Update, and Delete take one or more Uris as input.