Cisco Active Network Abstraction Network Service Activation 1.0 Customization Guide, 3.7
Customizing Cisco ANA Network Service Activation Scripts
ErrorMessage : Didn't tag either concept or doctype for selected page

null
Downloads: This chapterpdf (PDF - 248.0KB) The complete bookPDF (PDF - 3.55MB) | Feedback

Customizing Cisco ANA Network Service Activation Scripts

Table Of Contents

Customizing Cisco ANA Network Service Activation Scripts

Before You Begin Script Customization

Cisco ANA Macro Language and BeanShell

Activation Script Example

Verification Checks

Writing Scripts for Service Activations

Script Customization Flow

E-Line Flow Chart

E-Line CLI

Script File Annotations for Configure E-Line Scenario

Registry XML Files

Site XML File

Repository XML File

The DSP-Scripts XML File


Customizing Cisco ANA Network Service Activation Scripts


The following topics provide general information about modifying Cisco ANA NSA scripts. In general, modifying scripts is not recommended because of the detail and the level of experience that is required. Topics include:

Before You Begin Script Customization, page 4-1

Understanding BeanShell Commands, page 4-2

Writing Scripts for Service Activations, page 4-4

E-Line Flow Chart, page 4-6

Registry XML Files, page 4-9

Before You Begin Script Customization

Before you begin any script modifications, you should read and have available for reference the chapter, "Managing and Deploying Configuration Changes Using Command Builder" in the Cisco Active Network Abstraction 3.7 Customization Guide. Be sure you have all the proper permissions and understand the different job policies, and the deployment and scheduling procedures.

Keep in mind that the Cisco ANA NSA activation wizards and workflows were written and tested with the packaged wizards and workflows. Customized activation scripts might require you to customize the Cisco ANA NSA workflows and wizards.


Note Information in this section is not meant to substitute for information provided in the Cisco Active Network Abstraction 3.7 Customization Guide.


Cisco ANA Macro Language and BeanShell

Cisco ANA NSA scripts can be modified using the Cisco ANA Macro Language or BeanShell scripting language. For information about the Cisco ANA Macro Language see "Cisco ANA Macro Language," in the Cisco Active Network Abstraction 3.7 Customization Guide. The most complete resource for using BeanShell is available online at http://www.beanshell.org/. This section only provides guidelines for using BeanShell to create Cisco ANA NSA commands used to interact with the devices.

Unlike Cisco ANA Macro Language, BeanShell user arguments inventory properties should not be embedded within $...$ symbols.

The following examples show the available predefined Telnet environment objects that you can use to interact with a device:

telnetInterface.config ("prompt","telnet command")—Where "prompt" is the expected prompt after the command completes and "telnet command" is the actual command to be executed.

telnetInterface.setStatus (1 or 2)—Where 1=success and 2=fail, used (for example) to signal to workflow manager that a configuration command has succeeded or failed.

Activation Script Example

This section uses an E-Line point-to-point service activation to show how the service is provisioned using the E-Line point-to-point scripts. Figure 4-1 shows the general flow.

Figure 4-1 Carrier Ethernet Service Activation

Cisco ANA NSA activation scripts are designed to be modular and reusable. You can customize or create new service element scripts by reusing the available utility scripts. The scripts are implemented as:

Service element scripts—Implement service logic in the context of one network element.

Utility scripts—Are more granular scripts that implement one atomic action on the device and can be reused by many service element scripts. Utility scripts also implement the rollback logic for their action, making them atomic and self-contained. After the utility script succeeds, the CLI for the task is configured on the device. Likewise, if a utility script is unsuccessful, the utility script does the rollback for that task and no configuration is applied on the device.

Figure 4-2 shows the E-Line service element script and its usage of utility scripts.

Figure 4-2 Configure E-Line Service Element Script

Verification Checks

Cisco ANA NSA scripts resolve errors by going through a series of verification steps on the parameter values to reduce the possibility of a configuration error on the device. The verification checks include:

