How to write Command Portion in Template

NCCM supports two ways of writing commands in Template

1) 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.

2) 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.

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 - 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” 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”

• 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>

• 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]"

The properties below also follow the same principle as the error_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]"

• 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=""

• 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=""

• 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.

• 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.

• 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.

• 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.

• 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

• 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” %}