SHARE

Using the REST API to Get the Most out of SolarWinds, Part 2

In the first post in this series, I started by going over authentication with the SolarWinds API and sending queries with parameters. This time we’ll dive in a little deeper and talk about leveraging the many “verbs” that are available.

If you haven’t already, you’ll want to go and download the Orion SDK which includes a utility called SWQL Studio. That’s going to allow us to submit SWQL (SolarWinds Query Language) requests to the SWIS (SolarWinds Information Service). You can grab the latest version available even if it’s a beta. The changes are measured and infrequent and usually involve some kind of improvement/bugfix over the last.

Once it’s installed, launch it and authenticate the way you would if you were logging into the web console.

Provide the hostname of the SolarWinds server (localhost if you’re running it on the server itself), and then either provide a username & password or change the “Server Type” drop-down to “Orion (v3) AD” to authenticate with the user you’re using to log into your machine. Either will get you to the same place provided your user has admin privileges. For this exercise you’ll want to make sure you use an account that has at least node management rights because we’re going to unmanage and remanage a node in the inventory.

Once you’ve authenticated you can expand the left dropdown and see that there are dozens of namespaces. These are basically folders organizing all the entities that are in SolarWinds. The more products you have installed the more entries you’re going to see here. There’s even some overlap where products have been renamed (e.g., Cirrus renamed to NCM).

Since the goal is to unmanage a device the first order of business is to expand the Orion namespace so we can get to the Orion.Nodes entity. Expanding that area reveals a long list of properties with the blue icons, generated fields with green icons, navigation properties with chain links, and finally verbs with purple/pink icons. That “Unmanage” verb the one we’ll use to unmanage this device.

Properties

Generated Properties

Verbs

The information that SWIS needs to unmanage a device are the netObjectId, the time to start the unmanage period (usually now is good), the remanage time (now + 2 hours, for example) and finally a flag indicating whether or not the remanage time is relative. A relative remanage time would be something like “00:30:00” for 30 minutes. Since it’s trivial to come up with a timestamp 2 hours in the future in any programming language it makes sense to set this to false and go ahead and provide unmanage and remanage time stamp values.

Now that we know what need, let’s move over to Postman to do the work.

The setup that’s required is the same that we went through in the last post so I’ll just list the steps briefly here:

  1. Launch Postman.
  2. Change the method from GET to POST and enter the beginning of the URL.
    1. https://<your_solarwinds_server>:17778/SolarWinds/InformationService/v3/Json/
  3. Set the authentication to Basic Auth, enter your username & password, and click ‘Update Request’.

The URL we’re going to use for the request is slightly different now that we’re using a verb. The format is talked about a bit in the SolarWinds wiki and takes a format like the following:

<url>/Invoke/<entity>/<verb>

In our case it’ll look like this:

https://<your_solarwinds_server>:17778/SolarWinds/InformationService/v3/Json/Invoke/Orion.Nodes/Unmanage

If we were to send the request as it is we would get a status code of “500 Internal Server Error” and an error back:

That makes sense because we haven’t provided those four bits of information that it requires yet from above. So let’s get on with that. Since it’s expecting JSON we’ll have to format our information using JSON syntax. In our case, we’re meant to provide an array of values – a string, two datetime values, and a Boolean true/false. Since JSON doesn’t have a datetime value we’ll go ahead and send them as strings. To get started, scroll up from the response we just saw and 1) click the ‘Body’ link, 2) change the radio button to ‘Raw’, and 3) change the format to JSON (application/json).

For the request we’re going to need the current UTC datetime and another UTC datetime that’s 4 hours later. Postman makes this simple with its pre-request scripts. So we’ll set a couple of variables that we can use in our JSON request. Click the ‘Pre-request Script’ link and paste the following:

postman.setEnvironmentVariable("now", (new Date()).toJSON());
postman.setEnvironmentVariable("later", (new Date()).addHours(4).toJSON());

This creates two variables we can use: now & later. The first will be the current UTC datetime in JSON format, and the second with be the same datetime only 4 hours later. We’ll use them in our JSON body by pasting in the following (make sure you change your N:57 value to a node ID that you actually have in your environment):

["N:57", "{{now}}", "{{later}}", false]

When the pre-request script runs that will be converted to something like this:

["N:57","2017-08-09T06:08:58.067Z","2017-08-09T10:08:58.068Z",false]

When we click ‘Send’ if everything went well we should get a “200 OK” response with the value “null”. If not, you’ll get an error indicating what went wrong. Logging into this web console at this point should show that the node is in fact unmanaged now:

Now to remanage it we return to our SWQL Studio window to see what parameters it requires:

It makes sense that the only thing it needs is the node that you want to remanage since that happens immediately and has no duration involved. So adjust your POST URL to look like the following:

https://<your_solarwinds_server>:17778/SolarWinds/InformationService/v3/Json/Invoke/Orion.Nodes/Remanage

And change the body to the following:

["N:57"]

Once you’ve clicked ‘Send’, provided you get a “200 OK” and a “null” response, the node should be remanaged again. You can confirm by heading back to the web console like we did before. Note that it will start out as unknown while it’s getting through its initial poll but it will certainly not be set to unmanaged any longer.

That’s all there is to it! Next, we’ll talk about doing more complicated things like running NCM scripts using the REST API!

Steven Klassen
Programmer Analyst @ Loop1 Systems, Inc.

Author

Recent Posts
Digital Transformation
Digital Transformation is Driving Observability Adoption... and it’s Delivering Success!
Great Place to Work
Celebrating Success Loop1 Sri Lanka Ranks Among the Top 10 IT/ITES Workplaces
blog featured image
'Tis the Season of the Freeze
blog image
L1M3 Explainer Part 7 – Data Analytics and Business Outcomes
blog image
L1M3 Explainer Part 6 – Automation and Integration
blog image
L1M3 Explainer Part 5 – Security and Compliance
blog image
L1M3 Explainer Part 4 – Observability Data and Metrics
blog image
Observability and Maturity Part 3 – Feature Awareness
Shopping Cart
Scroll to Top