Submit a ticketCall us

Announcing NCM 7.7
With NCM 7.7, you can examine the rules that make up an access control list for a Cisco ASA device. Then you can apply filters to display only rules that meet the specified criteria, order the rules by line number or by the hit count, and much more.
See new features and improvements.

Home > Success Center > Network Configuration Manager (NCM) > NCM 7.7 Administrator Guide > Config change template details > Advanced commands

Advanced commands

Created by Caroline Juszczak, last modified by Anthony.Rinaldi_ret on Oct 03, 2016

Views: 26 Votes: 0 Revisions: 6

The scripting framework for change config templates allows you to create CLI { } command arguments that include foreach loops, if/else conditional operations, and functions for manipulating string patterns.

Foreach Loops

A foreach statement iterates through an array of items based on a SolarWinds Information Service (SWIS) entity data type. Foreach statements use the following pattern:

foreach (@ItemVaraible in @EntityArrayVariable)

A primary purpose of a foreach loop is to allow the template user to select multiple NCM objects for config change. The loop instructs NCM to perform the same config change on all items in scope as determined by the SWIS entity in the database and delimited at run time by the template user's selections in the template wizard.

Cisco Example

foreach (@portItem in @TargetPorts)
	  interface @portItem.InterfaceDescription

The foreach statement creates a set that contains two related variables: @portItem and @TargetPorts.

The @TargetPorts variable holds an array of objects with the data type of an SWIS entity called NCM.Interfaces[ ]. The array will be a set of interfaces on NCM nodes.

The @TargetPorts variable is associated with the PARAMETER_LABEL Select port(s) and the template user selects one or more ports at run time. The template user determines the set of interfaces to fill the array NCM.Interfaces[ ], and the template will perform VLAN membership config changes on each interface in that array.

@portItem is a dynamic variable that the loop uses during its iterating to hold the value of the current interface from the array represented by @TargetPorts.

The foreach loop format is fixed and NCM expects it to include the dynamic variable.

The user interacts with this template wizard screen:


Click Select Interfaces List to load a tree that displays available interfaces and NCM nodes previously selected in the wizard.

Conditional Statements

Conditional logic in a config change template script uses an if/else pattern to define two branches of possible action, enclosing specific conditions within parentheses. Within each branch of the conditional pattern are CLI{ } commands to execute if that branch meets the specific conditions.

Here is the basic structure:

if (condition is true)
 execute commands
 Execute other commands

The else section is optional. If you omit it, and the if condition is false, NCM excludes the relevant CLI{ } commands from the template output.


Use any of the following operators to specify a parenthetical condition. Use single quotes around string values.

Operator Condition
== Is Equal To
> Is Greater Than
>= Is Greater Than or Equal To
< Is Less Than
<= Is Less Than or Equal To
!= Is Not Equal To
Contains 'string'
containsExact 'case sensitive string'
startsWith 'string'
startsWithExact 'case sensitive string'
endsWith 'string'
endsWithExact 'case sensitive string'

Cisco Example

Add conditional logic in the foreach loop to prevent errors that may occur if the user accidentally selects an inappropriate interface (for example, the loopback address).

foreach @portItem in @TargetPorts)
	if (@PortItem.InterfaceDescription != ???Loop0???)
  	  interface @portItem.InterfaceDescription

If the template encounters the loopback interface, it does nothing and passes on to the next interface. This code prevents damage from template user error.

Manipulating Strings

Five functions for manipulating strings constitute a final scripting resource that you can use most readily for managing ACL config changes for network firewalls, in which a config change template needs to iterate through a predictably variable set of IP addresses, for example.

Function Description Declaration Variable Definitions
Substring Specify a starting point within a string and the length from the starting point that you want to capture for manipulation. string Substring(string str, int startIndex, int length)
  • str is the full string from which the substring comes
  • startIndex marks the position where the substring begins
  • length is the number of characters that the substring includes
StrLength Return the length of a string. In StrLength(string str)
  • str is the user-input string whose length is used as the integer value
IndexOf Find the number of characters in a string. int IndexOf(string str, string search)
  • str is a string to search on
  • search is a user-input string NCM uses to find the numerical value of the string being searched
