How to pull data from vScope via the API, using a token

Have you made some interesting findings in vScope which you’d like to take elsewhere? Here is how to take the first step towards automation and feeding other systems with data from vScope.

We are building vScope to become a cornerstone in organizations’ automation of IT. With vScope gathering and structuring data from across the whole IT, it is up to you as a user to decide whether to make use of the information within vScope or if you’d like to use the data in other systems. With this post I will show how to get started with live exporting data from vScope using the inbuilt API.

Export a table to CSV or XLSX using the API with a token

In this guide I will show you how to pull a CSV file based on a specific table from vScope – only using the API in vScope. “Why would you do that?” you might wonder. The answer is easy: using data from vScope can actually be the first step towards automating manual operations in other systems. This by making vScope responsible for the gathering and structuring of data.

I will also cover how you can do the export using an API token. This means that you can have the option “Guest access” (that is, accessing vScope without having to login) turned off and still be able to securely access the API.

Prerequisites

We have a quite comprehensive API documentation. You can find it here:

[vscope-server-name]/apidoc

To read more on how the API documentation works, checkout my earlier blogpost:

How to make use of vScope’s API.

In order to create an API token you will need to be logged in to vScope. You can do this either directly in vScope and then return to the documentation; Or you can authenticate yourself via the endpoint /rest/usermanager/authenticate. Also, make sure that you are a vScope administrator.

First, let’s create an API token!

Every token is created for a specific user in vScope. So for instance, you can create an user that is dedicated for API tokens. Users are created under the settings page under Users & Groups.

Create a dedicated user for API tokens

This step is actually not required. You can create an API tokens for anyone of your current users. If you don’t want a dedicated user for your tokens, skip to the next step (Create the token)

Name the user something like apiuser and set the email to someone that should be responsible for the user. Make sure to set the user as Admin, if you want the user to have admin privileges (which is recommended for this example).

Follow the link provided in the email and set a password for the user.

Create the token

Now let’s actually create the token! Go to the settings page and expand the section called API Tokens.

Here you can see all the API Tokens that can be used. To revoke a token , press the X next to it.

To create a token , simply click the button. A float should appear.

 Select the user that you want to base the API Token on. This should be the the user that we recently created. You can also set how many days the token should be valid. This field is optional and leaving it empty will make the token valid for ten years. Click create and the new token should appear in the list.

Using the token

To do a request with a token simply pass it along as a header, using the header key token. In CURL it looks like this:

curl -X GET --header 'token: [token]' [your vScope]/[endpoint]

For example; this will return the information about the user who owns the provided token, and save it to a file called me.txt:

curl -X GET --header 'token: 6483b55a3083b516' https://vscope/rest/usermanager/me > me.txt

Exporting a table to CSV using the API

Prepare a table

First we need to create a custom table in Table Explorer that will be used to take the data from. Select the resource that the table should be based on.

Now you can customize the table by including columns and filters. Any changes that you do to the table will be reflected when the data is collected from vScope, e.g. the export will have the same columns as the table.

When you’re done with the table, save it!

Now we need to get a hold of the ID of the table. This can be done by first opening Collaborators.

The last part of the permalink is the table’s ID. I have selected the ID in the image below.

Get the data from vScope

Now that we have the table’s ID we can get the data from vScope at any time by using this endpoint:

GET /rest/tables/{tableId}/csv

Replace {tableId} with the actual ID of the table. Like so:

GET /rest/tables/1504087939270/csv

This is how it will look using curl (don’t forget to include your API token as a header!):

curl -X GET --header 'token: 6483b55a3083b516' 'https://vscope/rest/tables/1504075943641/csv' > table.csv

Open the file and see that it contains rows and the columns specified in the table.

If you want the table to be in XLSX simply replace csv with xlsx, like so:

curl -X GET --header 'token: 6483b55a3083b516' 'https://vscope/rest/tables/1504075943641/xlsx' > table.xlsx

And we’re done!

Ending notes

API tokens are a great way to securely communicate with vScope without allowing anyone accessing the vScope data (enabling guest access). This method of getting and supplying the token can be used for any endpoint in the entire API for instance: starting Discoveries with a script, automatically get information about certain Tracker cases or any other data in vScope.

Why not use it for integration projects eg. I want to pick a machine from a list for a support ticket, why don’t get this list of machines automatically get it live from vScope?

Looking forward

This tutorial showed how to easily extract information from vScope in the form of CSV or XLSX. A great start for making vScope the cornerstone in any organization’s automation processes. Now go try this for yourself and I will return with more posts with suggestions of how to make use of these live exports.

To be continued…

Eric Nilsson

Front-end Developer

Back to the blog

Sign up for newsletter

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

2018-08-13T08:11:05+00:00