Verifying all mandatory parameters are entered.

Verifying the parameter values fall within the range expected by the device, for example, VLAN ID, Bridge Domain ID, Service Instance ID, and others.

Verifying that the syntax of the values satisfies the device syntax.

After these verifications are complete, another series of checks are performed against the device. A partial list of checks that might be performed include:

Using show commands on the device to verify the interface required for the service exists.

Verifying the Service Instance ID is already configured.

Verifying the VFI exists.

Verifying the QoS policy that is being attached to the service instance is defined in the device.

After all checks are completed, the script begins employing the utility scripts to download the CLI to the device. During CLI download, if the router returns an error message, error handling and rollback is performed. The utility script returns the error to the service element script and performs the service element level rollback, which includes invoking any "remove" utility scripts for all the configuration that was downloaded and applied. Cisco ANA NSA scripts ensure that the CLI is correctly configured on the device. If errors occur, rollback is performed and correct error messages are generated.

Writing Scripts for Service Activations

Table 4-1 lists the general steps for writing a service activation script. Descriptions include references to the sample E-Line point-to-point script in Script File Annotations for Configure E-Line Scenario, page 4-7.

Table 4-1 Script Design and Implementation Overview 

Step
Task
Description

Step 1 

Convert input parameters to data types as needed.

Cisco ANA supports many data types including string, integer, long, combo and others. Initialize and convert the types required by the script.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Item 5).

Step 2 

Check that all mandatory parameters are entered.

Verify that all parameters required for the script execution are provided by the user. If not, provide the appropriate error message.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Item 6).

Step 3 

Check for range and syntax on parameter values.

A first-level check can be performed within the scripts at this stage. This might include simple verifications such as making sure a VLAN ID is within the proper range or that the entered parameter syntax is within the allowed device range.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Item 7).

Step 4 

Check for existence of objects against the device if needed.

Check the parameter values entered against the device. Checks can include device show requests to verify that the objects expected by the scripts exist. Objects could include interface, service instance, xConnect, QoS policy and others.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Item 7.)

Step 5 

Invoke utility scripts and handle errors.

Call utility scripts to download the applicable CLI to the device. The utility scripts implement rollback so if errors occur while downloading the CLI, all downloaded CLI is removed.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Item 7)

Step 6 

Rollback if errors are encountered.

Using the service element script, handle error conditions and invoke the corresponding remove utility scripts to undo actions taken before the error was encountered. This ensures that under error conditions, all the CLI downloaded to the device is removed.

See Script File Annotations for Configure E-Line Scenario, page 4-7 (Items 2 and 7).


Script Customization Flow

The following steps provide the general flow for script customizations:

1. Create the resource element (utility) BeanShell script (if needed).

2. Create the service element BeanShell script.

3. Use Cisco ANA NetworkVision Command Builder to create the BeanShell scripts to define the interface for the GUI and BQL

a. Run the command to debug and verify.

b. Export the file containing the information that will be extracted in the next step.

4. Create the following XML and jar files:

a. site-ps.xml—Contains the device specific pointer to the "Repository" file (modify if needed).

b. cisco-<technology>-<device type>-scripts-repository.xml (add a new script):

Contains the metadata definition of the service script.

Converts the information created from Step 3 into Cisco ANA NSA script format.

c. cisco-<technology>-DSP.xml (add new script):

Contains the display information for the service script.

Converts the information created from Step c) into Cisco ANA NSA DSP format.

d. The client jar file consists of the DSP file,

5. Installation;

a. Copy the scripts to the scripts directory in the Cisco ANA gateway.

b. Copy the XML files to the registry directory in Cisco ANA gateway.

c. Copy the client jar to webstart/jar directory and update the jnlp file.

d. Restart the server/client.

6. Verification:

The new service script should be available in the Command Builder.

Run Cisco ANA NetworkVision Command Builder on the new command and verify.

