API DocsAdmin GuideUser GuideVideo Library

How to write Command Portion in Template

Command Format

Plain command format

(Writing Device Command as it is)

  1. In plain command format, the user writes the device commands defined by the vendor. This format will be used only inside the Command Execution & Network Diagnosis template type but not in Download Job Profiles, OS Upgrade Job, Configuration Trigger, Policy Rules, and Remedy.

  2. Though it is simple to write the template in this format, it is not recommended since it does not allow additional information to be added to the command, such as command timeout, response prompt, and error check condition on response.

  3. The timeout for each command using plain command format is always 30 seconds, and each command takes the full 30 seconds even if the execution has been completed before.

XML Command Format

  1. In XML command format, each command is enclosed in an XML node, and additional input to the command, like command timeout, prompt, expected pattern, previous match, and action, is added to the XML node properties.

  2. The XML command format is recommended for all NCCM features, including Download, Upload, Upgrade, and Diagnosis.

Sample command portion for changing Device hostname in plain text format and XML format:

Plain Format

XML Format

conf t

hostname

newname

exit

<command prompt=”#” timeout=”10”>conf t</command> <command prompt=”#” timeout=”10”>hostname newname</command>

<command prompt=”#” timeout=”10” action=”exit”>exit</command>

In the above example, the plain format takes the device command as it is the same way the command is executed using Putty or extreme application. Still, in XML Format, each device command will be placed inside the XML node “Data” section, and other information in the XML node property section.

XML Command Syntax

<command property1=”value” property2=”value”> Device Command </command>
                           ————————————————   ——————————————
                          Command Properties  Actual Command

XML Command Sample

<command prompt=”#” timeout=”10”>hostname newname</command>

The device command for every device will be inside the Data portion of the XML Node, and the additional properties or information will be inside XML’s property portion. The property value must always be inside the Double quotes character.

Command Properties

NCCM supports the following properties:

timeout

Value (in seconds). Every command execution is considered complete until the prompt pattern value is matched or till the timeout second count is reached.

prompt

It is generally the last character of the command response that informs the command execution completion of a Device. When the response from the Device does not match the prompt, command execution is considered as COMMAND ERROR.

prompt=”#”

a. The prompt can be a single character, a word, or a line.

prompt=” #”
prompt=”Router27#”
prompt=”[Are you confirm the reboot action]?”

b. The prompt value is always a regex pattern, and it can be escaped using \ to make an exact match. Below example. (Dot) regex character is escaped with \ to consider it literally as ‘.’ (Dot) and not as a regex pattern.

prompt=”\.”

Follow the URL https://regex101.com/ to verify or check the regex pattern before saving the template.

c. The prompt also supports multiple patterns (multiple single characters or multiple words) to match the command execution completion

