How to extract data from vScope to use in external applications & services

Are you becoming confident in vScope and want to build something by yourself? This post will give you an introduction to the vScope’s REST API.

vScope takes care of all the data gathering in your datacenter and makes the information easily accessible for anyone on your team. While vScope provides an intuitive user interface which lets you browse your IT in a completely new way, there might be occasions when you need to extract the data from vScope to elsewhere. This can be done via vScope’s API and here is an example of how to do it!

Extract IP Addresses and other values from vScope

In this tutorial I will go through a basic use case making use of vScope’s REST API. vScope’s frontend is built in AngularJS and makes use of this API. The exact same API is open to use for anyone with a licensed vScope which enables you to build basically anything based on the vScope data.

Prerequisites

In order to access the API you will either need to have Guest access enabled in vScope or to be logged in to your vScope. You can do this either directly in vScope and then return to the documentation; Or you can authenticate yourself via /rest/usermanager/authenticate.

Accessing the API

You can access the vScope API and its documentation via your browser:

[server-name]/apidoc

Here you’ve got access to all GET, POST, PUT & DELETE requests that you can make use of in your project. The REST API is fully documented, generated on the fly with swagger. Swagger also allows you to do requests directly via the documentation.

Let’s get started!

My goal here is to create a basic, general IP-list based on the data from vScope. It might not sound like much to the world but the same workflow holds true for extracting almost any data. So let’s start by extracting a list of IP addresses from vScope.

First, a short story about tablePresets…

To tell vScope what we want to extract we either need to build a tablePreset (a “table”) in Table Explorer, or use any of the bundled tablePresets in vScope. The bundled tablePresets are basically tables with columns and filters (found under Tailored Recommendations), or a list of all elements of a specific resource (Servers, IP addresses, Printers etc.).

All tablePresets for resources can be found under the All Resources dropdown in Table Explorer:

vscope api

Basically, a tablePreset is just the structure of what a table should look like. For example:

  • the name of the table
  • which columns that should be shown
  • filters that should be applied (that are visualized in the filter panel)

tablePresets can utilized by the same API-endpoints as Table Explorer uses, i.e. the /tables endpoints.

…and something about tableTypeId

Each tablePreset is built upon a specific table type (tableTypeId). This id can be found directly under the tablePreset name in Table Explorer.  You can also see this as the name of the main resource in a Table.

The tableTypeId tells vScope what the main resource of a tablePreset is, and thus the tags (information) that should be included when loading the table. For example, accessing a tablePreset with tableTypeId=printers won’t, by default, include information tags about LUNs or Datastores

Did you know?

If you call:

vscope.dumpPreset()

from the browser console when in Table Explorer, it will print out the active TablePreset.

Back to our IP plan

Now, if I just want to get the values from a specific tag for a specific resource (ie. IP of the resource IP address) we can use the following end-point:

GET: /rest/tables/{tableId}/tags/{tagName}

The tableId is a reference to a bundled Table preset and is in almost all cases the same as the resource name for the presets under All Resources. The tagName is the same as in the Column picker or Filter panel:

vscope api

So in this case when we want to get all IP addresses we simply call:

GET: /rest/tables/IP%20Addresses/tags/IP

(Note the %20, this is URI-equivalent of space)

or by using Swagger:

This will return a string array of all known IP addresses from vScope, both IPv4 and IPv6. So click Try it Out and see for yourself!

Congratulations, you have succeeded in your first API extraction!

Interested in any other information?

Likewise, if we only want the Type of the IP addresses listed we simply replace IP with Type in the request, like this:

GET: /rest/tables/IP%20Addresses/tags/Type

This endpoint is very versatile since it can get a list of almost every value in vScope. Just note that the requested tagName must be a tag that can be found in the Column picker in Table Explorer for that tableTypeId.

An easy way to get available tags for a specific tablePreset from the API is to call:

GET: /rest/tables/{tableId}/tags?includeTagSettings=false

Extending our IP plan

So now you have a list of IPs. Nice! But to turn this extraction into a more useful IP-plan, I will also include the Attached Names property of the tablePreset IP Addresses. Now, this will require the use of a different endpoint:

GET: /rest/tables/custom/rows

Or in Swagger:

In the example earlier we referenced an existing tablePreset using an ID, but in this case we will create our own. The tablePreset‘s structure can be quite complicated, but for our purposes we only need a simple one.

The tablePreset we will use has the following structure (in JSON):

{
   "@c": ".TablePresetAPI",
   "tableTypeId": "IP Addresses",
   "columns": [
     "IP",
     "Attached Names"
   ]
 }

Note that there are a lot of fields not included in this example. Consult the API-documentation if you want a full description of a tablePreset‘s structure.

The tablePreset (above) needs to be URI-Encoded before it can be used in the api request. There is a multitude of online tools that can do this for you This one for example (Meyerweb). After it has been encoded it will look like this:

%7B%0A%09%22%40c%22%3A%20%22.TablePresetAPI%22%2C%0A%09%22tableTypeId%22%3A%20%22IP%20Addresses%22%2C%0A%09%22columns%22%3A%20%5B%0A%09%09%22IP%22%2C%0A%09%09%22Attached%20Names%22%0A%09%5D%0A%7D

The encoded tablePreset will then be passed to the api as a header parameter, with the field name ‘Table-Preset’. Using curl it looks like this:

curl -X GET --header 'Accept: application/json'
            --header 'Table-Preset: %7B%0A%09%22%40c%22%3A%20%22.TablePresetAPI%22%2C%0A%09%22tableTypeId%22%3A%20%22IP%20Addresses%22%2C%0A%09%22columns%22%3A%20%5B%0A%09%09%22IP%22%2C%0A%09%09%22Attached%20Names%22%0A%09%5D%0A%7D'
            '/rest/tables/custom/rows'

Via swagger it will look like this:

Hit Try it Out and your result should look something like this:

 Major success!

The end-point /rest/tables/custom/rows also accepts skip and take as query parameters. This will allow you to load the data in a lazy manner. This is done by adding the following to the request url: ?skip=0&take=20. By default it will return all rows.

Ending notes

This tutorial was just a short introduction on extracting a basic IP-list from vScope. It might be relevant for some, but it should really only be seen as the starting point to create amazing stuff from the vScope data. Let vScope become your Discovery Engine gathering and structuring data from all over the datacenter and use it as your main data source for your IT!

Eric Nilsson

Front-end Developer

Sign up for newsletter

Join our community and 1000+ IT professionals by signing up for blogs, news and business insight through our newsletter

[recaptcha]

2018-10-31T11:21:34+00:00