General information
- Both service models operate in the same way. Global-Api-Value processes a numerical return 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 format REST JSON (which is a market standard) and no other formats (No SOAP, no REST XML, ...)
- They support the following authentication protocols: no authentication, OAuth, basic-auth
Is named "EndPoint", the end is the URL that can be called via the methods GET or in POSTwith parameters, which returns the results of the query.
Example: with an authentication on the URL http://myservice.com/v3/token and the call for information on http://myservice.com/v3/jobs So..:
- URL = http://myservice.com/v3
- Authentication EndPoint = /token
- EndPoint = /jobs
Principles of operation
The plugin offers fields related to authentication. These fields must be used if the API requires authentication via a different EndPoint than the final EndPoint.
This is required for OAuth authentication, or for any API that requires a token or visa or similar to call the API.
It is not useful for an API without authentication or an API with basic-authentication on every call.
Authentication
In the case of authentication, the value collected (token, visa, ...) when calling the authentication EndPoint is cached with a validity period set in parameters.
Example of implementation with the case of this API : https://helpcenter.veeam.com/docs/vbo365/rest/authorization.html?ver=50#RequestinAuthorization
To make calls to the EndPoint Jobs, you must provide a token and not a login and password. So we first need to collect the token, so we will use the EndPoint Authentication
The documentation indicates

So we will fill in the fields like this
URL = https://abc.tech.local:4443/v5
Identifier= xxxx
Password = yyyy
Authentication EndPoint = /token
Authentication method = POST
Authentication Header = Content-Type: application/x-wwww-form-urlencoded
Authentication body = grant_type=password&username=%login%&password=%password%
Identification field: access_token
Validity of the cache = 60
Explanations on the fields :
- Authentication body: We replace here the identifier by %login% this allows to get back the value of the ServiceNav identifier field and to benefit from the monitoring accounts management. Same for the password replaced by %password%. Attention we do not replace the password of "grant_type=password" because it is to indicate the type of authentication to the API (it is a choice of the API developer).
- Identification field: This is the name of the field that returns the value we will need for the next call. It is here directly at the root of the answer, i.e. at level 1 of the Json so we just put its name.
Call for 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)

So we're going to 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 specified in Identification field in the previous call.
As shown in the example, the API returns an array with a lot of information for each backup job, so the service model will look at each element of the array and perform the analysis according to the information returned for each element of the array.
Therefore, the following fields should be filled in like this:
Field Tree structure = Empty. This field is used to position at the beginning of the table. 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 then be applied, so here is 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

Field Tree structure should be " table "→ so we're positioning ourselves at the table level which becomes our new analysis repository.
Field Filter should be " Information>name« . → We're at the table level, to get the job name we go to Information and collect name.
Field Value should be " Result>lastStatus« . → We're at table level, to get the job status we go to Result then lastStatus.
Advanced use
First scenario
At the level of Tree, Filter and Value it is possible to replace the text by the position in the table.
For example, if the API return is as follows

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
the field Filter must be "name". → we're going to filter (black and white list) on the names of the jobs.
the field Value must be « lastresults>2>executionstatut ». → On va descendre dans lastresults, on arrive sur un tableau, on prends la 3e valeur, donc on indique 2 (un tableau débutant tout le temps à 0) et on prend ensuite la valeur associée à executionstatut.
Il est possible d’utiliser dans le champ Value « lastresults>-1>executionstatut » pour récuperer la dernière valeur du tableau (-2 pour l’avant dernière …)
Second scenario
For example, if the API return is as follows

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 empty → so we're positioning 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>1". → We'll go down to lastresults, we arrive on a displayboard, we take the 3rd value, so we indicate 2 (a displayboard starting all the time at 0), we arrive on another displayboard and we want the second value.
Using the value mask
Here we ask a device that returns the temperature for each fan, the answer is in the following format:

The Tree structure must be empty → so we're positioning ourselves at the highest level.
The Filter must be "name". → we will filter (white and black list) on the fan names
The 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 numerical value, so the value mask field contains : [0-9]+