Using TPL to enrich discovered data

While standard discovery processes can provide most key information, there are times when you may want to track information that is not available to discovery. A good example of this type of information is the exact location of a host. In most situations, there is nothing discoverable on a host that allows you to know that it is located in U23 of Rack 15 in Data Center 2 of the Houston campus. While the most common example of this is to track the location of hosts, similar approaches could be employed for relating hosts to organizational units, or owners.

BMC Atrium Discovery makes it very easy for you to extract information from external data sources and include it in its own data. Commonly, customers may use these capabilities for:

  • Relating hosts to locations using a host naming scheme
  • Reading location information from a file or registry setting
  • Using a table in a pattern to relate subnets to locations
  • Querying an SQL database for location information

These are described in the sections below.

In the TPL code (patterns) snippets, logging and basic error checking is shown in line with BMC Software recommendations. When you are developing patterns, you need to run them outside a normal discovery run against previously scanned host. For information on doing this, see Manual pattern execution.

Location using a naming scheme

The template_host_location template pattern shows you how to relate hosts to locations based on hostname. This pattern relies on a naming scheme in which hostnames contain a location identifier such as lon for London, or hou for Houston.

See Template patterns for a description of all template patterns supplied on the appliance.

Reading location from a file

A common way of incorporating location information into a host is to store a file in the host's file system. The template_si_version_xml_file template pattern demonstrates taking information from an XML file to version an SI. The same approach can be used to extract location information from an XML file.

If the information is stored in an XML file use xpath as shown in the template pattern. The TPL xpath functions are described in the TPL Guide. In the case where information is placed in a flat file, a simple regex is the most effective method of extracting the location. The TPL regex functions are described in the TPL Guide.

The full specification of the regular expression syntax used in BMC Atrium Discovery can be found on the Python website. A simpler introduction is also available.

Here is an example XML snippet for a file:

<?xml version="1.0"?>

<config>
   <physical>
      <location="Houston">
      ...

Here is the TPL which retrieves the file and uses xpath to obtain the location from the file:

    // Get config file and check that it was retrieved successfully
    cfgfile := discovery.fileGet(host, cfgfilePath);
    if cfgfile then

        // Extract location from conf file
        location := xpath.evaluate(cfgfile.content, raw '/config/physical/@location');

Now you can create or update the relationship between the host and location node. The following code snippet uses the model.uniquerel function to create or update the relationship.

    // Relate host to location. Using "uniquerel" rather than "rel" means that
    // any existing Location relationships between this Host (the first 
    // parameter) and any Location nodes other than the one given (the second
    // parameter) are removed. If a host has changed location, this keeps the
    // model up-to-date.
    log.info("Subnet_2_Locations: model.uniquerel.Location %host% %location%");
    model.uniquerel.Location(
       ElementInLocation := host, 
       Location := location
    );

See the template_si_version_xml_file template pattern for an example of how these statements are used in the pattern.

Reading location from a registry key

Some administrators may prefer to place information in a registry setting rather then the files used in the previous section. The template pattern template_si_version_registry demonstrates extracting information from the registry to version an SI. The same approach can be used to extract location information from the registry.

    // Get the registry key
    location := discovery.registryKey
                   (process, "HKEY_LOCAL_MACHINE\\HARDWARE\\DESCRIPTION\\System\\Location");

Using a table in a pattern to relate subnets to locations

Subnets can be used to identify locations of hosts. You can extend the template_host_location pattern to map subnets to locations. The following TPL snippet shows how you could use a table to map the subnet to hosts. You could also hard code a mapping of hostnames to locations if that information is available. See TPL Guide for more information on tables.

table SubnetLocations 1.0

    "101.10.10.0/24" -> "London Victoria";
    "101.10.11.0/24" -> "London Egham";
    "137.72.94.0/24" -> "Houston";
    "137.72.95.0/24" -> "Dallas";
    default -> "unknown";

end table;

The following TPL snippet shows the search from the host to associated subnet or subnets.

    subnet_list := search(in host traverse DeviceWithInterface:DeviceInterface:InterfaceOfDevice:NetworkInterface
                                  traverse DeviceOnSubnet:DeviceSubnet:Subnet:Subnet);
    location_id := '';
    list_size := size(subnet_list);
    log.debug("Subnet_2_Locations: subnet_list size is %list_size%");
    
    for subnet_node in subnet_list do
        log.debug("Subnet_2_Locations: Current subnet_node is %subnet_node.ip_address_range%");
        
        // if subnet_node is "None" get next node otherwise we can use this one
        if '%subnet_node.ip_address_range%' <> "None" then
            location_id:= '%subnet_node.ip_address_range%';
            break;
        end if;
    end for;

This TPL snippet uses the table to look up the location from the subnet.

    // Look up the location name from the table
    location_name := SubnetLocations[location_id];

Querying an SQL database for location information

The template_sql_asset_integration template pattern is supplied with BMC Atrium Discovery which enables you to extract location information from an SQL database. To query a database you must define the asset database in the pattern and activate the pattern. After activation, this creates an integration point into which you add connection information. For information on using integration points to connect to databases, see Integration points.

Automatically creating locations

The pattern examples above have shown a number of ways of determining locations and how to create the relationship between host and existing location nodes. The following code snippet shows how you can create or update a location node, asserting that the location exists.

    // Create or update a Location node for this. For a list of attributes for
    // Location nodes, see Administration > Taxonomy. Every attribute used on 
    // the node in the "location_row" variable must be returned by the query's
    // SELECT statement.

    log.debug('Setting location of %host.hostname% as %location_row.address%');
    
    location_node := model.Location(
      key  := text.hash("%location_row.name% %location_row.address%"),
      name := location_row.name,
      address := location_row.address
    );
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Timothy Onyskin

    I'm having a hard time when building my locations to get teh model.Location to make the location active. What is the correct syntax for that?

    Sep 04, 2012 01:59