E-Line Flow Chart

The E-Line activation includes of the following component scripts:

configure_eline; remove_eline.

add_service_instance_to_interface; remove_service_instance_from_interface.

add_xconnect_to_service_instance; remove_xconnect_from_service_instance.

Figure 4-3 shows the E-Line configuration script flow.

Figure 4-3 Configure E-Line

E-Line CLI

The CLI that runs on the device if the E-Line script succeeds:

conf t
int <Interface Name>
service instance <Service Instance Id> ethernet
encapsulation dot1q <Outer VLAN Tag> [ second-dot1q <Inner VLAN Tag >]
[rewrite ingress tag pop <Rewrite Pop Action>  symmetric]
[rewrite ingress tag push dot1q <Push Outer VLAN Tag>  symmetric]
[rewrite ingress tag push dot1q <Push Outer VLAN Tag>  second-dot1q 
<Push Inner VLAN Tag> symmetric]
[rewrite ingress tag translate 1-to-1 dot1q <Translate VLAN Tag >  symmetric]
xconnect <Peer Device IP> <Tunnel Id> encapsulation mpls
exit
exit
exit

Script File Annotations for Configure E-Line Scenario

Annotated excerpts of the configure_eline service element script BeanShell code is provided below. An ellipsis (...) indicates code that was excerpted because it is not necessary to show the script design principles. For the full configure_eline text and its component utility scripts, see Activation Scripts to Configure E-Line Service, page B-1.

/******* Script to configure e-line *******/

1. The configure_eline utility scripts include:

String sep = File.separator;
...
source("." + sep + "scripts" + sep + "configuration" + sep + "cisco" + sep + 
"add_service_instance_to_interface.bsh");
source("." + sep + "scripts" + sep + "configuration" + sep + "cisco" + sep + 
"add_xconnect_to_serviceInstance.bsh");
...

2. The following function is invoked by the configure_eline service element script when it encounters errors and must roll back. Using the failureLevel parameter, it sends the failure location information. The appropriate utility script is then invoked to undo the operation resulting in an error.

...
void rollback(String  interfaceName,Integer intServiceInstanceId, String failureLevel)
{
            // Function entry message
		telnetInterface.println ("Inside rollback_configure_eline...");		
...
		if (failureLevel =="xconnect") 
		{
		      // invoking utility script to remove service instance from
				// interface
       	     remove_service_instance_from_interface(interfaceName,strServiceInstanceId);
		} 		
		else if(failureLevel == "activate-interface")
		...

3. Set the appropriate status for this function as shown.

		telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_FAILURE );
// Function exit message
 		telnetInterface.println ("rollback_configure_eline done");
		sendResult(false, "The script --configure_eline --failed");

4. This function configures the flex uni eline command set on the device. If errors are encountered, any CLI deployed to the device is immediately removed.

boolean configure_eline(String interfaceName,Integer intServiceInstanceId,String 
outerVlanTag,String  innerVlanTag,String rewritePopAction,Integer 
intPushOuterVlanTag,Integer intPushInnerVlanTag,Integer intTranslateVlanTag,String 
peerDeviceIp,Integer intTunnelId,String activateInterface)
{
	telnetInterface.println("Inside Configure E-Line...");

5. Convert the input parameters to data types as needed.

...
String strPushInnerVlanTag = "";
             if (intPushInnerVlanTag!= null) 
                     strPushInnerVlanTag = String.valueOf(intPushInnerVlanTag);
...
	// handling 'activateInterface' combo input
	String strActivateInterface="";
	if(activateInterface.equals("true"))
	 {
		strActivateInterface="true";
	 }
	else if(activateInterface.equals("false"))
	 {
		strActivateInterface="false";
	 }

6. Check for mandatory parameters.

			// checking if mandatory input interface name is left blank
	if(!checkBlank(interfaceName,"Interface Name"))
	  {
		telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_FAILURE );
		sendResult(false, "The script --configure_eline -- failed");
		return false;
	  }
		...

