Discovery formula structure

All the discovery formula files must have the file extension as .discovery.

when clause

Specifies the resource types that are appropriate for executing a specific discovery formula. The components of when clause are as follows:

resource.type
```
resource.type = 'device'
```
Resource type device is discovered by Tivoli® Network Manager in first-level discovery. Currently, only the device resource type is supported by Tivoli Network Manager and resources from the discovered devices are discovered by Network Performance Insight® in second-level discovery.
Note: The value for resource.type must be in single quotation marks.

resource.sysobjectid

You can narrow the discovery to a specific vendor type by specifying the sysobjectid. The sysobjectid represents the type of device and can also indicate the model number in a dotted decimal format. For example:

Table 1. Vendor and model identification numbers
Vendor	OID
Cisco	1.3.6.1.4.1.9
Huawei	1.3.6.1.4.1.2011
Juniper	1.3.6.1.4.1.2636
Juniper Networks/Unisphere	1.3.6.1.4.1.4874

For more information about the vendor and model identification numbers, see IANA-registered Private Enterprise Numbers.

All the discovery files that have the same sysobjectid as that is returned from system-objectid.discovery are run to obtain the resources from those devices.

name.<IP_address>
It is the IP address of an interface or device.

Example

when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.9'

Note: The value for sysobjectid must be in single quotation marks.

select statement

In Network Performance Insight discovery, MIB tables are represented as relational database tables. Hence you can write the discovery definitions in SQL.

Selects data from a table or multiple tables. An SQL statement that retrieves resource properties from the tables that are available in the associated vendor-specific MIB file. The select statement has the following components:

property names

A list of property names and their aliases.

from table expression

Selects data from a table or multiple tables. In this case, it is <MIB _file_name.MIB_table_name>. For example:


when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.9'
select index, ciscomemorypooltype as memoryPoolType, ciscomemorypoolname 
as memoryPoolName, ciscomemorypoolvalid  as memoryPoolValid from 
CiscoMemoryPoolMib.ciscoMemoryPoolTable where ciscomemorypoolvalid = 1
set type = 'memory'
set vendor = 'Cisco'
set name = context.host + '_MemoryPool<' + resource.index + '>'

CiscoMemoryPoolMib is the code representation of the MIB file CISCO-MEMORY-POOL-MIB.
You can get these details by running the bin/snmp-mib-tool pack-demo list command from the Technology Pack Development Tool installation directory.
ciscoMemoryPoolTable is MIB table from CISCO-MEMORY-POOL-MIB file.
You can get these details by running the bin/snmp-mib-tool pack-demo show CISCO-MEMORY-POOL-MIB command from the Technology Pack Development Tool installation directory.

join table expression

Joins tables to combine rows from two or more tables, based on a related column between them. The different types of joins in SQL are as follows:

inner join
Returns records that have matching values in both tables.
left join
Returns all records from the left table, and the matched records from the right table. It is also known as outer join.
right join
Returns all records from the right table, and the matched records from the left table. It is also known as outer join.
full join
Returns all records when there is a match in either left or right table.

Note:

The index column is a special column that discovery adds automatically to the MIB tables. It contains the MIB index details.
If the select statement contains joins with multiple tables and the column name is not unique for a table, then you must add the MIB table name to qualify the column name. For example, ciscoMemoryPoolTable.index.
In V1.3.1, there is no support for scalar MIBs.

where condition

The where condition is used to extract only those records that fulfill a specified condition.

Operators

You can use all the SQL supported operators in the select statements. Typically, the following operators are used in the predefined discovery formulas.

like: The like operator is used in a where clause to search for a specified pattern in a column.
IN: The IN operator allows you to specify multiple values in a where clause.
ON: ON represents one or more JOIN conditions by which to match the records from one table to another.

Example


select hwEntityStateTable.index, hwEntityAdminStatus, hwEntityOperStatus, 
hwEntityStandbyStatus, hwEntityTemperature, entPhysicalTable.index, entPhysicalIndex, 
entPhysicalDescr, entPhysicalVendorType, entPhysicalName, entPhysicalClass from 
HuaweiEntityExtentMib.hwEntityStateTable left join EntityMib.entPhysicalTable on  
hwEntityStateTable.index = entPhysicalTable.index where entPhysicalClass = 6

Note: You can use complex nested select statements to create your discovery formulas by using the Technology Pack Development Tool.

set definitions

Discovery formulas provide an additional way to add resource properties. The set definition can contain a literal string, or combination of discovered properties, or special placeholder called context. For example:


set type = '<resource_type>'
set vendor = '<vendor>'
set id = context.host + '_<resource_name>:<' + resource.index + '>'

The expressions in the set definitions are as follows:

context
context is the special place holder that is used in the discovery formulas. It contains the following two components:
- host
  The context.host string returns the host name of the device. In this case, it is the IP address of the device that is returned from Tivoli Network Manager.
- port
  The context.port string returns the SNMP port number of the device.

The expression,

set name = context.host + '_Huawei_PowerSupply:<' + resource.index +
'>'

results in the name as:

10.55.239.56_Huawei_PowerSupply:<1835017>

Example


set type = 'card'
set vendor = 'Huawei'
set id = context.host + '_Huawei_PowerSupply:<' + resource.index + '>'

unset definitions

Unset removes or deletes the specified set values.

Example


unset jnxfilleddescr
unset jnxoperatingcontentsindex
unset jnxoperatingl1index
unset jnxoperatingl2index
unset jnxoperatingl3index

Note: The set and unset definitions support JavaScript expressions.

Required properties

type
Resource type to which the resource that is discovered belongs to. The resource types can be configured from Resource Types page in System Configuration on Dashboard Application Services Hub portal.

