Skip to main content

JSON Interface

A JSON Interface will be used when you need to connect to restFUL databases. This guide aims to explain how you can configure your new JSON interface when needed.

The JSON interface is made up of a base address and a request URI that return a JSON or XML result.

XML to JSON

If the result is XML, it will be automatically converted to JSON.

Configuration​

After installing a new JSON interface following these instructions, you are ready to configure your interface.

dashboard22
Training

Refer to Visual KPI training to learn all about how Visual KPI interfaces reads from thousands of data sources and how to create your own interfaces.

All REST-based interfaces have some components in common that need to be set:

  • Base address: The URL to the database API.
  • Request URI: Specifies the Base Address and Date Time Format to traverse the JSON object and retrieve values and timestamps.
  • Result base path: The path to the data you need inside the JSON.
  • Value field: The value field name in the JSON.
  • Timestamp field: The timestamp field in the JSON.
Info

The base address together with the request URI will form a URL that returns the JSON data.

JSON Security Settings​

Most restFUL databases have some sort of security implemented on them. These are usually handled by an authentication method. You will need to configure this into your Interface. To do so, do the following:

  1. Click on your newly created interface.
  2. Navigate to JSON security settings and configure the needed fields:
    • Authentication type: Select the type of authentication needed for this API.
    • User credentials: Click the "..." button and add the credentials needed to access the API.
Public APIs

If the API doesn't require authentication, you can skip this process.

JSON Base Settings​

In the interface settings, you can find the JSON Base Settings, which allows you to configure:

  • Base Address: Configure the API's base address.
  • Date Time Format: Set the DateTime format of the API.
  • Result Data Format: Inform the type of data the API returns (JSON or XML).

Using the example below as base address, you can see how you can parameterize it:

  • Base Address: http://demo.example.com/apitest/api/training?machine=server1

How to access JSON data​

To complete the result base path, value field and timestamp field, you need to understand how to access information in a JSON. Using the JSON below as example:

  {
    "message": "Transpara LLC Training",
    "data": {
      "ip_address": "192.168.1.100",
      "CPU": 45.6,
      "memory": 65.2,
      "temperature": 38.5,
      "timestamp": "2024-02-19T12:30:00Z"
    }
  }

To use CPU as the Value field, and timestamp as the Timestamp field, you need to use dot notation to reach the required data:

  • Value field: response.data.CPU
  • Timestamp field: response.data.timestamp

In Visual KPI Server Manager, you need to add the following for each configuration field:

FieldValueParameterized
Result base pathdata.{1}
Value fieldCPU{2}
Timestamp fieldtimestamp{3}
Parameterizing

These fields can be parameterized.

JSON Query Settings​

Under the JSON Query Settings section, you will need to configure the following fields:

Current Value​

The current value requires you to configure:

  • Result base path: {1}
  • Value field: {2}
  • Timestamp field: {3}

Where, in Visual KPI Designer, you would use server1|data.|CPU|timestamp as the lookup.

Trend Data​

Trend Data requires a start and end date to display the trend of a KPI. These can be added in the Request URI, as exemplified below:

  • Result base path: data.
  • Value field: CPU
  • Timestamp field: timestamp
  • Request URI: &start=2024-02-17T12:30:00&end=2024-06-15T12:30:00
Parameterizing

The start and end values can be parameterized using STARTDATE and ENDDATE.

Historical Value​

The historical value requires a specific date, as it needs to retrieve a value at or before a given date. For this, a timestamp parameter needs to be added in the request URI:

  • Result base path: data.
  • Value field: CPU
  • Timestamp field: timestamp
  • Request URI: &date=2024-06-15T12:30:00
Parameterizing

The date value can be parameterized using TIMESTAMP.

Historical Data​

The historical data requires a specific date, as it will gather all data until the set date. For this, a timestamp parameter needs to be added in the request URI:

  • Result base path: data.
  • Value field: CPU
  • Timestamp field: timestamp
  • Request URI: &date=2024-02-17T00:30:00
Parameterizing

The date value can be parameterized using TIMESTAMP.

Feedback