How to import tags from XLSX into vScope using Postman

Using vScope’s API is an advanced level of vScope and is usually not necessary. If you are not experienced using rest API’s it’s recommended to ask for help from a colleague who is.

Sometimes API requests are needed for specific tasks, for example importing manual tags and their values, or importing IP targets. Here’s a step by step how-to to how to use vScope’s open API using Postman.

Step 1 – Get Postman

Postman is free to use and makes API requests simpler. Start off by downloading and installing Postman. Make sure your computer have access vScope so that Postman can connect to vScope’s open API.

https://www.getpostman.com/

Step 2 – Prepare the Excel file

In this example we will import the tag ‘Your Manual Tag” for our servers. If you don’t already have an xlsx file prepared you can export a XLSX document with the server names from vScope. Take note of the resource type in the top left corner.

Open the excel file in Excel and add the tag you want to import to vScope. We called out tag “Your Manual Tag”. Save.

The most important thing in this step is that the XLSX file contains the server names and the tag you wish to import.

Step 3 – Create an API token in vScope

To import the manual tag to vScope we’ll need an API token for Postman. This token will tell vScope that Postman is allowed to make changes.

Go to vScope -> Settings -> API tokens -> +Add token

Choose a user that is allowed to access the resource you wish to add information to, and choose how many days the token will be active. In this case we’ll be able to use the token for 3 days.

Click ‘Create’, and done! We now have a token we can use in Postman.

Step 4 – Enter Postman

Enter Postman and close the popup.

Behind the popup you should see an empty project like the image below. Set the request to ‘POST’.

We start off by creating the request (building an URL). Enter the address to your vScope, it might look something like this https://vscope.example.com and add /rest/action/bulktag/xlsx.

Next we add the API token by adding a query string parameter. This will tell vScope that Postman is allowed to post this. Add:

?token=[token_created_in_vscope].

We’ve highlighted what this looks like for us in the image below.

Step 5 – Specify information you want added to vScope

Without specifying what we want to do with the query string, vScope won’t know what to do with the information in the excel file. To do this we simply add the information to the request URL in Postman. It may look overwhelming at first, but we’ll break it down below. Each parameter we need to define has been highlighted with a color in the image.

The “&” acts as a separator between the query parameters, and “%20” means space.

resourceType = All Machines
- Determines the resource we want as source for the rows we want to tag. In our example, we want to tag All Machines (see article’s second picture).
matchColumn = Name
- Specifies which column in the excel sheet that contains the values we want to use to match rows to rows in vScope. In our example, we want to map the rows using the values in the Name column.
matchTag = Name
- Specifies which tag in the Excel sheet that should be used to match the values in matchColumn. Since those values are names of the machines, we want to use the Name tag for matching.
valueColumn = Your Manual Tag
- Specifies which column in the sheet contains the values we want to set on the matched rows in vScope. In our example, we want to set the values that are found in Your Manual Tag.
apply = false
- Finally the apply parameter decides if changes should actually be applied or not. If set to false then vScope will only return results of what would happen if apply was true. After we’ve confirmed that everything works, we will set apply to true and commit the changed.

This is what our final URL looks like:
https://vscope.example.com/rest/action/bulktag/xlsx?token=1b644eddc79a5f5&resourceType=All%20Machines&matchColumn=Name&matchTag=Name&valueColumn=Your%20Manual%20Tag&apply=false

Step 6 – Set Content-Type

Go to the Headers section in Postman and add Content-Type as Key, and ‘application/octet-stream’ as Value.

Step 7 – Upload XLSX to Postman

Now it’s time to upload the excel file.

Go to the Body section
Check the binary option
Click Select File to upload the xlsx file.

Step 8 – Import the tags to vScope

Import the tags to vScope by clicking Send. The parameter apply that we previously set as ‘false’ allows you to tets the URL out before actually importing. This gives you the chance to see if the API request will work as intended. Test by clicking ‘Send’.

If everything works as intended you’ll get a body response like below. “rowsUpdated” indicates how many values that will be added to vScope. If this amount matches how many columns you have in your XLSX the import will work as intended. You can of course import the excel sheet even if some rows don’t have a match in vScope, simply add the manually in vScope afterwards.

Once you’ve verified the API request will work you can change it to ‘apply=true‘ and Postman will import the tags to vScope.