General information

• The 2 service templates work in the same way. Global-Api-Value processes numeric returns and compares it to thresholds, Global-Api-Status processes a text return and compares it with expected values
• Both service templates 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

The end of the URL, called "EndPoint", can be called via the methods GET or in POSTalong with 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 :

• URL = http://myservice.com/v3
• Authentication endpoint = /token
• EndPoint = /jobs

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 target EndPoint.

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

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

Authentication

In the case of authentication, the value collected (token, ...) during the call to the authentication EndPoint is cached with a validity duration set as a parameter.

Example of implementation using 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 says

So we will complete the fields as follows:

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 login by %login%. This allows to use the value of the ServiceNav login field and to benefit from monitoring account management. Similarly for the password being replaced by %password%. Be careful not to replace the password with "grant_type=password" because this indicates the type of authentication to the API (it being the choice of the API developer)
• Identification field: This is the name of the field that returns the value we need for subsequent calls Here it is directly at the root of the response, i.e. at level 1 of the Json so we just give its name.

Calling the API

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

So we complete the fields like this:

Field EndPoint = /Jobs

Field Method = GET

Field Header = Authorization: Bearer %auth%     | Here %auth% is automatically replaced by the value retrieved from the "access_token" field stipulated in the 'Identification field' of the earlier authentication call.

As seen in the example, the API returns an array with a variety of information for each backup job, so the service template will look at each element of the array and perform analysis according to the information returned for each element of the array

For this example, the following fields should be completed as follows:

Field Tree structure = . This field is used to position the API call at the beginning of the array. In this example the API returns the array directly, so leave this field empty.

Field Filter = name. This is the field against which the white and black lists will be applied, in this case the name of the backup job(s) to include /exclude from being checked. 

Field Values = lastStatus. This is the field for which the returned value will analysed (thresholds or text)

If the API returned information in the following format: 

Field Tree structure should be " tableau "→ so we position ourselves at the table level, which becomes our starting point for analysis

Field Filter should be " Informations>name" . → We are at the table level, to get the job name we go to 'Informations' 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 usage

Case 1

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

If the API returns the following:

The documentation tells you that the last 3 job runs are always stored, but you want to monitor the last status in the service.

the field Tree structure must be left empty → so we position ourselves at the top 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>executionstatut". → We'll go down into 'lastresults' and take the 3rd value in the array, so we'll indicate 2 (an array always starts at 0) and then take the value associated with 'executionstatut'.

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

Case 2

If the API returns the following:

The documentation tells you that the last 3 job runs are always stored, but you want to monitor the last status in the service.

the field Tree structure must be left empty → so we position ourselves at the top 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 filter

In this example, we query a device that returns the temperature for each fan, returned in the following format:

The field Tree structure must be left empty → so we position ourselves at the top 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 text (not numbers) note the presence of C in the output. We want to keep only the numeric value, so the value filter field contains : [0-9]+ to strip out the "C" character