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 is 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.
Prerequisites
vScope has 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 a user that is dedicated to API tokens. Users are created under the settings page under Users & Groups.
Optional – Create a dedicated user for API tokens
You can create 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 who 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).
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 could be 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 ‘Add token’ and the new token should appear in the list.
Using the token
To make 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 to access 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, and 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 of 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.