Documentation forNetwork Configuration Manager

NCM macros (variables)

NCM provides the following types of macros (also called variables):

All NCM macros are enclosed in ${ }. For example, the macro for system name is ${SysName}. Macros are not case-sensitive.

Global macros

The values for global macros are specified by global device defaults. The value for a global macro is the same for all nodes.

You can also create custom global macros.

Macro Inserts the value of this Global Device Defaults field
${GlobalUserName} Username
${GlobalPassword} Password
${GlobalEnableLevel} Enable Level
${GlobalEnablePassword} Enable Password
${GlobalExecProtocol} Execute Commands and Scripts
${GlobalConfigRequestProtocol} Config Request
${GlobalConfigTransferProtocol} Transfer Configs
${GlobalTelnetPort} Telnet Port
${GlobalSSHPort} SSH Port

Node macros

Node macros point to a column in the NCM_Nodes table. The value of a node macro is unique for each node. The following table lists the NCM_Nodes table column that supplies the value for each macro. Table column names are shown in square brackets.

Macro Inserts this value From this [columnName]
${AgentIP}

The IP address of the node.

  • If [ManagedProtocol] is 0, then [AgentIP]
  • If [ManagedProtocol] is not 0, then [AgentIPv6]
${Caption}

The name used to identify the node in the Orion Platform.

During discovery, this value is populated with the host name (if available) or the DNS domain name. You can change it by editing the node property Name. This value is not updated when the node is rediscovered.

[NodeCaption]
${SystemName}
${SysName}

The host name of the node, if it can be polled during discovery. This value is updated when the node is rediscovered.

  • If [SysName] is empty, same as ${AGENTIP}
  • If [SysName] is not empty then [SysName]
${SystemLocation}
${SysLocation}
The node location, which is obtained from the device via SNMP polling. [SysLocation]
${SystemContact}
${SysContact}
The node contact, which is obtained from the device via SNMP polling. [SysContact]
${Description}
${SysDescr}
${SystemDescription}
${SysDescription}
The node description. [SysDescr]
${SCPStorageAddress} The IP address or host name of the NCM SCP server.
  • If [Settings.SCPAutoRetriveIP], then [EngineIP]
  • If not, then [Settings.SCPServerAddress]
${StorageAddress} The IP address or host name of the NCM TFTP server.
  • If [Settings.TFTPAutoRetriveIP], then [Settings.TFTPServerAddress]
  • If not, then [EngineIP]
${SCPServerUserName} The user name that NCM uses to access the SCP server. [Settings.SCPUserName]
${PCAddress}
${ServerIP}
${IPAddress}
${TFTPServer}
${LocalIP}
The IP address of the Orion Platform primary server. [EngineIP]
${HostName}
${LocalHostName}
The host name of the Orion Platform primary server. [EngineServerName]
${TransferProtocol} The transfer protocol used during an indirect transfer.

[TransferProtocol]

Transfer macros

Transfer macros are used when NCM uploads or downloads configuration files.

Macro Inserts this value
${ConfigType} The type of configuration (for example, running or startup).
${StorageFileName} The name generated by NCM for the downloaded configuration file.
${ConfigText}

In a direct upload operation, the config to be uploaded to the device.

Command macros

Device template commands are used to execute commands on devices. Device templates define the Name and Value for each device command. For example, EnterConfigMode is a command name, and the value is the command required to enter config mode for a specific device type. For a description of all device template commands, see NCM device template commands.

When a command is defined in a device template, you can include the command as a macro within a script. To do so, format the command Name as a macro (for example, ${EnterConfigMode}).

Device command templates for each device type can define different Values for commands with the same Name. For example, the value of EnterConfigMode is config terminal for Cisco IOS devices, but it is configure for HP Procurve switches. When you use a command macro in a script instead of the actual command, you can use the same script for multiple device types.

Date and time macros

Date and time macros are replaced with current date or time.

Macro Inserts this value Examples
${DateTime}
${Date Time}
${Date/Time}
Local date and time in short date and local time format (the Short Date and Short Time format defined in the Windows Control Panel) 10-29-2019 2-55 PM
${Date}
${ShortDate}
${Short Date}
Date in short date format 10-29-2019
${MediumDate}
${Medium Date}
Date in medium date format 29-Oct-19
${LongDate}
${Long Date}
Date in long date format Tuesday, October 29, 2019
${Time}
${ShortTime}
${Short Time}
Time in short time format 14-55
${MediumTime}
${Medium Time}
Time in medium time format 02-55 PM
${LongTime}
${Long Time}
Time in long time format 2-55-48 PM
${DOW}
${Day Of Week}
${DayOfWeek}
Day of the week, spelled out Tuesday
${AbreviatedDOW}
${Abreviated Day Of Week}
${AbreviatedDayOfWeek}
Abbreviated day of the week Tue
${D}
${Day}
One- or two-digit day of the month

5
29

${DD} Two-digit day of the month, with a leading zero if needed

05
29