7. Employ utility scripts to add a service instance, xconnect on a service instance, or if desired, to activate the interface. These utility scripts verify the input parameters before configuring on the device. If an error occurs, the utility script will roll back and return an error so that the service element script can handle the error as needed.

		...
	if(!add_service_instance_to_interface(interfaceName,strServiceInstanceId 
,outerVlanTag,innerVlanTag,strRewritePopAction,strPushOuterVlanTag,strPushInnerVlanTag,str
TranslateVlanTag))
	{
		telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_FAILURE );
		sendResult(false, "The script --configure_eline-- failed");
		return false;
	}
	// invoke the utility script to add xconnect on the service instance. This script 
verifies the input parameters locally as well
      // as against the router before configuring xconnect on service instance. If there 
is an error, returns false.
      // If there is an error configuring xconnect, rollback is called to remove the 
configured service instance.
	
if(!add_xconnect_to_serviceInstance(interfaceName,strServiceInstanceId,outerVlanTag,innerV
lanTag,peerDeviceIp,strTunnelId))
	{
		rollback(interfaceName,intServiceInstanceId,"xconnect");
		telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_FAILURE );
       	return false;
	}
	// Activate the interface if needed.
	if(strActivateInterface.equals("true"))
	{
		if(!activate_interface(interfaceName))
		{
		  telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_FAILURE );
		  rollback(interfaceName,intServiceInstanceId,"activate-interface");
		  return false;
		}
	}	

8. Print the success message and exit.

	sendResult(true, "The script configure_eline was executed successfully");
	telnetInterface.setStatus(CARRIERETHERNET_PROVISIONING_STATUS_SUCCESS );
   	return true;
}
...

9. Invoke configure_eline.

boolean result = configure_eline(interfaceName,intServiceInstanceId 
,outerVlanTag,innerVlanTag,rewritePopAction,intPushOuterVlanTag,intPushInnerVlanTag,intTra
nslateVlanTag,peerDeviceIp,intTunnelId,activateInterface);

Tip For the complete text of the E-Line activation script, along with the utility scripts used for this scenario, see Appendix B, "Sample Text for Activation Scripts to Configure E-Line Service."


Registry XML Files

Cisco ANA NSA is designed to work with the base Cisco ANA. To achieve this, Cisco ANA NSA includes:

Scripts that implement the activation logic.

Registry XML files that provide metadata for the scripts and registers them with the correct VNEs in the Cisco ANA units.

Table 4-2 lists the Cisco ANA NSA registry XML files.

Table 4-2 XML Files in Cisco ANA NSA

File
Description

site-ps.xml

Device-specific pointer to the scripts file.

cisco-<technology>-<device class>-scripts-repository.xml

The metadata definition of each script.

cisco-<technology>-DSP.xml

Specific information for each script.


Site XML File

The site-ps.xml file captures the customization performed by Cisco ANA NSA. The activation modules package edits this file to support new activation scripts on different devices. The following example shows the registration performed by the site-ps.xml file for Cisco 7600 routers. The entry for "76xx" points the Cisco ANA server to a scripts file for all Cisco 7600 VNEs with the MPLS scheme.

...


<key name="site-ps">
  <entry name="default">.sitedefault</entry> 
