Programmable Configuration

You can write simple Velocity scripts to automatically configure your monitoring resources by pulling data from an HTTP portal (like NetBox), reading local files, SQL databases, or parsing JSON content.

This is ideal for:

• Large environments with hundreds or thousands of resources
• Dynamic infrastructures where resources are frequently added or removed
• Integration with CMDBs or inventory systems

The following Velocity Tools are supported to fetch and transform data into valid configuration blocks:

Tool	Purpose
$http	Making HTTP requests to APIs
$file	Reading local files
$json	Parsing JSON data
$collection	Splitting strings or manipulating collections
$sql	Executing SQL queries on a database
$env	Retrieving environment variables
$date, $number, $esc	Date formatting, number formatting, escaping

Writing Velocity Templates

1. Connect to the Web Interface at https://MACHINE_WHERE_METRICSHUB_IS_RUNNING:31888
2. From the Configuration tab, click Create > New Velocity template
3. In the editor, write your Velocity script to either load resources from:

• an HTTP API
• a local file
• or an SQL Database

4. Click Test to validate your script and preview the generated configuration blocks
5. Click Save
6. When ready, click Apply.

note

In Velocity, use # for directives, ## for comments, and $ for variables.

Loading Resources

From an HTTP API

Use the $http.execute(...) function to execute HTTP requests directly from templates.

$http.execute Tool Arguments

Argument	Description
url	(Required) The HTTP(S) endpoint to call.
method	HTTP method (GET, POST, etc.). (Default: GET). Use $http.get(...) or $http.post(...) to quickly send GET or POST requests without specifying a method
username	Username used for authentication.
password	Password used for authentication.
headers	HTTP headers, written as newline-separated Key: Value pairs.
body	Payload to send with the request (e.g., for POST).
timeout	Request timeout in seconds. (Default: 60).

Example

Suppose your API endpoint at https://cmdb/servers returns:

[
  { "hostname": "host1", "OSType": "win", "adminUsername": "admin1" },
  { "hostname": "host2", "OSType": "win", "adminUsername": "admin2" }
]

You can dynamically create resource blocks using:

resources:
#set($hostList = $json.parse($http.get({ "url": "https://cmdb/servers" }).body).root())

#foreach($host in $hostList)
  #if($host.OSType == "win")
  $host.hostname:
    attributes:
      host.name: $host.hostname
      host.type: windows
    protocols:
      ping:
      wmi:
        timeout: 120
        username: $host.adminUsername
        password: $http.get({ "url": "https://passwords/servers/${host.hostname}/password" }).body
  #end
#end

From a Local File

Use the $file.readAllLines(filePath) function to read all lines from a local file.

$file.readAllLines Tool Arguments

Argument	Description
filePath	(Required) The path to the local file.

Example

If your CSV file contains:

host1,win,wmi,user1,pass1
host2,linux,ssh,user2,pass2

Use this Velocity template to generate the resource block:

#set($lines = $file.readAllLines("/opt/data/resources.csv"))
resources:
#foreach($line in $lines)
  #set($fields = $collection.split($line))
  #set($hostname = $fields.get(0))
  #set($hostType = $fields.get(1))
  #set($protocol = $fields.get(2))
  #set($username = $fields.get(3))
  #set($password = $fields.get(4))
  $hostname:
    attributes:
      host.name: $hostname
      host.type: $hostType
    protocols:
      $protocol:
        username: $username
        password: $password
#end

From an SQL Database

Use the $sql.query(query, jdbcUrl, username, password, timeout) function to execute SQL queries.

$sql.query Tool Arguments

Argument	Description
query	(Required) SQL query to execute.
jdbcUrl	(Required) The JDBC connection URL to access the database.
username	Name used for database authentication.
password	Password used for database authentication.
timeout	(Optional) Query timeout in seconds (Default: 120).

Example

Consider a hosts table in your database with the following data:

hostname	host_type	username	password
storage-server-1	storage	admin1	pwd1
windows-server-1	windows	admin2	pwd2

You can dynamically create resource blocks by querying the database:

#set($url = "jdbc:h2:mem:management_db")
#set($user = "sa")
#set($pass = "pwd1")
#set($rows = $sql.query("SELECT hostname, host_type, username, password FROM hosts ORDER BY hostname", $url, $user, $pass, 120))
resources:
#foreach($row in $rows)
  #set($hostname  = $row.get(0))
  #set($host_type = $row.get(1))
  #set($username  = $row.get(2))
  #set($password  = $row.get(3))
  #if($host_type.equals("storage"))
  $hostname:
    attributes:
      host.name: $hostname
      host.type: $host_type
    protocols:
      http:
        hostname: $hostname
        https: true
        port: 443
        username: $username
        password: $password
  #end
#end

Using Environment Variables

Use $env.get("ENV_VARIABLE_NAME") to retrieve environment variables in your templates:

#set($apiKey = $env.get("CMDB_API_KEY"))
#set($response = $http.get({
  "url": "https://cmdb/api/servers",
  "headers": "Authorization: Bearer $apiKey"
}))

This allows you to keep sensitive credentials out of your template files.