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

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

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.

Leave a Reply