SetOctet Replace an octet within an IP address. string SetOctet(string ipAddr, int octetPosition, string octet)
  • ipAddr is the IP address
  • octetPostion marks the position where the target octet begins
  • octet is the new value of the target octet
GetOctet Retrieve an octet from a user-specified IP address and octet position. string GetOctet(string ipAddress, int octetPosition)
  • ipAddress is a user-input IP address
  • octetPosition is the user-input value for the place where the function finds the beginning of the octet to get

Example 1: Manipulating a String

script IPshuffle(string @str, string @search )
	int @length = strlength(@str)
	int @startIndex = indexof(@str,@search)
	int @substringLength = @length - @startIndexstring
	@res = substring(@strA, @startIndex, @substringLength)


The user enters ABCDEF for the @str variable and CD for the @search variable in the template's wizard. Based on those values, the script does the following:

  1. Uses ABCDEF in the strlength function to give a value of 6 to a variable called @length.
  2. Uses CD as the substring of ABCDEF to set a value 2 for the variable called @startIndex.
  3. Subtracts 2 (@startIndex) from 6 (@length) to determine the value of @substringLength as 4.
  4. Takes the original string ABCDEF and calculates a result (@res) using @startIndex to count in two positions and @substringlength to count four positions from the start index.
  5. Outputs CDEF as the result.

Example 2: Changing an Access Control List

This example creates a block of Access Control List (ACL) instructions that predictably vary the value of a specific octet within an IP address. The instructions conform to the pattern 10.10.@id.10, where the value of @id is determined by user input.

The user enters as the value of @ipaddress in the config change template's run-time wizard. The user enters 1, 22, and 222 for the @indexes variable declared in the script command.

	IP address???????? 
	Enter an IP address

	Enter a pattern of octet replacements.
	Separate numbers with a comma.

script ACLChanges(string @ipaddress, int[] @indexes)
	string @ipnew

	foreach(@id in @indexes)
		@ipnew = setoctet(@ipaddress,3,@id)
     		Allow @ipnew out
		Allow @ipnew UDP 2055 OUT

The script uses the SetOctet function to determine the value of an @ipnew variable. SetOctet is defined to take the user-input IP address and create a new IP address by iteratively replacing the third octet with user-input values. For each new IP address, the script produces a command to create outgoing UDP transmission access through port 2055:

  • Allow outAllow UDP 2055 OUT
  • Allow outAllow UDP 2055 OUT
  • Allow outAllow UDP 2055 OUT

Example 3: Managing an Access Control List for Multiple Routers

In this example, a config change template generates a block of ACL instructions for a router in a store. We create an ACL block of instructions for this device that varies based on a portion of the device's IP address.

If the store has four routers,,,, and, the template script generates an ACL block that appears this way on the selected router (

Allow out

Allow UDP 2055 OUT

Allow out

Allow UDP 2055 OUT

Allow out

Allow UDP 2055 OUT

Allow out

Allow UDP 2055 OUT

Here is the script that produces the output:

script OpenACLs(NCM.Nodes @ContextNode, string[] @IpRouters)
	foreach(@ipRouter in @ipRouters)?????? 
		string @octet = getoctet(@IpRouter,3)
		string @ipnew = setoctet(@ContextNode, 3,@octet)
		  Allow @ipnew out
		  Allow @ipnew UDP 2055 OUT

This script does the following:

  • Uses a foreach loop to go through a user-input series of router IP addresses.
  • Uses the GetOctet function to focus the third octet of the current router IP address.
  • Uses the SetOctet function to create a new IP address as a value for @ipnew.
  • Creates a CLI { } command that will execute Allow operations for each of the selected routers.

The result is a set of Allow commands that open access in the ACL so that the router can send OUT traffic via UDP on port 2055 to,, and

Here are the parameters for this config change template. The template user selects the router on which to make ACL changes and inputs the target router IP address through this template:

	Router for ACL Change???????? 
	Select a Router
	Target Routers???????? 
	Add Routers to Target with ACL Allowances	


Last modified
14:08, 3 Oct 2016