prompt=”[#,>,\$]”
prompt=”[Username, login, User]”

d. When the given prompt is not matched within the specified timeout seconds, NCCM will declare it a Command error and stop or continue the execution based on Task IP/Command continuation input from Upload Job task input.

action

This property is used to:

a. Inform NCCM that the exit command is executed and to not wait for a prompt.

action=”exit”

b. Inform NCCM to store the result of the command for storing the device's configuration output and copy the command output for Trigger parsing.

action=”output-to-store”

shell

  • The “shell” property is used to Inform NCCM to open a remote session (TELNET or SSH) from a Device for further command executions.

shell=”remote”
<command      shell="remote"       prompt="Password">     ssh     -o    
StrictHostKeyChecking=no     -o            UserKnownHostsFile=/dev/null    
{{Profile.ssh_loginname}}@{{Device.IPaddress}}     -p     {{Profile.ssh_port}}    
</command>

error_pattern

  • The “error_pattern” property checks the command response; if the pattern values match the command response, command execution is considered COMMAND ERROR. Similar to the prompt property, error_pattern can take multiple values.

Note: The prompt property checks for command completion; however, the error_pattern property checks whether the response is as expected. 

error_pattern="[Unknown command, Invalid Command]"

Example: when the “copy tftp” command is not supported by a device, the response will be %Error opening tftp, and the error_pattern to catch the error will be

error_pattern="[%Error opening tftp]"

no_banner_check

In the configuration template, banner checking is determined using binary values:

  • 1 – Indicates that the banner data should be checked.

  • 0 – Indicates that the banner data should be ignored.

When a device responds after entering the username or password, it may return banner data. You can configure whether this response should be validated depending on your requirement. Setting the banner_check property to 1 enable verification of the banner data, while setting it to 0 skip this check.

no_banner_check ="1"

The “device_error_pattern” property checks the command response; if the pattern value matches the command response, command execution is considered a CONNECTION CLOSED.

device_error_pattern="[FATAL ERROR,[Cc]onnection reset by peer,closed network,[Cc]onnection closed]"

The properties below also follow the same principle as the error_pattern.

expected_pattern

  • The “expected_pattern” property checks the command response; if the pattern value does not match the command response, command execution is considered a COMMAND ERROR.

expected_pattern="[bgp is enabled]"

expected_any_response

  • The “expected_any_response” property checks the command response; if the device does not respond to any data, command execution is considered a COMMAND ERROR. The value of property is not required, and hence input can be empty double quotes

expected_any_response=""

expected_empty_response

  • The “expected_empty_response” property checks the command response; if the device responds with any data, command execution is considered a COMMAND ERROR. The value of a property is not required, and hence, the input can be empty double-quotes

expected_empty_response=""

expected_count_response

  • The “expected_count_response” property checks the command response; if the device response line does not equal the count value data, command execution is considered a COMMAND ERROR. The value of the property is the response line count. The count can be any number

expected_count_response="5"

NCCM expects a 5-line response.

expected_count_response

  • The “expected_count_response” property checks the command response; if the device response line does not equal the count value data, command execution is considered COMMAND ERROR. The value of the property is the response line count. The count can be any number.

expected_count_response="!5"

NCCM expects the response to be anything other than 5 lines.

expected_count_response

  • The “expected_count_response” property checks the command response; if the device response line is less than 6, command execution is considered COMMAND ERROR. The value of the property is the count of lines. The count can be any number.

expected_count_response=">5"

NCCM expects the response to be greater than 5 lines.

expected_count_response

  • The “expected_count_response” property checks the command response; if the device response line exceeds 4, command execution is considered COMMAND ERROR. The value of the property is the count of lines. The count can be any number.

expected_count_response="=5"

NCCM expects the response to be more than 4 lines.

expected_count_response

  • The “expected_count_response” property checks the command response; if the device response line exceeds 5, command execution is considered COMMAND ERROR. The value of the property is the count of lines. The count can be any number.

expected_count_response="<=5"

NCCM expects the response to be less than 6 lines

type

  • The “type” property stores the command response under property value. NCCM stores the command output in the Operation Data store.

For example:

If the output of the command shows that the IP interface brief is required to be stored in NCCM as an Interface Brief, the XML command should be written as

<command prompt=”#” timeout=”5” type=”Interface Brief”> show IP
interface    brief</command>

Sample command to shut down an interface in plain text and XML format.

Plain Format

XML Format

conf t

int Gi 0/0

shutdown

exit

<command prompt=”#” timeout=”10”>conf t</command> <command prompt=”#” timeout=”10”> int Gi 0/0 </command> <command prompt=”#” timeout=”10”>shutdown</command> <command prompt=”#” timeout=”10” action=”exit”>exit</command>

Sample command to enable syslog in plain text format and XML format.

Plain Format

XML Format

conf t logging source-

interface Loopback100 end write memory

<command prompt=”#” timeout=”10”>conf t</command> <command prompt=”#” timeout=”10”> logging sourceinterface Loopback100 </command> <command prompt=”#” timeout=”10”>end</command> <command prompt=”#” timeout=”10” action=”exit”>write memory</command>

Below are some sample commands to replace the Device configuration file from the NCCM server.

<command prompt="\]\?">copy tftp:running-config</command>
<command prompt="\]\?">{{Global.managementIP}}</command>
<command prompt="\]\?">{{Job.uploadfilename}}</command>
<command prompt="[\],#]" timeout="300">running-config</command>
<command previous_match="\]" prompt="#" timeout="300">yes</command>
<command action="exit" prompt="">exit</command>

Note: Plain text commands cannot be written since the timeout of some commands is more than 30 seconds.

NCCM also supports writing Comments inside the command portion to understand commands better. To define a line as a comment, add # character at the beginning of a line.

Example for writing Comments inside commands:

# Make Terminal Len 0terminal length 0
<command    prompt="#" timeout="60">terminal length 0</command>
# Copy the Image to Flash
<command    prompt="]\?" timeout="60">copy tftp flash:</command>
# Remove boot system
<command    prompt="#" timeout="60">no boot system</command>

Note: At the time of execution, NCCM ignores all lines starting with # (comment lines)

NCCM Variable Substitution

NCCM follows the Jinja2 Template engine for converting command templates into actual commands. Jinja2 Template engine provides features like

  • Variable substitution

    • For substituting specific values for specific Devices

  • Variable declaration

  • Data structures like Integer, Boolean, List, and Dictionary

  • Loop Statements like

    • For o While

    • Do while

  • Conditional Statements like

    • If

    • If else

    • If elif else

  • Conditional operators like

o =

o !=

o in

o not in

o > and >=

o < and <=

Variable Substitution

Variables are command inputs given by a user dynamically during the execution time.

For example, if the user wants to change the hostname in Cisco devices, the command syntax will be

#hostname <New Hostname>
hostname is the command and <New hostname> is the variable or 
input portion to hostname command

Through variable substitution, the single template is enough to change the hostname of all devices with the same Vendor and OS Type configured in the template; otherwise, each device requires a separate template.

To substitute a variable, follow the below steps based on the condition applicable:

1) Use “Double Curly Brackets” before and after the variable {{ }}, only if the variable is not inside Jinja2 statements

