Using custom actions to populate device attributes
A custom action might populate devices with values captured from the custom action's command output. For example, you might first want to run a custom action to set a value in the device record that is used in a subsequent Deploy to Active span action of a template or rule by using a device substitution parameter. Or, you might want to periodically run a custom action to set values in the device record for reporting purposes.
Custom actions can be used to populate dynamic fields that are text or menu-based. They can also be used to populate the device's imported inventory attribute.
This topic includes the following sections:
Best practices for defining dynamic fields
When defining a dynamic field, you should consider the kind of data being captured from the device. Although, any dynamic field is acceptable, the Value Type that you choose can affect the usability of the system. If the data is unique for each device, you should define the dynamic field as Text because there will be a large range of unpredictable values. If the data belongs to a small range of discrete values such as domain names or netmasks, you should define the dynamic field as a Single-Select menu type. When creating new devices, the menu type provides users a limited selection by displaying a menu on the Device Edit page.
Carefully consider whether you want to enable auto-grouping. If the data is unique per device, do not enable auto-grouping. Enabling auto-grouping would result in a single group per device making it difficult to process group lists.
Populating simple dynamic fields from a custom action
Get System Serial Number is a factory-installed custom action that shows how to populate a device record's dynamic field called Serial Number with the serial number captured by the custom action’s command output.
The custom action supports many device types, including IOS and CatOS. Before running the custom action, create a device dynamic field called Serial Number; specify it as a text field with a maximum length of at least 50 characters.
You must also edit the custom action definition in the device adapter, which is available on the Device Adapter Management page. Export and edit the adapter. Uncomment the lines that tell the system to populate this dynamic field, then import the modified adapter. The following code segment is an excerpt from the factory-installed custom action XML file for IOS:
<name>Get System Serial Number</name>
<guid>045D9DF3-AB31-4BB7-8A60-524F2219CE17</guid>
<browserExecutable>true</browserExecutable>
<approvable>true</approvable>
<inspectionOnly>true</inspectionOnly>
<dynamicField>
<name>Serial Number</name>
<sourceResult>result.pbid</sourceResult>
</dynamicField>
</customDeviceCommandDeclaration>
<!-- ========================================================== -->
<deviceType>
<guid>BE2B2D21-1CAA-53C3-05C3-CBB0A5D151B8</guid>
<extension>true</extension>
<deviceCommand>
<guid>045D9DF3-AB31-4BB7-8A60-524F2219CE17</guid> <!-- Get System Serial Number -->
<interaction>
<prompt>%prompt%</prompt>
<command>show ver</command>
<response>%prompt%</response>
<error>Invalid input</error>
<capture buffer="Processor\s+board\s+ID\s*(\S+)" ignoreFailure="true">
<property name="result.pbid">{1}</property>
</capture>
</interaction>
</deviceCommand>
</deviceType>
</deviceTypeMap>
<name>Serial Number</name>
<sourceResult>result.pbid</sourceResult>
</dynamicField>
<property name="result.pbid">{1}</property>
</capture>
result.pbid is displayed in the Captured Results column of the Job Details report as shown in the following figure:
Examples:
- If you have a text-type dynamic field, the captured value must not exceed the maximum character length specified by the dynamic field.
- If the dynamic field is an integer type, the captured value must be numeric.
By default, invalid values are ignored and are not stored into the device. However, if you try to populate a field that drives auto-grouping, you might want to know about invalid values.
In the custom action declaration, you can specify what error handling should occur when an invalid dynamic field value is detected. Inside the <dynamicField> tag, you can include the <onBadValue> tag with one of the values listed in the following table:
Value | Description |
|---|---|
logEvent | Log a warning-level event to the event log; the action still succeeds. |
failActionMinor | Flag the action as succeeded with warning. |
failActionMajor | Flag the action as failed. |
For example, if the Serial Number text-type dynamic field has a maximum field length of 20, upon executing the following XML snippet, the event log will include a warning event for each captured result.pbid that exceeds a length of 20 characters. The event will specify which device is being processed, which dynamic field is being populated, and the value that fails validation. The failActionMinor and failActionMajor settings specify the dynamic field and value in error.
<name>Serial Number</name>
<sourceResult>result.pbid</sourceResult>
<onBadValue>logEvent</onBadValue>
</dynamicField>
Populating multi-select menu-based dynamic fields from a custom action
To populate multi-select dynamic fields, the declaration is the same as when populating a single value. The following script snippet is from the Get Trunk Interfaces factory-installed custom action:
<name>Trunks</name>
<sourceResult>result.Trunk</sourceResult>
<rejectUnknownMenuOptions>false</rejectUnknownMenuOptions>
</dynamicField>
...
<interaction>
<prompt>%prompt%</prompt>
<command>show int desc | exclude Interface</command>
<response>%prompt%</response>
<error>Invalid input</error>
<capture buffer="(\S+)\s+.*$" multipleValues="true"
ignoreFailure="true" >
<property name="cmd.allInterfaces">{1}</property>
</capture>
</interaction>
<loop variable="Interface" input="cmd.allInterfaces">
<interaction>
<prompt>%prompt%</prompt>
<command>show int %loop.Interface% switchport</command>
<response>%prompt%</response>
<capture buffer="^Operational Mode:\s*(\S+).*"
ignoreFailure="true">
<property name="cmd.operMode">{1}</property>
</capture>
</interaction>
<condition test="(-EXISTS-cmd.operMode) -AND- (%cmd.operMode% -EQ- trunk)">
<assign property="result.Trunk.%loop.Interface%"value="%loop.Interface%"/>
<assign property="cmd.operMode" value=""/>
</condition>
</loop>
The first interaction captures a set of interface names into properties called cmd.allInterfaces.<index>. <index> is a number assigned by the system, starting at zero and ranging up to the number of results that match the pattern. Each value is the interface name taken from the output of the show int desc command.
The second interaction loops over the set of discovered cmd.allInterfaces properties, running a show int switchport command on each; when the output includes the operational mode of trunk, then a property called result.Trunk.<name>, where <name> is the name of the interface.
The system then finds if such a dynamic field exists because the results must populate Trunks, a dynamic field. You must have added it, and to support multiple values, it must be a multi-select menu.
When properties matching the value specified in <sourceResult> are captured, the system erases the device's current values for the specified dynamic field, then finds all the properties named starting with result.Trunk; each property's value is added to the device's setting for this dynamic field.
When no properties matching the value specified in <sourceResult> are captured, the current values are cleared for system-assigned dynamic fields. The values are unchanged for user-assigned dynamic fields to allow a user to assign values manually should a device not support the commands run by the custom action.
The declaration specifies that any values not already in the dynamic field's menu are not to be rejected, but are to be automatically added to the menu. If you instead specify that unknown options are to be rejected, you must predefine the legal range of values in the dynamic field's menu. Any value encountered in a property that is not already in the dynamic field's menu will be ignored.
You can reference the trunk interfaces in a Rule as shown in the following figure. The Rule Domain specification resolves to For each trunk interface.
Populating the Imported Hardware field from a custom action
Each device has an attribute known as the imported inventory. The value stored in it is usually obtained from an external element manager such as CiscoWorks or HP OpenView Network Node Manager during the device import process. The inventory is shown when you view a device, and in the Device Inventory Report. Instead of importing the data from an element manager, you can enter it with relevant information directly from the device.
The following example shows how to populate the imported hardware field of a device from a custom action. This is very similar to storing results of custom actions into dynamic fields.
The differences are as follows:
- For dynamic fields, you need to specify the name of the dynamic field.
- The Imported Hardware field of a device is not limited in size and can capture large text values.
- A device has only a single value for its current imported inventory.
- The imported inventory cannot be referenced in rules.
<name>Show system information for switch</name>
<guid>1676338B-BCE5-48D5-976F-28890E2965BC</guid>
<browserExecutable>true</browserExecutable>
<inspectionOnly>true</inspectionOnly>
<importedHardware>
<sourceResult>result.sys.info</sourceResult>
</importedHardware>
</customDeviceCommandDeclaration>
Related topic