Table Of Contents

ANA Macro Language

What Are ANA Macro Language Scripts?

Properties Available From the IMO Context

Specifying and Using Parameters

User-Defined Parameters

Multiple Formats for IP Subnet Parameters

Built-In Parameters

Supported Pragmas

Success

Description

Syntax

Directives

Examples

Fail

Description

Syntax

Directives

Example

Prompt

Description

Syntax

Directives

Example

Full Prompt

Description

Syntax

Directives

Example

Rollback

Description

Directives

Activity

Description

Syntax

Directives

Example

Enum

Description

Directives

Example

Example

Command Script

Rollback Script

Running the Script

ANA Macro Language

---

This chapter describes the ANA Macro Language, its syntax, how to use parameters, pragmas and a detailed example for writing 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 the following sections:

•What Are ANA Macro Language Scripts?—Provides a definition of ANA Macro Language programming language and command scripts.

•Properties Available From the IMO Context—Describes a script's Information Model context.

•Specifying and Using Parameters—Describes the user-defined and built-in parameters used in script lines.

•Supported Pragmas—Describes the inline ANA Macro Language directives supported by the language.

•Example—Provides a full example of an ANA Macro Language based command script.

What Are ANA Macro Language Scripts?

ANA Macro Language scripts are 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. 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. ANA Macro Language scripts can be created using the Command Builder or can be provided externally using the Cisco ANA BQL API.

An ANA Macro Language script is usually made of a command script and a rollback script. The programmer can specify that if a command script has been detected to have failed, a rollback script would be called.

When defining ANA Macro Language scripts the programmer can:

•Import or paste scripts from external sources.

•Define inline directives (pragmas) for validating the network element's reply.

•Define a rollback script for undoing failed commands.

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 represent-able by the Cisco ANA IMO, ranging from a managed element, through port connector to a routing entry.

Example IMO contexts can include:

•Managed device

–IMO name—IManagedElement

–Example properties—CommunicationStateEnum, DeviceName, ElementType

•Port

–IMO name—IPortConnector

–Example properties—portalias, location, ifindex

For more information about ANA Macro Language Built-in parameters see Built-In Parameters.

Specifying and Using Parameters

ANA Macro Language supports two types of script parameters. User-defined parameters and built-in parameters, both are replaced at runtime. In the Command Builder GUI all parameters (both built-in and user-defined ones) are available during command editing via a selection list.

---

Note To view all the user-defined and built-in parameters in the Command Builder application press Ctrl + Spacebar to open the selection list of available arguments (containing both the user-defined input argument and the built-in properties of the IMO context).

---

ANA Macro Language represents both types of parameters in script lines within dollar symbols, namely, $...$. For example, in a VRF configuration command, the input variable vrfName can be defined as ip vrf $vrfName$

---

Note Timeout for pragmas and scripts is supported using BQL. This adds a timeout type integer defined in milliseconds. It is recommended that if you change the timeout for the pragma you also change the timeout for the script.

---

---

Note An example of a timeout for a pragma is route-target both $rt$ [timeout=2000]

---

---

Note An example of a timeout for a script is <Timeout type="Integer">5000</Timeout>

---

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.

The following is a complete list of the user-defined parameter properties:

Property	Explanation
Name	Parameter name. Can contain only letters, digits, "-" and "_". Unique within the script scope.
Caption	Parameter display name. Visible in the Command Builder script execution window.
Type	String, Integer, IPSubnet, Combo, IP, Float, Long.
Width	Field width, in characters. Relevant for the Command Builder script execution window.
Visible	Show this parameter in the window or not. Relevant for the Command Builder script execution window.
Default	A default value for the parameter. Note This property is only available through the Command Builder GUI.

---

Note Some parameter properties are relevant only for the script data entry window in the Command Builder.

---

During runtime the script is executed via a BQL command. As with all BQL commands if the argument types do not match, then an exception is returned to the user.

User defined parameters values can be provided in one of the following ways:

•Using flow-through activation the input parameters are provided as part of the API before they are sent to the Virtual Network Element (VNE).

•Run from NetworkVision as a GUI-based command. The programmer provides the input before they are sent to the VNE. For example, by typing a value or selecting one from the dropdown list.

Multiple Formats for IP Subnet Parameters

ANA Macro Language scripts support multiple formats for IP subnet parameters, as described in the table below, using the example 198.168.2.10 255.255.255.0:

#	Format	Description	Output
1	maskbits	The IP of the subnet converted to an integer value. Only bits.	30
2	ip	Only the IP without the mask.	198.168.2.10
3	mask	The IP of the subnet mask without the IP address.	255.255.255.0
4	networkmask	The mask address converted to the network.	0.0.0.255
5	ipmaskbits	The IP and the value of the mask bits.	IP/30
6	ipmask	The IP mask. This is the default.	198.168.2.10 255.255.255.0
7	ipmasknot	The IP and the network address.	198.168.2.10 + 0.0.0.255

For example, routeadd$SB:IP$mask$SB:mask$. The same argument 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 (for example, portalias, status etc.), 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 To view all the user-defined and built-in parameters in the Command Builder application press Ctrl + Spacebar to open the selection list of available arguments (containing both the user-defined input argument and the built-in properties of the IMO context).

---

Supported Pragmas

The programmer can insert inline directives (pragmas) in the script lines for finer-granularity control. Pragmas are enclosed within square brackets, namely, [...]. The ANA Macro Language supported pragmas are listed below:

