Cisco Active Network Abstraction Network Service Activation 1.0 Customization Guide, 3.7
Cisco ANA Network Service Activation Customization Concepts
Downloads: This chapterpdf (PDF - 326.0KB) The complete bookPDF (PDF - 3.55MB) | Feedback

Cisco ANA Network Service Activation Customization Concepts

Table Of Contents

Cisco ANA Network Service Activation Customization Concepts

Cisco ANA NSA Customization Elements

Activation Wizard Files

Activation Workflows

Activation Scripts

Service Activation Flow

Cisco ANA NSA Design Principles

Cisco ANA NSA Customization Tools

Cisco ANA NSA Customization Flow

Backing Up and Restoring Customized Files

Where to Go From Here


Cisco ANA Network Service Activation Customization Concepts


The following topics provide an overview to the Cisco Active Network Abstraction Network Service Activation 1.0 (Cisco ANA NSA) customization concepts and processes:

Cisco ANA NSA Customization Elements

Service Activation Flow

Cisco ANA NSA Design Principles

Cisco ANA NSA Customization Flow

Backing Up and Restoring Customized Files

Where to Go From Here

Cisco ANA NSA Customization Elements

Cisco ANA NSA customizations are performed on three file types:

Wizards—XML files that contain the activation attributes and control display and behavior of the activation wizards launched from Cisco ANA NetworkVision.

Workflows—XML files created with Cisco ANA Workflow Editor that control the activation flow on the network devices identified in the activation wizards.

Scripts—BeanShell files containing the Telnet and CLI sequence to complete service activations at devices identified in the activation wizards at the direction of the activation workflows.

Customizing these files requires different approaches and tools. To customize a wizard, you download it from the gateway to a local drive, edit it with an XML or text editor, then upload it to the gateway. You can download individual wizard files using the Cisco ANA NSA Service Modification Utility, which is located in the Cisco ANA NetworkVision Activation menu. Simple changes, such as changing an attribute display name or removing an attribute, can be accomplished in minutes. More complex customizations take longer and require more planning.

To customize a workflow, you open Cisco ANA Workflow Editor and download the files using the Workflow Editor download function. You use Workflow Editor to perform all activation workflow customizations. When completed, you upload the workflows using the Workflow Editor upload function. Customizing workflows requires familiarity with the Workflow Editor, familiarity with programming logic, and intimate knowledge of the workflow service activation objective.

Script customization requires knowledge of BeanShell and scripting, as well as knowledge of the CLI sequence at the device level. To customize scripts, you use the Cisco ANA Command Builder. Command Builder is described in the Cisco Active Network Abstraction 3.7 Customization User Guide. However, script customization is not recommended unless you have knowledge and experience in these areas.

Activation Wizard Files

Service activation wizards include the following files and file types:

Service.xml—Defines the Activation window service activation tree that appears after the operator launches the Activations menu item in Cisco ANA NetworkVision. The file defines the tree sequence and display names. It also links tree items to the appropriate pages and activation files that will be invoked when the operator chooses an item from the Activation tree. Only one Service.xml file is in effect at any given time.

Pages files—Define the wizard pages display and behavior in Cisco ANA NetworkVision GUI.

Activation files—Contain the attribute values collected by the pages file. Activation files provide the attribute inputs entered by operators to the activation workflows.

Macro files—Contain subroutines called by pages files to perform short, directed actions such as retrieving a list of devices to populate the Device attribute or retrieving a list of device interfaces.

Pages and activation files function in pairs. One controls the wizard content and behavior; the other maps the collected wizard inputs to the workflow inputs.


Note The pages and activation files provided in the delivered Cisco ANA NSA package contain the word "Pages" and "Activation" in their file names to make file tracking easier. This practice is not required, but is recommended.


Activation Workflows

Service activation workflows take the attribute inputs collected by the wizards and guide the activations and device provisioning sequences. A workflow is comprised of tasks arranged in a hierarchy or other logical sequence. Workflows run the logical flow of activation commands, including rollback scenarios. The workflow author defines relationships between tasks, including sequences, branches, failure procedures, access to Cisco ANA commands as well as the information model. To customize activation workflows, you use the Cisco ANA Workflow Editor., which is described in the Cisco Active Network Abstraction 3.7 Customization User Guide.

Activation Scripts