<command prompt=”#” timeout=“5”>hostname {{Runtime.hostame}}    
</command>

Runtime is a substitution object.

NCCM Substitution Objects in Template:

NCCM supports 10 types of substitution objects for Variable substitution within the configuration template

1) Runtime object

The runtime object will be used in Configuration Upload and Network Diagnosis activities. Runtime object variables will be converted into user input form to get values while configuring the upload task or Network Diagnosis creation.

{{Runtime.hostname}}

2) Global object

All Global parameters configured in NCCM are available through the Global object for Variable substitution.

{{Global.managementIP}}

3) Type object

Defines the field based on the variable type specified, such as Text Area, Text field, DropDown, and Multi DropDown.

Type.Speed=DropDown

4) Default object

I defined the default value for Type Object here.

Default.Speed=10,100,1000

5) Remark object

Displays the Text on mouse hover on the Variable Name.

Remark.Speed=enter speed of interface

6) Optional object

If the variable is declared ‘Optional’, the input for the field is not mandatory.

Optional.VariableName

7) Check object

Ensures that the Input format matches the defined format.

In Textfield, it should allow only 1 to 255 ^([1-9]|[1-9][0-9]|[1-2][0-5][0-5])$

8) LOCAL_SHELL object

The LOCAL_SHELL object gets values from the LOCAL_ACCOUNT profile, configured in the Device credential for Variable substitution.

{{LOCAL_SHELL.username}}

9) Device object

The device object gets values from the Device database of the corresponding Device where command execution occurs.

{{Device.IPaddress}}

10) Interface object

The interface object gets values from the Device Interface database of the corresponding Device where command execution takes place.

{{Interface.name}}
{{Interface.description}}

11) Job object

Job object gets values from the Job Database (Upload or Download Job) of the corresponding Device where command execution occurs.

{{Job.name}}

12) Profile object

Profile object gets values from Profile Database (Configuration Profile) of the corresponding Device where command execution occurs.

{{Profile.download_profile.user_name}}

13) Trigger object:

Trigger object gets values from Configuration Trigger Database of corresponding Trigger name used in Configuration Template.

{{Trigger.triggername}}

Note: A template can have more than one Trigger variable.

14) Profile object:

Profile object gets values from the Device Credential Database of the corresponding Device (Device Credential) where command execution will occur.

{{Profile.ssh_loginname}}

15) Time object:

Time object gets values from the NCCM server based on current time, which is for substituting time values in a template during execution

{{Time.now}} – Time in unix epoc format
{{Time.YYYYMMDD}} – Time in YYYY MM DD format
{{Time.uniquestring}} – Unique string

16) Directly writing variable, if a variable is inside Jinja2 expression statement {% %}

{% if Runtime.hostname. == “router27” %}

17) Selected Node Device Credential Fetch Support (Event Substitution Object)

When executing an Upload Job for a specific IP, you can dynamically retrieve the associated username and password. Currently, the following keys are supported within the Event substitution object:

  • event_msg

  • additional_text

  • specific_problem

  • perceived_severity

18) Device Login Profile Credentials

You can directly replace username and password values from the device’s login profile using these objects:

  • {{Device.login_profile_username}}

  • {{Device.login_profile_password}}

19) Device_Common_Info

Maps to the Asset common_info details in the asset inventory.

Device_Common_Info -> Asset common_info

20) Device_Custom_Fields

Maps to the Asset custom fields associated with the device.

Device_Common_Info -> Asset common_info

21) Resource_Common_Info

Maps to the Resource common_info details for the selected resource.

Resource_Common_Info -> Resource common_info

22) Resource_Custom_Fields

Maps to the Resource custom fields associated with the resource.

Resource_Custom_Fields -> resource custom fields

23) Resource_Resource_Info

Maps to the resource_info details stored in the resource database.

Resource_resource_Info  -> resource_info

NCCM Jinja2 Filters

regex_search

The regex_search filter in NCCM allows template authors to extract specific values from a string using regular expressions. This is commonly useful for parsing messages, variables, or other text-based input to dynamically populate variables within a configuration template.

By applying regex_search, you can target and capture only the required part of the message, reducing manual intervention and improving automation accuracy.

Example:

{% set account_user = Event.additional_text | regex_search('Account\sName:\s+(\w+)\s+Account') %}

In this example:

  • The filter searches within Event.additional_text.

  • The regex pattern looks for the word "Account Name:" followed by one or more word characters (\w+), then the word "Account".

  • The captured username is stored in the account_user variable for later use in the template.

PreviousWhat you see on the screenNextConditioning in Template

Last updated

Was this helpful?