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:
Nested substitution parameters
Nested substitution parameters allow you to use the result of one substitution parameter as the name or value of another.
The inner parameter is resolved first, and its value becomes part of the outer parameter. This capability helps you create a single, reusable asset such as a rule, template, or script that aligns with device context, for example by domain, site, or location. Nested parameters follow the same applicability rules and resolution model as substitution parameters.
Syntax
Examples
${device.${global.${realm.${agent.name}}}}
${exec my_script.sh${global.LOCAL15_${device.DomainName}}}
For better understanding, here is the explanation of the ${exec my_script.sh${global.LOCAL15_${device.DomainName}}} example.
In this example, TrueSight Network Automation first resolves ${device.DomainName} (for example, fm). It then uses that value to resolve the corresponding global parameter, such as ${global.LOCAL15_fm}, and passes the final resolved value to my_script.sh as an argument.
If ${device.DomainName}= fm and ${global.LOCAL15_fm}= 10.1.1.5 10.1.1.6, the resolved command becomes:
Example parameter substitution
Examples are based on Cisco IOS CLI:
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 your script's exit code. 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, log a warning message to the server's log file, or 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 | 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 |
Realm | X | X | X |
| 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:
- Network Automation allows 10 layers of nesting for template substitution parameters in templates.
- 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.