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 → so we're positioning ourselves at the highest level

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]+