${MMMM}
${MonthName}
$Month Name}
Name of the month, spelled out October
${MMM}
${AbreviatedMonth}
${Abreviated Month}
Abbreviated name of the month Oct
${Month}
${M}
One- or two-digit month number

5
12

${MM} Two-digit month number, with a leading zero if needed

05
12

${DayOfYear}
${Day Of Year}
Number of the day of the year 302
${Year2}
${Year2}
${YY}
Two-digit year 20

${Year4}
${Year4}
${Year}
${YYYY}

Four-digit year 2020
${H}
${Hour}
One- or two-digit hour

02
11

${HH} Two-digit hour, with a leading zero if needed

02
11

${NN}
${Minute}
Two-digit minute, with a leading zero if needed

05
55

${N} One- or two-digit minute

5
55

${SS}
${Second}
Two-digit second, with a leading zero if needed

05
30

${S} One- or two-digit second

5
30

${AMPM}
${AM/PM}
AM or PM PM

Keystroke macros

Keystroke macros send keystrokes to menu-based or CLI devices. For example, ${DownArrow} simulates sending a Down Arrow keystroke to the device.

Macro Sends these characters
${CTRL+@} CTRL+@

${CTRL+A}

CTRL + A

${CTRL+B} CTRL+B
${CTRL+C} CTRL+C
${CTRL+D} CTRL+D
${CTRL+E} CTRL+E
${CTRL+F} CTRL+F
${CTRL+G} CTRL+G
${CTRL+H} CTRL+H
${CTRL+I} CTRL+I
${CTRL+J} CTRL+J
${CTRL+K} CTRL+K
${CTRL+L} CTRL+L
${CTRL+M} CTRL+M
${CTRL+N} CTRL+N
${CTRL+O} CTRL+O
${CTRL+P} CTRL+P
${CTRL+Q} CTRL+Q
${CTRL+R} CTRL+R
${CTRL+S} CTRL+S
${CTRL+T} CTRL+T
${CTRL+U} CTRL+U
${CTRL+V} CTRL+V
${CTRL+W} CTRL+W
${CTRL+X} CTRL+X
${CTRL+Y} CTRL+Y
${CTRL+Z} CTRL+Z
${CTRL+[} CTRL+[
(Equivalent to pressing the Esc key)
${CTRL+\} CTRL+\
${CTRL+]} CTRL+]
${CTRL+CTRL} CTRL+CTRL
${CTRL+ } CTRL+
${UpArrow} Up Arrow
${DownArrow} Down Arrow
${RightArrow} Right Arrow
${LeftArrow} Left Arrow
${CR} Carriage return
${CRLF}

Carriage return and line feed combination: \r\n

Prompt detection and delay macros

The following macros can be included in scripts.

Macro Description
${DisablePromptDetection}
${EnablePromptDetection}

By default, NCM waits for the device to send a command mode prompt before it sends the next command. If a device does not send a command mode prompt immediately after each command, you can include the following macros in a script to turn off prompt detection for a block of commands in order to improve the performance of the script.

${DisablePromptDetection}

Command1

Command2

...

${EnablePromptDetection}

The ${DisablePromptDetection} macro temporarily disables prompt detection. NCM stops waiting for the command mode prompt before it sends the next command. The ${EnablePromptDetection} macro turns prompt detection back on.

Use these macros to surround a specific group of commands. Always use ${DisablePromptDetection} to turn prompt detection back on at the end of the group of commands.

${Delay:nn}

In a command script, use the Delay macro to specify the number of seconds that NCM should wait before it sends the next command. Use this macro when the first command will take some time to complete. The following example waits 20 seconds before it sends Command2:

Command1
${Delay:20}
Command2

${NewPromptRegEx:regEx}

If a device's command mode prompt changes frequently and the UseVirtualPormptForCommands in the device template is causing false prompt detection, you can use the NewPromptRegEx macro to identify the new prompt with the executed command. For example, after the sys command is executed, a device's command prompt changes from <Prompt> to [Prompt]. The following line tells NCM to execute the sys command and then identify any line that contains [ as the command mode prompt:

sys ${NewPromptRegEx:[}

Where can macros be used?

You can use macros in the following operations.

NCM functionality Macros you can use
Connection profiles that enable NCM to connect to a node
  • Global
Command scripts
  • Global
  • Node
  • Transfer
  • Command
  • Date and time
  • Prompt detection and delay macros

NCM jobs

  • Global
  • Node
  • Date and time
Template for naming archived config files
  • Global
  • Node
  • Date and time
  • ${ConfigType}
Device templates
  • Node
  • Transfer
  • Date and time
  • Keystroke
Real-time change detection email notification options
  • Global
  • Node
  • Date and time
Firmware upgrade templates
Alerts
The SWIS verb NodeInvoker.ParseMacros
  • Global
  • Node
  • Date and time

In policy rules, NCM automatically adds certain policy rule macros, such as ${ConfigBlockStartLine}. Policy rule macros are for internal use and should not be manually added to policy rules.