About substitution parameters
You can use substitution parameters in configuration templates, rules, and other areas to support reusability.
Substitution parameters syntax
The following table defines the substitution parameters that are available in TrueSight Network Automation:
Component | Substitution parameter description and usage |
|---|---|
Device | Substitutes an attribute from the device inventory. The parameter is device inventory field name. For example, ${device.host} substitutes the Host Name/IP Address value assigned in the device inventory. Valid parameter values include:
Usage: |
Agent | Substitutes an attribute from the device agent. Valid parameter values include:
Usage: |
| Label | Substitutes a localized label for a device attribute or section of attributes as those labels appear inside a TSNA Device Attributes configuration. Note that this is the label or name of the attribute, not its value for a particular device. Valid parameter values include:
Usage: |
Global | Substitutes a globally defined parameter defined under the Admin tab. The parameter is the global parameter name (such as logServer1, ntpServer1, snmpROAcl). For example, Usage: |
Template | Templates can be substituted into rules and templates. The parameter is the template name. A common use of template substitution is managing Access Control Lists (ACLs). For example, all ACLs require a common set of ACL entries. Define the common ACL entries in a template that is substituted into various ACL Rules. Usage: |
Runtime | Substitutes a runtime parameter assigned by the user. The user is prompted to enter the runtime value for the parameter. You can assign a default value (for example, Usage: You can also assign a defined set of options. In this case, the user is presented with the list of options to a runtime value. Usage: Runtime parameters should not be used in policy-based span actions unless default parameter values are assigned and are intended to be used. |
Internal function | Executes an internal or user-defined function and substitutes the function's return value. One level of nested eval or exec inside an eval is permitted. Internal functions can be used to encrypt or update passwords or perform arithmetic operations. |
Password encryption functions
See Updating device passwords for how to use these internal functions for managing password changes. Usage:
| |
Arithmetic functions
Usage:
| |
External program | Executes an external program and substitutes the program's return value.
Usage: |
User-defined function | You can define your own functions. Use the following procedure to define a function:
|
Pod substitution parameters
All pod-related substitution parameters have the basic form ${pod.parameter}. The string indicated by parameter can contain multiple components. See Pod substitution parameter syntax in the BMC Cloud Lifecycle Management on-line technical documentation.
Container substitution parameters
All container-related substitution parameters have the basic form ${container.parameter}. The string indicated by parameter can contain multiple components. See Container substitution parameter syntax in the BMC Cloud Lifecycle Management on-line technical documentation.
Example parameter substitution
Examples are based on Cisco IOS CLI:
hostname ${device.host}
snmp-server community ${global.snmpROCommunity} RO ${global.snmpROAcl}
logging ${runtime.logServer1}
enable secret 5 ${eval encrypt_gnu_md5_b64 ${global.enablepw} ${trigger.1}
enable secret 8 ${eval encrypt_cisco 8 ${global.enablepw} ${trigger.1}
hostname ${exec assignHostName}Example Linux script execution
The following example demonstrates a simple script and how to use ${exec} to execute the script. ${exec} programs or script must be located in the BCAN_DATA/endorsed directory.
The script returns the value my_value.
Create the BCAN_DATA/endorsed/my_script.sh with the following lines:
#!/bin/sh echo my_value- Invoke my_script.sh by using a
${exec} expression:${exec my_script.sh}
Note that the system examines exit code of your script. A zero exit code indicates success, while a non-zero indicates a failure. A failure is reported out in various ways, depending on the context of where this substitution parameter appears. The system might log an event, might log a warning message to the log file of the server, or might display an error message.
Example Windows script execution
The following example demonstrates a simple script and how to use ${exec} to execute the script. ${exec} programs or script must be located in the BCAN_DATA\endorsed directory.
The script returns the value my_value.
Create the BCAN_DATA\endorsed\my_script.bat file with the following lines:
@echo off echo my_value- Copy cmd.exe into the endorsed directory:
copy C:\windows\system32\cmd.exe BCAN_DATA\endorsed - Invoke my_script.bat by using a
${exec} expression:${exec cmd.exe /c my_script.bat}
Substitution parameters applicability
Substitution parameters can be used by the following components:
Component | Adhoc templates | Templates | Rules | Configuration | Configuration | Custom | External | External | Internal | External |
|---|---|---|---|---|---|---|---|---|---|---|
Device | X | X | X | X | X | X | X | X | X | X |
Agent | X | X | X | X | X | X | X | X | X | X |
| Label | X | X | ||||||||
Global | X | X | X | X | X | X | X | X | X | X |
Template | X 1 | X 1 | X | X | X | |||||
Run-Time | X | X | X | X | X | |||||
Internal | X | X | X | X | X | X 2 | X 2 | |||
External | X | X | X | X | X | X 2 | X 2 | |||
Pod | X | X | X | X | ||||||
Container | X | X | X | X |
Footnotes:
- TrueSight Network Automation allows 10 layers of nesting for template substitution parameters in templates.
- TrueSight Network Automation allows 1 layer of nesting for the following substitution parameter and component combinations:
- Internal Function substitution parameters in Internal Functions.
- Internal Function substitution parameters in External Programs.
- External Programs substitution parameters in Internal Functions.
- External Programs substitution parameters in External Programs.
Be cautious when using internal function or external program substitution parameters in CAP queries because they impact the performance of Snapshot and Refresh Device Status span actions.
Some factory installed templates (syslog) and rules reference global substitution parameters. Ensure you create and assign values to these global substitution parameters before using the factory installed templates and rules.
When referring to a Multi Select Menu type of dynamic field, the system replaces the substitution parameter with all values of the dynamic field in sorted order. Be cautious about referring to such dynamic fields because such a list of values might be invalid in context. For example, if you are editing a template, a device might not accept a comma-separated list of values in its command line. Follow these guidelines when referring to such a dynamic field:
- If the text is inside something that carries a regular expression (such as the subject pattern in a rule), the system separates the values with the
|(or) operation. For example:valueA|valueB|valueC. You must include parentheses around the substitution parameter in order for the or operation to have an effect. For example:(${device.myValueList}) is the correct way to refer to a Multi Select Menu dynamic field in a rule. Thus, referring to a Multi Select Menu dynamic field in a regular expression means you are searching for a match on one of its values. - If the text is inside a non-regular expression (such as the subject line in a rule), the multiple values are separated by a comma and a space. For example:
valueA,valueB,valueC.
Comments
Log in or register to comment.