Additional functions to call in patterns are described in definitions blocks. In Foundation 7.2 / TPL 1.2, two types of definitions blocks are supported, both used for integration with SQL databases.

The basic form of a definitions block is:

definitions name version
  """Description of definitions block"""
 
  type := definitions_type;
  other_setting := setting_value;
  ...
  
  define function_name
    """Function description"""
    parameters := param1, param2, ...;
    other_setting := setting_value;
  end define;
  ...
end definitions;

All definitions blocks must have a type specification. Other settings may be required by certain definitions types. The definitions block contains one or more define blocks, describing the functions being defined. All functions that take parameters must have a parameters specification, listing the names of the parameters to the function. (If a function takes no parameters, the parameters specification can be missed out.) Most definitions types also require other settings in the define blocks.

Once defined, functions can be called in patterns with the usual function calling syntax. Definitions can be imported from one module into another, with the usual versioning scheme.

The supported definitions types are as follows:

SQL database integration

Centralised databases – asset databases, for example – are accessed with sql_integration definitions. The definitions block must contain a name setting, which corresponds to the Integration Point in the user interface. Each define block must contain a query setting that contains the SQL query to perform. Parameters are inserted into the query with the usual TPL % interpolation. e.g.

definitions AssetDatabaseDetails 1.0
  """Queries to obtain information from asset database"""

  type := sql_integration;
  name := "Example asset database";
 
  define getLocationOfHost
    """Return details of the location for the given hostname"""

    parameters := hostname;
    query := """select name, address from hosts, locations where
                hosts.id_location = locations.id and hostname = %hostname%""";
  end define;

end definitions;

The defined function is used in a pattern as the function AssetDatabaseDetails.getLocationOfHost. It is called with a single hostname parameter. It returns a list of nodes, one for each row of output from the query. If the query fails in some way, the function returns none. Each row node has attributes named after the columns selected in the SQL query. So, for example, to use the query defined above:

location_rows := AssetDatabaseDetails.getLocationOfHost(hostname := host.name);

if location_rows = none then
  log.warn('Could not retrieve location for host %host.name%');
  stop;
end if;

for row in location_rows do
  // Create / update Location node for this location, with a key made from its name and address.
  loc := model.Location(name := row.name,
                        address := row.address,
                        key := "%row.name%.%row.address%");
  // Relate the Location to the Host...
end for;

SQL database discovery

Database integration is used when there is a single, centralised database to be accessed. Database discovery, on the other hand, is used to perform queries on databases that have been discovered running on discovery targets. It is analogous to running commands on discovered hosts. SQL discovery is specified with sql_discovery definitions. The definitions block must contain a group setting, which corresponds to a Software Credential Group in the user interface.

Like sql_integration definitions, the define blocks in sql_discovery ones require a query setting, which gives the SQL query to be used.

When calling a sql_discovery function, the target for the discovery must be specified via additional parameters. The functions take an endpoint parameter, which is a Host node or DDD node that identifies the target (like the target in built-in Discovery functions). Some database types require additional parameters to identify the target database, and most have a number of optional parameters. See the Driver Documentation for details.