- Cisco Active Network Abstraction Customization User Guide, 3.6.6
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 and its syntax, how to use parameters and pragmas, and a detailed example for writing Cisco ANA Macro Language scripts. This chapter 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 the generation of a Telnet device configuration command that can be sent to the device. Each command line is validated according to the inline directives that can abort and roll back the script or continue executing the next script line. Cisco ANA Macro Language scripts can be created using 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. You can specify that if a command script fails, a rollback script is called.
When defining Cisco ANA Macro Language scripts, you 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 signs; for example, $...$. For instance, in a VRF configuration command, the input variable vrfName can be defined as ip vrf $vrfName$.
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 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 Cisco Active Network Abstraction 3.6.6 Technology Support and Information Model Reference Manual.
Note
Supported Pragmas
You 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. <string> can be simple text or can contain arguments that are replaced in runtime.
Directives
The pragma succeeds and the script continues only if <string> is found in the device reply.
The pragma fails if <string> does not exist in the reply.
<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$]Using 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. <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 <string> does not exist in the reply.
<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$]Using 60:60 for 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. <prompt> can be simple text or can contain arguments that are replaced in runtime before being sent to the device.
Directives
The pragma is successful and script execution continues only if <prompt> is found as the suffix of the device prompt. The pragma fails if <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. <prompt> can be simple text or can contain arguments that are replaced in runtime before being sent 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
A rollback pragma determines that rollback will be executed only upon failures from this point onward.
Note
Directives
If the script fails after the [rollback] marker, then rollback is executed.
Note
Activity
Description
An activity pragma sets 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 in the provisioning event that is generated.
Syntax
[activity=<activity>]where <activity> represents an inline remark comment. <activity> can be simple text or can contain arguments that are replaced in runtime before being sent to the device.
Directives
When a failure occurs later in the script, you are notified of the error by activity name.
Example
[activity=now adding the vrf]Enum
Description
An enum pragma 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 command script and rollback script perform an Add VRF configuration. The scripts use user-defined arguments to represent the VRF name, route target, and route distinguisher; several types of pragmas to validate the device reply; and 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 as 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)#endRerunning the script with the same input values (VRF already exists; 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 route target (RT) and route distinguisher (RD) (VRF creation begins and then is rolled back 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
