Other LogicModules

Creating PropertySources

PropertySources auto-assign properties at the device-level based on the output of a Groovy script. Automating these property assignations has a wide-range of benefits for improved inventory tracking/reporting, troubleshooting, as well as dynamically grouping devices based on their shared properties.

At a high-level, PropertySources work as follows: your script  interacts with a device, identifies designated systems information (ie. serial number, port speed, firmware version, etc), establishes this information as a key-value pair (ie. port.number=443), and then assigns these key-value pairs as properties on the device.

A PropertySource will run:

  1. Each time the PropertySource is updated.
  2. Each time Active Discovery is manually executed (from Manage | Device)
  3. Automatically once a day

Note: In order for PropertySources to work properly for cloud resources, you'll need to first enable monitoring via local Collector

Configuring your PropertySource

New PropertySources can be added From Settings > PropertySources > Add

You will be asked to complete the following General Information fields:

Name

The unique name of the PropertySource.  As a best practice, this name should be descriptive: specify the platform or application name, then, if necessary, a specific component of the platform.  
 

Description

The description that will be associated with this PropertySource.  As a best practice, if the PropertySource name is not unambiguous as to what the PropertySource is collecting, the description field should provide enough information that someone seeing the name and the description will be clear what the PropertySource does 
 

Group

The PropertySource Group to which the PropertySource will be added.  If this field is left empty, the PropertySource will not be added to a group.  If you enter text that does not match an existing PropertySource Group, one will be created
 

Applies To

The Applies To field defines which devices will be associated with this PropertySource. This field needs to be in Applies To Scripting Language syntax 
 

Configuring your PropertySource  

Drafting a PropertySource Script

PropertySource scripts must be written in a Groovy syntax. 

Please view example PropertySource scripts here

Continuing with the example specified in the above ScreenShot, let's say we want to write a PropertySource that will automatically evaluate against PureStorage arrays during Active Discovery. We want to identify the values of the following systems information and set them as properties on the device: ID, array name, revision, and version number.

To do this, we would use the following script format:

1. Import the Java Helper as JsonSlurper class (used to parse JSON text into Groovy data structures legible for our script)

import java.net.*;
import java.io.*;
import java.util.*;
import java.text.*;
import groovy.json.JsonSlurper;

2. GET the array's hostname and API token, which should be set as properties on your device. Establish these responses as the values for "hostName" and "apitoken" keys, respectively.

hostName = hostProps.get("system.hostname");
apitoken = hostProps.get("purestorage.apitoken.pass");

3. Init (establish API URL in order to start session in Step 4)

base_url           = "https://" + hostName;
arrayInfo_commmand = "/api/1.4/array";
api_url            = new URL(base_url + arrayInfo_commmand);

4. GET session based on API authentication parameters defined in previous step.

cookie = getSession();

5. Open an HTTP connection and issue the arrayInfo request.

connection   = api_url.openConnection();
connection.setRequestMethod("GET");
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/json");
connection.setRequestProperty("Cookie", cookie);

6. Verify whether we received a valid response from our API endpoint

if (connection.getResponseCode() != 200)
{
    // no -- return an error code that indicates failure
    return(2);
}

7. Collect the payload and parse the JSON into a map object.

jsonslurper  = new JsonSlurper();
arrayInfo_map = jsonslurper.parseText(connection.content.text);

8. Iterate over the resultant map

arrayInfo_map.each
{  key, value ->
    // print out each key and value
    println "$key=$value";
}

Script Output

Based on the above script, we would expect an output resembling the following:

array_name=MY-PURE-001
id=93f00dad-b1aa-1234-5678-ec55f5ba55d6
revision=201609291808+e9e9b09
version=4.7.6

These four key-value pairs will be automatically stored as properties on your device. In the event that a value changes, the property will be updated during the next Active Discovery iteration.

PropertySource Example- SNMP OID Query

The following PropertySource is applied to all devices for which the AppliesTo scripting text, isNetApp() evaluates to true.

The PropertySource will return a list of OIDs related to all NetApp devices. Then, it will apply productVersion, productModel, productFirmwareVersion, productSerialNumber, ProductPartnerSerialNumber, and productMachineType, as properties in key-value pair format on their respective devices.

import com.santaba.agent.groovyapi.snmp.Snmp;
// get the snmp host from the device properties
def host = hostProps.get('system.hostname');
// define a list of product oids
def netapp_product_mib =
[
productVersion          : '.1.3.6.1.4.1.789.1.1.3.0',
productModel            : '.1.3.6.1.4.1.789.1.1.7.0',
productFirmwareVersion  : '.1.3.6.1.4.1.789.1.1.11.0',
productSerialNum        : '.1.3.6.1.4.1.789.1.1.14.0',
productPartnerSerialNum : '.1.3.6.1.4.1.789.1.1.15.0',
productMachineType      : '.1.3.6.1.4.1.789.1.1.16.0',
];
// iterate over each oid entry
netapp_product_mib.each
{ key, oid ->
    // retrieve the oid and print the value
    value = Snmp.get(host, oid);
    println "auto." + key + "=" + value;
}
return(0);

Test Script 

The "Test Script" functionality will prompt you to select a device against which you can test the PropertySource's ability to properly assign designated properties. 
 

Managing PropertySources

Once you have created a PropertySource, you will be able to view it in the Settings | LogicModules | PropertySources page.

In this page, a "More" dropdown menu will display next to the PropertySource's name. From this menu, you can select the following options:

  1. Force device match: this will manually run the AppliesTo to ensure all applicable devices are captured and associated with this PropertySource.
  2. Show associated devices: this will display a table containing all the devices impacted by this PropertySource.
  3. Export: this will automatically export your PropertySource as a JSON file.