Service activation scripts contain the CLI sequence, including Telnet commands, to activate services or create elements on devices following the workflow tasks and with the attribute inputs provided by operators in the activation wizards. Scripts can be modified, but customization requires familiarity with BeanShell and/or the Cisco ANA Macro Language. The Cisco ANA Macro Language is described in the Cisco Active Network Abstraction 3.7 Customization Guide. BeanShell is a small, free, embeddable Java source interpreter with object scripting language features. BeanShell is written in Java. It dynamically executes standard Java syntax and extends it with common scripting conveniences such as loose types, commands, and method closures like those in Perl and JavaScript. (The most complete resource for using BeanShell scripting language is available at http://www.beanshell.org/.)

Although script customization is possible, keep in mind that the service activation scripts provided with Cisco ANA NSA service activation scripts were designed and tested against with Cisco ANA NSA 1.0 wizards and workflows.

Cisco ANA NSA activation scripts are located in: $ANAHOME/Main/scripts/configuration/cisco/ce Over 130 scripts are provided with Cisco ANA NSA. Scripts are divided into groups based on the key action the script performs:

Activate

Add

Configure

Create

Modify

Remove

Cisco ANA NSA activation workflows call anywhere from four to six scripts to perform specific functions at different points in the workflow process.

Service Activation Flow

The Cisco ANA NSA wizards, workflows, and scripts work together to facilitate device provisioning and service activations. Table 1-1 shows the general flow.

Table 1-1 Cisco ANA NSA Process 

Action
Files Involved
File Type

From NetworkVision Activation menu, operator chooses Activation.

Service.xml

Wizard

Operator expands the Activation tree and chooses a service activation.

The pages and activation files for the activation selected by the operator display the activation wizard.

Service.xml >>>

[activation name]Pages.xml

[activation name]Activation.xml

Wizard

Operator enters service activation data.

[activation name]Pages.xml

Wizard

Operator completes the wizard.

[activation name]Pages.xml

[activation name]Activation.xml

Wizard

After completing all attributes, operator clicks Finish.

[activation name]Activation.xml

[activation name] Workflow

Wizard

Workflow

The activation workflow completes its tasks. It calls activation scripts to perform specific functions.

[activation name] Workflow

[function] scripts

Workflow

Script

The workflow receives success/failure input from devices. Based on that input, the workflow performs completion or rollback tasks.

[activation name] Workflow

[function] scripts

Workflow

Script

The workflow output is sent to the Cisco ANA NSA Service Activation List. The operator can view the results and view the workflow output (Figure 1-1).

[activation name] Workflow

Workflow


Upon completion of the activation process, operators view results in the Service Activation List window. Depending on the results, the operator can start again, or begin a new activation.

Figure 1-1 Service Activation List Window

The number of activations displayed in the Service Activation List window is set in the Cisco ANA registry cvm.xml with key="service-activation-list" and entry="retrieval-block-size". The current default is 1500. You can change the value of this setting using the runRegTool command, which is located in ANAHOME/Main.


Caution Before you change the Cisco ANA registry, review "Working with the Registry," in the Cisco Active Network Abstraction Administrator Guide 3.7.

The maximum number of activations that can be displayed is 15000. Keep in mind, a trade off exists between the number of activations displayed and performance. The higher the number of activations displayed, the longer it will take for the Service Activation List window to populate.

To change the Service Activation List activations display:


Step 1 Change to the Main directory:

% cd Main

Step 2 Using the runRegTools command, set the new activations display:

% ./runRegTool.sh -gs 127.0.0.1 set 0.0.0.0 
cvm/service-activation-list/retrieval-block-size "new-number"

For example:

./runRegTool.sh -gs 127.0.0.1 set 0.0.0.0 cvm/service-activation-list/retrieval-block-size 
10000

Step 3 Restart Cisco ANA NetworkVision.


For more information about viewing service activation results, see the Cisco Active Network Abstraction Network Service Activation 1.0 User Guide.

Cisco ANA NSA Design Principles

Cisco ANA NSA wizards, workflows, and scripts were developed following design principles that you should consider when customizing Cisco ANA NSA. Failure to follow these principles in your customization might cause inefficient or incomplete activations.

Cisco ANA NSA scripts follow two key principles:

Error handling—Scripts must anticipate errors and provide for adequate recovery sequences at all script levels.

Atomic design—Script development or customization should be as atomic as possible. That is, if any script sequence fails, the entire operation should fail; all devices must be restored to the state they were in before the script operation began.

Similar design principles apply to Cisco ANA NSA workflows:

Exception handling—Workflows must anticipate and adequately account for exception occurrences.

Rollback (best effort)—Workflows must roll back all completed operations whenever exceptions occur before the entire workflow is completed. For example, if a workflow completes activations on multiple devices, and an exception occurs on the last device, all completed device activations must be rolled back to ensure device consistency.

Service removal (best effort)—The built-in roll back capability is extended to allow operators to remove (deactivate) activations through the Cisco ANA NSA Service Activation List.

Multi-platform and inter-platform capability—All workflows must be designed to operate on multiple platforms.

Cisco ANA NSA Customization Tools

Customizing Cisco ANA NSA requires the following tools:

Wizards—You can use any text or XML editor that does not add a Byte Order Mark (BOM) to the UTF-8 XML. Cisco ANA NSA does not recognize XML with BOMs. XML editors that have been used with Cisco ANA NSA include NotePad++, XMLPad, and XMLSpyR.

Workflows—You must use the Cisco ANA Workflow Editor. For information, see the Cisco Active Network Abstraction 3.7 Customization User Guide.

Scripts—You can use the Cisco ANA Command Builder. For information, see the Cisco Active Network Abstraction 3.7 Customization User Guide.

Cisco ANA NSA Customization Flow

The following steps outline the general flow you must follow when creating a new Cisco ANA NSA service activation.

1. Create the Scripts—See Chapter 4, "Customizing Cisco ANA Network Service Activation Scripts."

2. Create Workflows—Chapter 3, "Customizing Cisco ANA Network Service Activation Workflows."

3. Create Service Activation Wizard—Chapter 2, "Customizing Cisco ANA Network Service Activation Wizards."

Create the pages file.

Create the activation file.

Add the new service into the Service.xml file.

Backing Up and Restoring Customized Files

Cisco ANA backup and restore functions back up data placed in the $ANAHOME/Main/to_backup directory as well as Cisco ANA registry data. In Cisco ANA, Release 3.7, the Oracle database is removed from Cisco ANA backups. The database must be backed up following Oracle database backup procedures.

The general Cisco ANA NSA backup and restore process prior to installation of a new Cisco ANA version includes the following:

1. Backup user data—See "Backing Up and Restoring the Registry," in the Cisco Active Network Abstraction Administrator Guide 3.7.

2. Uninstall Cisco ANA—See the Cisco Active Network Abstraction Installation Guide 3.7.

3. Install Cisco ANA—See the Cisco Active Network Abstraction Installation Guide 3.7.

4. Install Cisco ANA NSA—Cisco Active Network Abstraction Network Service Activation 1.0 Installation Guide.

5. Restore user data—See "Backing Up and Restoring the Registry," in the Cisco Active Network Abstraction Administrator Guide 3.7.

When customizing Cisco ANA NSA wizards, workflows, and scripts, review the following notes to ensure customized files are adequately backed up.

Customized wizards—If you customize Cisco ANA NSA wizards using the Service Modification Utility (see Downloading and Uploading Wizard Files, page 2-22), customized wizards are uploaded to $ANAHOME/Main/to_backup/MetadataDirectory/Custom. These files will be automatically backed up during the next Cisco ANA registry backup.

Customized scripts—If you customize Cisco ANA NSA scripts, you must manually place the scripts in the $ANAHOME/Main/to_backup in order for them to be backed up during the next the next Cisco ANA registry backup.

Customized workflows—All Cisco ANA workflows, including Cisco ANA NSA workflows, are kept in the Cisco ANA Oracle database. Backing up and restoring customized Cisco ANA NSA workflows should follow Oracle database backup and restore practices established at your site. For additional information, see "Workflow Administration Tasks," in the Cisco Active Network Abstraction Administrator Guide 3.7.


Note Always rename customized workflows. If you do not rename the workflows, they might be overwritten during the next Oracle utility database restoration.


Where to Go From Here

Any Cisco ANA NSA wizard, workflow, or script customization requires planning and forethought. If you are just getting started, the sequence below is a general approach you might consider:

1. Review your service activation requirements. Specifically, what type of service, what attributes, and what devices are involved? A strong knowledge of the provisioning that occurs at the device level is required.

2. Review the provided Cisco ANA NSA scripts, workflows, and wizards.

3. Create a detailed customization specification that answers the following questions.

a. Can the customization be handled through wizard customization alone? Attribute display name changes are one wizard customization that can be performed without workflow customization. For an example, see Chapter 6, "Cisco ANA Network Service Activation Customization Examples." You can remove optional attributes if they are never entered in your specific service activation. You can also customize the Activation tree, for example, remove activations your operators will never use.

b. Can existing workflows be used to handle the customization? If yes, identify the workflow and specific customizations that must be made.

c. If provided workflows cannot be used, do the provided scripts cover the customization requirements? If yes, you can begin planning the new workflow. If no, you will need to contact Cisco consulting services for support.

Table 1-2 provides a list of resources to help you with the customization details.

Table 1-2 Cisco ANA NSA Customization Resources 

Topic
Reference
Description

Scripts

Appendix A, "Cisco ANA Network Service Activation Scripts"

Master list of all scripts included in Cisco ANA NSA.

Scripts

Workflows

Chapter 5, "Cisco ANA Network Service Activation Workflows"

Lists the scripts called by each workflow.

Scripts

Chapter 4, "Customizing Cisco ANA Network Service Activation Scripts"

General information about Cisco ANA scripts and script customization.

Scripts

"BeanShell Commands," Cisco Active Network Abstraction 3.7 Customization User Guide.

Overview on the use of BeanShell commands in Cisco ANA.

Workflows

Chapter 3, "Customizing Cisco ANA Network Service Activation Workflows"

Provides information about customizing Cisco ANA NSA workflows.

Workflows

"Using the Workflow Editor to Create Task Workflows," Cisco Active Network Abstraction 3.7 Customization User Guide

Provides general information about using the Cisco ANA Workflow Editor.

Wizards

Chapter 2, "Customizing Cisco ANA Network Service Activation Wizards"

Provides information about customizing Cisco ANA NSA wizards.

Examples

Chapter 6, "Cisco ANA Network Service Activation Customization Examples"

Provides step-by-step Cisco ANA NSA customization examples.