Documentations

Global-Api-Value & Global-Api-Status

On the page

Do you need help?

General information

  • The 2 service models work in the same way. Global-Api-Value processes digital feedback and compares it to thresholds, Global-Api-Status processes a text return and compares it to expected values
  • Both service models support APIs in the REST JSON (which is a market standard) and not other formats (no SOAP, no REST XML, ...)
  • They support the following authentication protocols: no authentication, OAuth, basic-auth

Is named "EndPoint", the end of the URL that can be called via the methods GET or in POSTwith parameters, which returns the results of the query.

Example: with authentication on the URL http://myservice.com/v3/token and the call for information on http://myservice.com/v3/jobs then :

Operating principles 

The plugin provides fields related to authentication. These fields must be used if the API requests authentication via an EndPoint different from the final EndPoint.

This is required for OAuth authentication, or for any API that requires, for example, a token or visa or similar to make the API call.

It is not useful in the context of an API without authentication or an API with basic-authentication on each call.

Authentication

In the case of an authentication, the value collected (token, visa, ...) during the call to the authentication EndPoint is cached with a validity period set in parameter.

Example of implementation with the case of this API: https://helpcenter.veeam.com/docs/vbo365/rest/authorization.html?ver=50#RequestinAuthorization

To make the calls to the EndPoint Jobs, we need to provide a token and not a login and password. So we need to collect the token first, so we will use the authentication EndPoint

The documentation indicates

chrome 2020 12 18 15 51 36
chrome 2020 12 18 15 51 36

So we will fill in the fields like this

URL = https://abc.tech.local:4443/v5

User ID= xxxx

Password = yyyyy

Authentication endpoint = /token

Method for authentication = POST

Authentication Header = Content-Type: application/x-www-form-urlencoded

Authentication body = grant_type=password&username=%login%&password=%password%

Identification field: access_token

Cache validity = 60

Explanation of the fields : 

  • Authentication body : We replace the login by %login%. This allows to get the value of the ServiceNav login field and to benefit from the management of the supervision accounts. Same for the password replaced by %password%. Be careful not to replace the password with "grant_type=password" because it is to indicate the type of authentication to the API (it is a choice of the developer of the API)
  • Identification field: This is the name of the field that returns the value we need for the next call. It is here directly at the root of the response, i.e. at level 1 of the Json so we just put its name.

Call to the API

Here in the example we want to retrieve the last status of the backup jobs (https://helpcenter.veeam.com/docs/vbo365/rest/get_jobs.html?ver=50)

chrome 2020 12 18 16 07 41
chrome 2020 12 18 16 07 41

We will fill in the fields like this:

Field EndPoint = /Jobs

Field Method = GET

Field Header Authorization: Bearer %auth%     | Here %auth% is automatically replaced by the value retrieved in the "access_token" field indicated in the Identification field in the previous call.

As shown in the example the API returns an array with many information for each save job, so the service model will look at each element of the array and do the analysis according to the information returned for each element of the array

The following fields should be filled in as follows:

Field Tree structure = . This field is used to position itself at the beginning of the array. Here in the example the API returns the array directly, so empty.

Field Filter = name. This is the field on which the white and black lists will be applied, in this case the name of the backup job. 

Field Values lastStatus. This is the field for which the returned value will be taken into account for the analysis (thresholds or text)

If the API was in the following format 

image

Field Tree structure should be " table "→ so we position ourselves at the table level, which becomes our new frame of reference for analysis

Field Filter should be " Information>name" . → We are at the table level, to get the job name we go to Information and collect name

Field Value should be " Result>lastStatus" . → We are at the table level, to get the status of the job we go to Result then lastStatus

Advanced use

Case 1

In Tree, Filter and Value it is possible to replace the text with the position in the table.

For example, if the API returns the following

image 1

The documentation tells you that there are always the last 3 runs, and you want to have the last status in the service.

the field Tree structure must be → so we position ourselves at the highest level

the field Filter must be "name". → we will filter (white and black list) on the names of the jobs

the field Value must be "lastresults>2>executionstatus". → We'll go down into lastresults, come up with an array, take the 3rd value, so we'll indicate 2 (an array starting all the time at 0) and then take the value associated with executionstatus.

It is possible to use in the field Value "lastresults>-1>executionstatus" to get the last value of the array (-2 for the second last one ...)

Case 2

For example, if the API returns the following

image 2

The documentation tells you that there are always the last 3 runs, and you want to have the last status in the service.

the field Tree structure must be → so we position ourselves at the highest level

the field Filter must be "name". → we'll filter (whitelist and blacklist) on the job names

the field Value must be "lastresults>2>1". → We'll go down lastresults, we come to an array, we take the 3rd value, so we indicate 2 (an array starting all the time at 0), we come to another array and we want the second value.

Using the value mask

Here we query a device that returns the temperature for each fan, the answer is in the following format:

image 3
image 3

The field Tree structure must be → so we position ourselves at the highest level

The field Filter must be "name". → we'll filter (whitelist and blacklist) on the fan names

The field Value must be "Temperature". 

Problem: the returned values are texts (not numbers) with the presence of C in the return. We want to keep only the numeric value, so the value mask field contains : [0-9]+

You may also be interested in

word image 10

Using the Global-Plugin-Execution service model

ps 1

Using PowerShell generic templates - GLOBAL-PS-Values

Configure the box to receive traps

en_GB

Welcome to ServiceNav!

Do you need some help? More information about our products? Write to us!
You have taken note of our privacy policy.
We use cookies to ensure the best experience on our site. If you continue to use this site, we will assume that you are satisfied with it.

Reserve your place

You have taken note of our privacy policy.