In Cisco devices, it can be memory, temperature, fan, cpu, and others.

For more information, see Configuring resource types.
vendor
Vendor device to which the discovery formula is applicable.
id
The resource on the device for which the discovery is to be done.
index
Index number of the resource.

Stitch definitions

Create a discovery file with stitch definitions. The format of the syntax is as follows:

RELATE <source_resource_type> TO <target_resource_type> AS <relation_type> WHEN <filtering and joining conditions>

Note:

You can specify multiple releate conditions.
The when clause meant for two purposes; condition for joining source and target resources and filtering unrelated relate rules for a device's resources.
The definition file must not be shared with the discovery definitions above.

For example:

Relate interface To channel AS contain when source.AP_Name == target.AP_Name && source.ap_slot_Id == target.ap_slot_Id && source.vendor == 'Cisco'

SNMP bulk get

Packs such as Huawei NQA require to get stats values from tables that have dynamic or running indexes. It is not possible to obtain these indexes during discovery.

During discovery, the index property must have static indexes and for dynamic indexes, it must be replaced with *. For example:

when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.2011'
select * from NqaMib.nqaAdminCtrlTable
set vendor='Huawei'
set type='probe'
set id='HuaweiNQA<'+resource.index+'>'
set index=resource.index+'.*'

Note:

set
index = resource.index + '.*'

appends '*' to the end of index property.

Examples

Some vendor-specific discovery formula examples:

Cisco

cisco-powersupply.discovery


when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.9'
select index, ciscoenvmonsupplystatusdescr as envPowerSupplyStatusDescription, 
ciscoenvmonsupplystate as envPowerSupplyState, ciscoenvmonsupplysource as 
envPowerSupplySource from CiscoEnvmonMib.ciscoEnvMonSupplyStatusTable 
where ciscoenvmonsupplystate!=5
set type = 'environment'
set vendor = 'Cisco'
set id = context.host + '_PowerSupply:<' + resource.index + '>'

Juniper

juniper-chassis.discovery


when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.2636'
SELECT jnxContentsTable.index, jnxOperatingContentsIndex, jnxOperatingL1Index, 
jnxOperatingL2Index, jnxOperatingL3Index, jnxOperatingDescr as 
jnxOperatingDescription, jnxContainersIndex, jnxContainersView, 
jnxContainersLevel, jnxContainersDescr as jnxContainersDescription, 
jnxFilledState, jnxFilledDescr as jnxFilledDescription, jnxFilledContainerIndex, 
jnxContentsContainerIndex, jnxContentsSerialNo, jnxContentsRevision, jnxContentsPartNo 
FROM JuniperMib.jnxContentsTable 
INNER JOIN JuniperMib.jnxContainersTable ON jnxContentsTable.jnxContentsContainerIndex 
= jnxContainersTable.jnxContainersIndex 
INNER JOIN JuniperMib.jnxFilledTable ON jnxContentsTable.index = jnxFilledTable.index 
INNER JOIN JuniperMib.jnxOperatingTable ON jnxContentsTable.index = 
jnxOperatingTable.index
WHERE jnxOperatingDescr NOT LIKE '%temp sensor%' AND (jnxOperatingDescr LIKE '%SSB%' OR 
jnxOperatingDescr LIKE '%SCB%' OR jnxOperatingDescr LIKE '%SFM%' OR jnxOperatingDescr 
LIKE '%FEB%' OR jnxOperatingDescr LIKE '%FPC%' OR jnxOperatingDescr LIKE '%PIC%' OR 
jnxOperatingDescr LIKE '%midplane%')
AND jnxContainersLevel = 0
set type = 'chassis'
set vendor = 'Juniper'
set id = context.host + '_Chassis:<' + resource.jnxoperatingcontentsindex + '>
<' + resource.jnxoperatingl1index + '><' + resource.jnxoperatingl2index + '>
<' + resource.jnxoperatingl3index + '>'

Juniper ERX

junipererx-module.discovery


when resource.type = "device" and resource.sysobjectid like "1.3.6.1.4.1.4874"
select 'module' as type,juniSystemSlotTable.index,junisystemslotstatus,
junisystemslottype, juniSystemModuleTable.index,junisystemmoduleoperstatus 
as ModuleOperStatus, junisystemmodulecurrenttype as ModuleType from 
JuniperSystemMib.juniSystemSlotTable 
LEFT JOIN  JuniperSystemMib.juniSystemModuleTable ON 
JuniperSystemMib.juniSystemSlotTable.index =  
JuniperSystemMib.juniSystemModuleTable.index where  junisystemslotstatus =4 
and junisystemslottype IN(1,2,16,17,18) and junisystemmodulecurrenttype IS NOT NULL
set vendor = "Juniper"
set CLASSNAME = "JuniperERX"
set id = context.host + "_JuniperERXModule:<" + resource.index + ">"

Huawei

huawei-powersupply.discovery


when resource.type = 'device' and resource.sysobjectid like '1.3.6.1.4.1.2011'
select hwEntityStateTable.index, hwEntityAdminStatus, hwEntityOperStatus, 
hwEntityStandbyStatus, hwEntityTemperature, entPhysicalTable.index, entPhysicalIndex, 
entPhysicalDescr, entPhysicalVendorType, entPhysicalName, entPhysicalClass from 
HuaweiEntityExtentMib.hwEntityStateTable LEFT JOIN EntityMib.entPhysicalTable ON
  hwEntityStateTable.index = entPhysicalTable.index where entPhysicalClass = 6
set type = 'card'
set vendor = 'Huawei'
set id = context.host + '_Huawei_PowerSupply:<' + resource.index + '>'