- <key name="ciscorouter2">
  - <key name="76xx">
    - <key name="ipcore">
    - <key name="software versions">
      - <key name="default version">
    - <key name="imo">
      - <key name="scripts">
       - <key name="com.sheer.imo.IManagedElement">
         - <key name="add_allowed_vlan_to_interface">
             <entry 
             name="default">cisco-carrierethernet-76xx-scripts-repository/add_allo
             wed_vlan_to_interface</entry> 
            </key>
         - <key name="add_l2pt_to_switchport_interface">
             <entry         
              name="default">cisco-carrierethernet-76xx-scripts-repository/add_l2p
              t_to_switchport_interface</entry> 
              </key>
          - <key name="add_mac_acl_to_service_instance">
             <entry 
             name="default">cisco-carrierethernet-76xx-scripts-repository/add_mac_
             acl_to_service_instance</entry> 
            </key>
         - <key name="add_mac_acl_to_switchport">
            <entry 
            name="default">cisco-carrierethernet-76xx-scripts-repository/add_mac_a
            cl_to_switchport</entry> 
           </key>
         - <key name="add_mac_security_to_service_instance">
            <entry 
            name="default">cisco-carrierethernet-76xx-scripts-repository/add_mac_s
            ecurity_to_service_instance</entry> 
          </key>
...

Repository XML File

The repository XML file contains the script definition, similar to the XML configuration written by Cisco ANA to the VNE AVM when you create a script using Command Builder. The definition describes the script, lists the parameters the script expects, and the name and relative path of the BeanShell file as shown in the following example:

- <key name="cisco-carrierethernet-34xx-scripts-repository">
  - <key name="add_allowed_vlan_to_interface">
  <entry name="default">voids</entry> 
  <entry name="metadata-id">76xx</entry> 
  <entry name="error-condition" /> 
  <entry name="interface">telnet</entry> 
  <entry name="script-name">add_allowed_vlan_to_interface</entry> 
  <entry name="language">beanshell</entry> 
  <entry name="enable">true</entry> 
  - <key name="parameters">
- <key name="0">
  <entry name="type">java.lang.String</entry> 
  <entry name="name">interfaceName</entry> 
</key>
- <key name="1">
  <entry name="type">java.lang.String</entry> 
  <entry name="name">outerVlanTag</entry> 
</key>
  </key>
  <key name="enums" /> 
  - <key name="roles">
  <entry name="Administrator" /> 
  <entry name="OperatorPlus" /> 
  <entry name="Operator" /> 
  <entry name="Viewer" /> 
  <entry name="Configurator" /> 
  </key>
  <key name="rollback" /> 
  - <key name="script">
  <entry 
name="file-name">configuration/cisco/ce/add_allowed_vlan_to_interface.bsh</entry> 
    </key>
  </key>


The DSP-Scripts XML File

The DSP-Scripts file contains all display parameters that are required for the Cisco ANA NSA client to correctly display the script name and configuration. Its content is similar to the XML written by Cisco ANA to the site.xml file when you create a script using Command Builder.


- <key name="cisco-carrierethernet-DSP">
  - <key name="add_allowed_vlan_to_interface">
   - <key name="metadata">
    - <key name="76xx">
    <entry name="short-description">add_allowed_vlan_to_interface</entry> 
    <entry name="display-name">add_allowed_vlan_to_interface</entry> 
    <entry name="menu-path">Commands</entry> 
    <entry      name="class-name">com.sheer.client.common.components.scripts.
    GenericScriptsController</entry> 
    <entry name="multiple-selection">false</entry> 
    <entry name="icon">toolbar/Run_Command</entry> 
    <entry name="visible">true</entry> 
    <entry name="location">100</entry> 
  - <key name="parameters">
    - <key name="interfaceName">
    <entry name="visible">true</entry> 
    <entry name="default-value" /> 
    <entry name="width">15</entry> 
    <entry name="required">true</entry> 
    <entry name="location">0</entry> 
    <entry name="display-name">Interface Name*</entry> 
    <entry name="enabled">true</entry> 
      </key>
  - <key name="outerVlanTag">
    <entry name="visible">true</entry> 
    <entry name="default-value" /> 
    <entry name="required">true</entry> 
    <entry name="width">15</entry> 
    <entry name="location">1</entry> 
    <entry name="display-name">Outer VLAN Tag*</entry> 
    <entry name="enabled">true</entry> 
  </key>
     </key>
    </key>
   </key>
      </key>
...