ANA Macro Language
ErrorMessage : Error while constructing the Hinav

null
Downloads: This chapterpdf (PDF - 166.0KB) | Feedback

ANA Macro Language

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 appendix 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 appendix 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