Pragma	Short Description	Refer to...
Success	Line-specific success check	Success
Fail	Line-specific failure check	Fail
Prompt	Line-specific prompt assertion validation	Prompt
Full prompt	Full prompt line-specific prompt assertion validation	Full Prompt
Rollback	Rollback enable or disable	Rollback
Activity	Script remarks. These would also help to determine the failure location	Activity
Enum	Defining enumerated value substitution	Enum

---

Note Wherever the carriage return character is required in the middle of a command line, the programmer should use the escape sequence &cr.

---

---

Note It is possible to use multiple pragmas in a single line, in which case all the pragmas will be analyzed. If the same type of pragma is repeated, only the last one will be used.

---

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 will be replaced in runtime.

Directives

The pragma will be successful and the script will continue only if the <string> is found in the device reply.

The pragma will fail 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 as the newVRF, this pragma will yield success if the device reply would contain % 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 will be replaced in runtime.

Directives

The script will fail if <string> is found in the device reply.

The script will continue 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 will yield failure only if the device reply would contain =% 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 will be replaced in runtime before sending to the device.

Directives

The pragma will be successful and script execution continues only if the <prompt> is found as the suffix of the device prompt.

The pragma will fail 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 will yield success only if the next device prompt would end 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 will be replaced in runtime before sending to the device.

Directives

The pragma will be successful and script execution continues only if the next full prompt equals <prompt>.

The pragma will fail 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 will yield success only if the next device prompt would match router(config)# exactly.

Rollback

Description

Rollback scope—the pragma [rollback] determines that rollback will be executed only upon failures from this point onwards.

---

Note Be sure the rollback script restores the devices prompt to its original value before the script was initiated.

---

Directives

If the script fails after the [rollback] marker then rollback is executed.

---

Note If the rollback script fails, no additional actions can be performed.

---

Activity

Description

Set the text that, if the script fails, will appear 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 will be replaced in runtime before sending to the device.

Directives

When a failure occurs later in the script, the user is 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 will be successful only if the user inputs one of the values in the list.

The pragma will fail if the user does 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 and 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$

end

Rollback Script

config terminal

no ip vrf $vrfName$

end

The following table lists the user-defined argument definitions used in the script:

Name	Type	Default	Explanation	Example
vrfName	String	N/A	The VRF name. The value provided for this argument will be used as the VRF table name.	Manhattan
rt	String	N/A	The VRF route target, in the format of integer:integer. The value provided for this argument will be used as is for the device configuration.	60:60
rd	String	1	In this example, the system administrator would like the route distinguisher to be based on the pre-defined enumerated values list. Hence, the route distinguisher will be provided in the format of an integer to be used as a lookup table key, and not x:y.	1, 2 or any valid value according to the enum pragma

The following table provides an explanation of the command script line-by-line:

Script Line	Explanation
[enum rd 1=60:60;2=80:80]	The line enumerates the possible values of the route distinguisher argument.
show ip vrf $vrfName$ [success=% No VRF named $vrfName$]	Verify if the requested VRF already exists. Continue to create the VRF only if the requested VRF name is not found.
[activity=prepare for VRF creation]	Remark to state that the following section is preparation for VRF creation.
config terminal [success=Enter configuration commands, one per line. End with CNTL/Z.] [prompt=(config)]	Change mode command. Continue to the next command if the success pragma string is found in the device reply and the prompt changes to config.
ip vrf $vrfName$ [prompt=(config-vrf)]	Change mode command. Continue to the next command if the prompt changes to config-vrf.
[rollback]	Placeholder to state that rollback should be executed only if a subsequent script line fails.
[activity=create VRF]	Remark to state that the following section is actually the VRF creation.
rd $rd$ [fail=% Cannot set RD, check if it's unique]	Set the route distinguisher. If this command will fail the rollback script will be called.
route-target both $rt$	Set the route target. If this command will fail the rollback script will be called.
end	Change mode command. Return to normal ("enable") mode.

The following table provides an explanation of the activation rollback script line-by-line:

Script Line	Explanation
config terminal	Set the device to terminal mode.
no ip vrf $vrfName$	Delete the VRF from the device.
end	Change mode command. Return to normal ("enable") mode.

Running the Script

The script is executed with the following input arguments:

vrfName=Trial

rd=2

rt=60:60

The telnet commands as would be sent to the device (preview):

show ip vrf Trial            

config terminal                

ip vrf Trial            

rd 80:80         

route-target both 60:60        

end        

  ------Rollback------        

config terminal        

no ip vrf Trial        

end

Full session:

vrfName=Trial

rd=2

rt=60:60

PE-North#show ip vrf Trial          

% No VRF named Trial        

PE-North#config terminal            

Enter configuration commands, one per line.  End with CNTL/Z.

PE-North(config)#ip vrf Trial          

PE-North(config-vrf)#rd 80:80        

PE-North(config-vrf)#route-target both 60:60        

PE-North(config-vrf)#end

Running the script with the same input values again (VRF already exists, the command stops after VRF name verification)

PE-North#show ip vrf Trial          

  Name                             Default RD          Interfaces

  Trial                            80:80        

PE-North#        

 ^ Failed to find the text '% No VRF named Trial' in the device reply!, script terminated.

Running the script with a different VRF name (same RT & RD) (VRF would begin to be created and then rollback due to RD already in use)

vrfName=Trial2

rd=2

rt=50:50

PE-North#show ip vrf Trial2            

% No VRF named Trial2        

PE-North#config terminal                

Enter configuration commands, one per line.  End with CNTL/Z.

PE-North(config)#ip vrf Trial2            

PE-North(config-vrf)#rd 80:80         

% Cannot set RD, check if it's unique        

PE-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 terminal        

Enter 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 removed        

PE-North(config)#end