- Cisco Active Network Abstraction Customization User Guide, 3.6.4
Table Of Contents
What Are Cisco ANA Macro Language Scripts?
Properties Available From the IMO Context
Specifying and Using Parameters
Multiple Formats for IP Subnet Parameters
Cisco ANA Macro Language
This chapter describes the Cisco ANA Macro Language, its syntax, how to use parameters, pragmas, and a detailed example for writing Cisco ANA Macro Language scripts. This guide is intended for use by programmers who want to write command scripts that are executed within the Cisco ANA activation framework.
This chapter includes:
•
What Are Cisco ANA Macro Language Scripts?
•
•
What Are Cisco ANA Macro Language Scripts?
A Cisco ANA Macro Language script is a simple sequence of Telnet commands, runtime-replaced input arguments, and inline execution directives that are executed sequentially as Telnet configuration commands on a networking device. Cisco ANA Macro Language script lines are evaluated in runtime for argument replacements that result in generation of a Telnet device configuration command that can be sent to the device. The reply of executing each command line is validated according to the inline directives that can abort and rollback the script or continues executing the next script line. Cisco ANA Macro Language scripts can be created using the Command Builder or can be provided externally using the Cisco ANA BQL API.
A Cisco ANA Macro Language script is usually made of a command script and a rollback script. The programmer can specify that if a command script fails, a rollback script is called.
When defining Cisco ANA Macro Language scripts, the programmer can:
•
•
•
Properties Available From the IMO Context
The script IMO context makes the Cisco ANA Information Model Objects available to the script as built-in arguments. A script IMO context can be any object that can be represented by a Cisco ANA IMO, ranging from a managed element to a port connector to a routing entry.
Example IMO contexts can include:
•
–
–
•
–
–
For more information about Cisco ANA Macro Language Built-in parameters, see Built-In Parameters.
Specifying and Using Parameters
Cisco ANA Macro Language supports two types of script parameters: User-defined and built-in; both are replaced at runtime. In the Command Builder GUI, all parameters (both built-in and user-defined) are available during command editing via a selection list.
Note
Cisco ANA Macro Language represents both types of parameters in script lines within dollar symbols, such as $...$. For example, in a VRF configuration command, the input variable vrfName can be defined as ip vrf $vrfName$.
Note
Note
Note
User-Defined Parameters
User-defined input parameters must be defined up front. A parameter specification includes parameter name, type, and even an optional default value. User-defined parameters can be defined using the Command Builder or through the Cisco ANA API.
Table 17-1 provides a complete list of user-defined parameter properties.
Note
During runtime, the script is executed via a BQL command. As with all BQL commands, if the argument types do not match, an exception is returned to the user.
User-defined parameters values can be provided in the following ways:
•
•
Multiple Formats for IP Subnet Parameters
Cisco ANA Macro Language scripts support multiple formats for IP subnet parameters, as described in Table 17-2, using the example 198.168.2.10 255.255.255.0.
For example, routeadd$SB:IP$mask$SB:mask$ extracts the IP and then the subnet.
Built-In Parameters
Built-in parameters are the built-in properties available in IMO arguments of the IMO context (such as portalias or status), which are automatically set to their runtime value during execution. The built-in properties include IMO attributes, OID attributes, and instrumentation data.
For a complete list of the available built-in parameters related to the IMO context, see the IMO Reference Guide.
Note
Supported Pragmas
The programmer can insert inline directives (pragmas) in the script lines for increased granularity control. Pragmas are enclosed within square brackets ([...]). Table 17-3 lists the pragmas that Cisco ANA Macro Language scripts support.
Note
Note
Success
Description
A success pragma is validated against the script line reply. The success pragma verifies that a required substring exists in the reply. If the substring is not found, the script fails.
Syntax
[success=<string>]where <string> represents the expected return value from the device. The <string> can be simple text or can contain arguments that are replaced in runtime.
Directives
The pragma succeeds and the script continues only if the <string> is found in the device reply.
The pragma fails if the <string> does not exist in the reply.
The <string> can be a regular expression; it does not necessarily have to be an exact string to match.
Examples
The following example verifies that the specified VRF $newVrf$ does not already exist:
show ip vrf $newVrf$ [success=% No VRF $newVrf$]Placing Trial for newVrf, this pragma succeeds if the device reply contains % No VRF Trial.
Fail
Description
A fail pragma is validated against the script line reply. The fail pragma verifies that a required substring does NOT exist in the reply.
Syntax
[fail=<string>]where <string> represents the value that should not be included in the device reply. The <string> can be simple text or can contain arguments that are replaced in runtime.
Directives
The script fails if <string> is found in the device reply.
The script continues if the <string> does not exist in the reply.
The <string> can be a regular expression; it does not necessarily have to be an exact string to match.
Example
The following example sets a route distinguisher:
rd $newRD$ [fail=% Cannot set RD $newRD$]Placing 60:60 as the newRD, this pragma yields failure only if the device reply contains =% Cannot set RD 60:60.
Prompt
Description
A prompt pragma is validated against the next Telnet command prompt. The prompt pragma verifies that the suffix of the prompt equals the given string. If the suffix differs from the string, the script fails.
Syntax
[prompt=<prompt>]Where <prompt> represents the new expected prompt, the <prompt> can be simple text or can contain arguments that are replaced in runtime before sending to the device.
Directives
The pragma is successful and script execution continues only if the <prompt> is found as the suffix of the device prompt.
The pragma fails if the <prompt> is not found in the suffix of the device prompt.
Example
The following example changes the Telnet prompt and validates the change in the newly returned Telnet prompt:
configure terminal [prompt=(config)]This pragma succeeds only if the next device prompt ends with (config)#.
Full Prompt
Description
A full prompt pragma is validated against the next telnet command prompt. The full prompt pragma verifies that the prompt equals the given string. If the prompt differs from the string, the script fails.
Syntax
[prompt=^<prompt>]Where <prompt> represents the expected full prompt, the <prompt> can be simple text or can contain arguments that are replaced in runtime before sending to the device.
Directives
The pragma is successful and script execution continues only if the next full prompt equals <prompt>.
The pragma fails if the next prompt does not equal <prompt>.
Example
The following example changes the Telnet prompt and validates the change in the newly returned Telnet prompt:
configure terminal [prompt=^router(config)#]This pragma yields success only if the next device prompt matches router(config)# exactly.
Rollback
Description
Rollback scope—the pragma [rollback] determines that rollback is to be executed only upon failures from this point onwards.
Note
Directives
If the script fails after the [rollback] marker then rollback is executed.
Note
Activity
Description
Set the text that, if the script fails, appears in the script's result as the name of the activity that failed. The failed activity name (label) appears in the returned result and also in the provisioning event that is generated.
Syntax
[activity=<activity>]Where <activity> stands as an inline remark comment, the <activity> can be simple text or can contain arguments that are replaced in runtime before sending to the device.
Directives
When a failure occurs later in the script, you are notified of the error according to the "activity name."
Example
[activity=now adding the vrf]Enum
Description
Defines the values that are used when substituting parameter names into a Telnet string.
Directives
The pragma is successful only if you input one of the values in the list.
The pragma fails if you do not input one of the values in the list.
Example
The enum pragma appears at the top of the script:
[enum RouteTargetTypeEnum 0=export;1=import]Later in the script, the parameter RouteTargetTypeEnum is used:
no route-target $RouteTargetTypeEnum$ $RouteTarget$The value that is substituted into the Telnet command for $RouteTargetTypeEnum$ is "export" or "import" instead of "0" or "1".
Example
The following script and rollback script performs an Add VRF configuration. The script uses user-defined arguments to represent the VRF name, route target, route distinguisher, several types of pragmas to validate the device reply, remarks in the command script, and rollback script.
Command Script
[enum rd 1=60:60;2=80:80]show ip vrf $vrfName$ [success=% No VRF named $vrfName$][activity=prepare for VRF creation]config terminal [success=Enter configuration commands, one per line. End with CNTL/Z.] [prompt=(config)]ip vrf $vrfName$ [prompt=(config-vrf)][rollback][activity=create VRF]rd $rd$ [fail=% Cannot set RD, check if it's unique]route-target both $rt$endRollback Script
config terminalno ip vrf $vrfName$endTable 17-4 lists the user-defined argument definitions used in the script.
Table 17-5 provides an explanation of the command script line-by-line.
Table 17-6 provides an explanation of the activation rollback script line-by-line.
Running the Script
The script is executed with the following input arguments:
vrfName=Trialrd=2rt=60:60The Telnet commands that would be sent to the device (preview):
show ip vrf Trialconfig terminalip vrf Trialrd 80:80route-target both 60:60end------Rollback------config terminalno ip vrf TrialendFull session:
vrfName=Trialrd=2rt=60:60PE-North#show ip vrf Trial% No VRF named TrialPE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#ip vrf TrialPE-North(config-vrf)#rd 80:80PE-North(config-vrf)#route-target both 60:60PE-North(config-vrf)#endRunning the script with the same input values again; the VRF already exists, so the command stops after VRF name verification:
PE-North#show ip vrf TrialName Default RD InterfacesTrial 80:80PE-North#^ Failed to find the text '% No VRF named Trial' in the device reply!, script terminated.Running the script with a different VRF name but the same RT and RD; the VRF would begin to be created and then rollback due to RD already in use:
vrfName=Trial2rd=2rt=50:50PE-North#show ip vrf Trial2% No VRF named Trial2PE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#ip vrf Trial2PE-North(config-vrf)#rd 80:80% Cannot set RD, check if it's uniquePE-North(config-vrf)#^ Error in activity 'create VRF'.^ Found the text '% Cannot set RD, check if it's unique' in the device reply!, script terminated.-----Invoking Rollback-----PE-North#config terminalEnter configuration commands, one per line. End with CNTL/Z.PE-North(config)#no ip vrf Trial2% IP addresses from all interfaces in VRF Trial2 have been removedPE-North(config)#end
