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

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

Customizing Cisco ANA Network Service Activation Wizards

Table Of Contents

Customizing Cisco ANA Network Service Activation Wizards

Metadata Files Overview

The Service.xml File

Pages Files

Activation Files

Macro Files

Services.xml Attributes

Pages Metadata

Pages Example

Activation Metadata

Downloading and Uploading Wizard Files

Customizing Wizard Files General Flow


Customizing Cisco ANA Network Service Activation Wizards


The following topics provide detailed information for customizing Cisco ANA NSA wizards. Topics include:

Metadata Files Overview

Services.xml Attributes

Pages Metadata

Activation Metadata

Downloading and Uploading Wizard Files

Metadata Files Overview

Service activation wizards are built with the following metadata files:

Service.xml file

Pages files

Activation files

Macro files

The Service.xml File

Service.xml defines the Activation window service activation tree (Figure 2-1) that appears after the operator chooses the Activations item from the Cisco ANA NetworkVision Activation menu. The file defines the tree sequence and display names. It also links tree items to the appropriate pages and activation files that are invoked after the operator chooses an item from the Activation tree.


Note Only one Service.xml file is in effect at any given time.


Figure 2-1 Service Activation Window

Pages Files

Pages files define the activation wizard name, display, and behavior in the Cisco ANA NetworkVision GUI. Figure 2-2 shows the first E-Line point-to-point activation wizard panel. This panel, and all panels within the E-Line point-to-point wizard, are controlled by the ELINEPages.xml file.

Figure 2-2 Activation Wizard Page Example

Activation Files

Activation files map the attributes defined in the pages file to the input parameters in the activation workflows. You can also assign constants or special variables.

Activation and pages files function in pairs. Table 2-1 lists the pages and activation file pairs that are provided in the delivered Cisco ANA NSA package.

Table 2-1 Wizard Pages and Activation Files 

Wizard
Page and Activation Files

Create E-LAN VPLS Hub

ELAN_HUBPages.xml

ELAN_HUBActivation.xml

Create E-LAN VPLS Neighbor

ELAN_VPLS_NeighborPages.xml

ELAN_VPLS_NeighborActivation.xml

Create E-LAN H-VPLS Hub Neighbor

ELAN_HVPLS_HUB_NBRPages.xml

ELAN_HVPLS__HUB_NBRActivation.xml

Create E-LAN H-VPLS Spoke

ELAN_HVPLS_SpokePages.xml

ELAN_HVPLS__SpokeActivation.xml

Create E-Line Point-to-Point Service

ELINEPages.xml

ELINEActivation.xml

Create Multipoint EFP

ELANEFPPages.xml

ELANEFPActivation.xml

Create Access

AccessPages.xml

AccessActivation.xml

Create Layer 3 VPN Service

L3VPNPages.xml

L3VPNActivation.xml

Create TDM Pseudowire Service

MToP_TDMActivation.xml

MToP_TDMPages.xml

Create ATM Pseudowire Service

Create_ATM_Pseudowire_Service_Activation.xml

Create_ATM_Pseudowire_Service_Pages.xml

Create Clock Synchronization

MToP_SynchronizationActivation.xml

MToP_SynchronizationPages.xml

Create HSI Point to Multipoint

HSIActivation.xml

HSIPages.xml

Create Layer 2 ACL

ACLPages.xml

ACLActivation.xml

Create QoS Policy

QosPages.xml

QosActivation.xml

Add MAC Secure Addresses

MacSecureAddressPages.xml

MacSecureAddressActivation.xml


Macro Files

Macro files implement macros, which are called by pages files to perform specific actions such as retrieving a list of devices or device interfaces to populate wizard combo box attributes. A macro file implements a particular query. Cisco ANA NSA also provides a macro index file, Macro.xml. Macro.xml contains a catalog of available macro files in the system. Table 2-2 lists the shipped Cisco ANA NSA macro files.

Table 2-2 Cisco ANA NSA Macros 

Name
File
Description

Get All Devices Macro

GetDevices.xml

Gets all devices to populate the Device attribute.

Get All 7600 Devices Macro

GetDevices7600.xml

Gets all Cisco 7600 Series Routers to populate the Device attribute.

Get All 9000 Devices Macro

GetDevices9000.xml

Gets all Cisco 9000 Series Routers to populate the Device attribute.

Get All 7600/9000 Devices Macro

GetDevices7600_9000.xml

Gets all Cisco 7600 and 9000 Series Routers to populate the Device attribute.

Get All 3400/3750/4500 Devices Macro

GetDevices3400_3750_4500.xml

Gets all Cisco 3400, Cisco 3750, and Cisco 4500 Series Switches to populate the Device attribute.

Get All MToP Devices Macro

GetDevicesMToP.xml

Gets all Cisco 2941 Series Switches and Cisco 7600 Series Routers to populate the Device attribute.

Get Devices by Map Macro

GetDevicesByMap.xml

Enables operators to select devices from the NetworkVision map.

Get All 7600 Devices by Map Macro

GetDevices7600ByMap.xml

Populates the Device attribute with the Cisco 7600 device selected by the operator from the NetworkVision map.

Get All 9000 Devices by Map Macro

GetDevice9000ByMap.xml

Populates the Device attribute with the Cisco 9000 device selected by the operator from the NetworkVision map.

Get All 7600/9000 Devices by Map Macro

GetDevices7600_9000ByMap.xml

Populates the Device attribute with the Cisco 7600 or Cisco 9000 device selected by the operator from the NetworkVision map.

Get All 3400/3750/4500 Devices by Map Macro

GetDevices3400_3750_4500ByMap.xml

Populates the Device attribute with the Cisco 3400, Cisco 3750, or Cisco 4500 device selected by the operator from the NetworkVision map.

Get All MToP Devices by Map Macro

GetDevicesMToPByMap.xml

Populates the Device attribute with MToP devices from the Cisco ANA NetworkVision map.

Get All Interfaces of a Device Macro

GetInterfaces.xml

Populates the Interfaces attribute based on the operator selection in the Device attribute.

Get All MToP Controller Interfaces of a Device Macro

GetControllerInterfacesMToP.xml

Populates the MToP Controller Interfaces attribute based on the operator selection in the Device attribute.

Get All Virtual CEM Interfaces of a Device Macro

GetVirtualCEMInterfaces.xml

Populates the CEM Virtual Interfaces attribute based on the operator selection in the Device attribute.

Get the device IP Address Macro

GetDeviceIp.xml

Gets the device IP address.

Get Device Family Macro

GetDeviceFamily.xml

After the user enters a device name, gets the device family. This macro is used for Cisco 7600 and Cisco 9000 Series routers.

Get Device Family 3400/3750/4500 Macro

GetDeviceFamily3400_3750_4500.xml

After the user enters a device name, gets the device family and populates the Platform attribute. This macro is used for Cisco 3400, Cisco 3750, and Cisco 4500 Series switches.

Get ATM Interfaces

GetATMLogicalInterfaces.xml

Retrieves all ATM interfaces.

Get ATM Regular Interfaces

GetATMRegularInterfaces.xml

Retrieves all ATM regular interfaces.


Services.xml Attributes

The Service.xml file metadata defines the Activation window (Figure 2-1) activation tree text and organization. It also defines the pages and activation files that will be called when the operator makes a window selection.

Service.xml is comprised of IMetaDataList entries. Each IMetaDataList entry describes one item in the Service.xml file. Table 2-3 lists the tags that are included in an IMetaDataList entry.

Table 2-3 Service.xml IMetaDataList Metadata

Metadata
Type
Description

<ID>

OID

Free form text that must be unique in the IMObject_Array. The ID is a unique identifier for the service listing entry.

<Name>

String

The display name that appears in the Activation window service activation list and the Service Activation List window.

<ActivationId>

OID

The activation file that is called when the activation tree item is selected. See Table 2-1.

<Type>

String

A "/" delimited set of values. The delimited values are used to create a folder hierarchy in the service listing page.

<Display>

Boolean

Determines whether an entry is displayed. You can use this option to hide an entry if it is deprecated but deployed activations still use the information (needed for those deployed activations to be deactivated).

<Order>

Integer

Determines the ordering of the information in the listing:

Folders specified by the <Type> tag take on the order of the lowest associated OrderValue.

Within a folder, contents are listed from lowest OrderValue to highest OrderValue.

The lowest valued OrderValue is displayed first at the top of the
Activation window service listing.

PagesId

OID

The pages file that is called when the activation tree item is selected. Table 2-1.


Figure 2-3 shows the Service.xml IMetaDataList metadata for the Create E-LAN VPLS Hub.

Figure 2-3 Service.xml Metadata

1

<ID>

5

<Display>

2

<Name>

6

<Order>

3

<ActivationId>

7

<PagesId>

4

<Type>

   

Pages Metadata

Pages files define the Cisco ANA NSA activation wizard display and behavior in the Cisco ANA NetworkVision GUI. Customizing pages files requires a clear understanding of the required service attributes, the metadata types, for example, string or an array, and the attribute dependencies, for example, whether or not attributes require an entry in another attribute. Additional information is provided in the following topics:

Pages Example, provides a detailed look at a pages file for Create E-LAN VPLS Hub wizard.

Pages XSD, page C-1, provides the metadata schema (XSD) for Cisco ANA NSA pages files.

Pages Example

The following example shows the pages metadata used to create the Create E-LAN VPLS Hub wizard (Figure 2-4).

Figure 2-4 Create E-LAN VPLS Hub Activation Window Entry

A wizard consist of a linear sequence of pages and iterations. An iteration is a collection of pages used to collect zero or more sets of the same information. After the user chooses Create E-LAN VPLS Hub in the Activation window, the Add Multiple E-LAN Hubs page appears (Figure 2-20). This page is a "basket." It collects multiple iterations of data. As iterations of wizard pages are completed, entries appear in the Add Multiple E-LAN Hubs list.

Figure 2-5 E-LAN VPLS Hub Wizard Collection Page

The E-LAN VPLS Hub wizard consists of a single iteration composed of two wizard pages. Figure 2-6 shows the first page.

Figure 2-6 E-LAN VPLS Hub First Wizard Page

Figure 2-7 shows the second page.

Figure 2-7 E-LAN VPLS Hub Second Wizard Page

Figure 2-8 shows a high-level view of the ELAN_HUBPages.xml. Attributes include:

<IMetaDataPages>—Outermost tag for the page metadata.

<Pages>—Contains the definition for each wizard page.

<IterationData>—Contains the definitions of the iterations in the wizard flow.

<GroupData>—Contains definitions of attribute or enum groups. Attribute groups are sets of attributes that are conditionally enabled based on the value of other attribute(s). Enum groups are values of a combo box (drop-down menu) that are conditionally present based on the value of other attribute(s).

Figure 2-8 ELAN_HUBPages.xml High Level View

1

<IMetaDataPages>

3

<IterationData>

2

<Pages>

4

<GroupData>


Figure 2-9 shows a first-level expansion of the Figure 2-8 categories:

<Pages>—Shows that the wizard contains two defined pages.

<IterationData—Shows that the wizard contains one iteration.

<GroupData>—Shows that the wizard contains thirteen attribute/enum groups.

Figure 2-9 ELAN_HUBPages.xml Expanded View

1

<Pages>

3

<GroupData>

2

<IterationData>

   

Figure 2-10 shows the page numbering, sequence, and display name:

<ID>—Defines the page ID. The first defined page in this example is Page1 based on the value of the tag. The second page is Page2.

<StepDisplayName>—Specifies the label that will appear in the wizard page. In this example, it is Add Multiple E-LAN Hubs. Here, the same display name is used for Page1 and Page2, but different display names could be used.

<Order>—Specifies the page sequence. Lower number pages are displayed first.

<Attributes>—Contains the page attributes.

Figure 2-10 ELAN_HUBPages.xml Page Number, Display Name, and Order

1

<ID> for first page (Page1)

5

<Attributes> for Page2 (not expanded)

2

<Attributes> for Page1 (not expanded)

6

<Order> for Page2 (2)

3

<Order> for Page1 (1)

7

<StepDisplayName> for Page1 and Page2 (Add Multiple E-LAN Hubs)

4

<ID> for second page (Page2)

   

Figure 2-11 shows the Page1 <Attributes> expanded to the first level. Page1, which defines the E-LAN hub wizard page shown in Figure 2-6, has 23 attributes.

Figure 2-11 ELAN_HUBPages.xml Page1 Attributes

1

<ID> for first wizard page (Page1).

2

<Attributes> for Page1 expanded to the first level.


Figure 2-12 shows the first Page1 attribute definition:

<ID>—Specifies the first attribute wizard model ID. Here, the ID is "Device".

<AttributeDisplayName>—Shows label that will be displayed within the wizard GUI. In this example, the display name is "Device:".

<Type>—Indicates the attribute type. Options are "String", "Integer", "combo". A "combo" type is a drop-down menu.

If <Type> = combo, <SelectionType> indicates whether the values of the combo box are statically defined (value = Static) or dynamically queried against the Cisco ANA model using a macro (value = Dynamic).

If the attribute is a dynamic combo box, the macro used to query the values is specified using the <ComboValueMacro> tag. In this example, it is GetDevices7600_9000ByMap.

If a macro is used, <ComboValueParameters> specifies the arguments to the macro. In this example, an implicit attribute, $MAP$, is the only argument provided to the macro. Activation files can be used to assign constants or special variables to workflow input parameters. $MAPS is the name of the map currently open in NetworkVision. It is primarily used in the pages metadata as an argument to a macro. $COUNT$, another argument that can be used, defines the number of entries for an iteration and is typically used in the activation metadata to assign this value to a workflow attribute.

If <SelectionType> is set to "Static", an additional tag, <StaticComboValues>, is used to specify the values.

<IMOType>—If used, indicates that the Cisco ANA NetworkVision topology or IMO tables can be used to select an object to populate the attribute value. Only Cisco ANA NetworkVision objects that match the indicated class can be selected using the object's context menu item Activation -> Add To Activation, shown in Figure 2-12

If the selected object's type does not match, the menu item is disabled.

<IMOPropertyName> specifies the name of the property to use when the appropriate IMO object is selected. In this example, the DeviceName property of the IManagedElement IMO object is used.

Figure 2-12 Add to Activation Menu

<Required>—Indicates whether the attribute must take a value, that is, the attribute is required and the operator must enter a value.

<Order>—Indicates the sequence of this attribute on the page. Lower value attributes are listed first.

Figure 2-13 ELAN_HUBPages.xml First Page1 Attribute

1

<ID>

6

<Order>

2

<Required>

7

<ComboValueParameters>

3

<AttributeDisplayName>

8

<StringValue>

4

<ComboValueMacro>

9

<IMOPropertyNames>

5

<Type>

   

Figure 2-14 shows the RewritePopAction attribute. It is a static combo type.

<StaticComboValues>—Specifies the values of the static combo. In this example, the combo box displays options "none", "1", and "2".

<DefaultValue>—Specifies the default value. This value may either be a fixed value, such as "none," or an attribute reference, which is used in this example. In this example, the reference used is a reference back to itself. In this case, the page is part of an iteration and <DefaultValue> is used to populate the initial value as a default for subsequent iterations through the page.

<DefaultDisabledValue>—Can be used to override the attribute grouping feature and specify an alternate value for a disabled attribute. Attribute grouping can be used to disable attributes. In such cases, disabled attributes typically take an empty ("") value. To override this behavior and specify an alternative value, you can use <DefaultDisabledValue>. In this example, the attribute contains a value of "none" when it is disabled.

Figure 2-14 ELAN_HUBPages.xml RewritePopAction Attribute

1

<DefaultDisabledValue>

3

<StaticComboValues>

2

<DefaultValue>

   

Figure 2-15 shows an <IterationData> group. In this example, a single iteration is defined called "loop1." It includes a Page1 and Page2. The included set of pages must be sequential.

Figure 2-15 ELAN_HUBPages.xml Iteration Data

Figure 2-16 shows a grouping example. 7600Group is the group that contains Cisco 7600 attributes. When the attribute specified by <DependentSelectionAttribute> is set to the value (or one of the values) specified by <DependentSelectionValue>, the attributes specified in <AttributeNames> and enumerations specified in <ComboAttributeProperties> are enabled (unless another group disables it).

<DependentSectionValue> might contain an "|" delimited set of values. In this example, the value could be set to "7600|7500|7000" to enable values for multiple platform types. If $Page1.Platform$ = "7600", the "$Page1.VlanId$" attribute is enabled and combo attribute $Page1.RewriteTranslationAction$ will contain values "none" and "1-to-1".

Figure 2-16 ELAN_HUBPages.xml 7600Group

1

<ID>

4

<AttributeNames>

2

<DependentSelectionValue>

5

<ComboAttributeProperties>

3

<DependentSelectionAttribute>

   

Activation Metadata

Activation files map the attributes defined in the wizard pages file to the input parameters in the activation workflows. Activation files are divided into two broad blocks:

Steps—Map the wizard attributes to the workflow attribute.

RepeatSteps—Identify steps that correspond to iterations within the pages metadata. Wizard attributes that are members of a step included in the block can potentially take on multiple values. The block provides the activation feature the awareness to know how to pack and delimit the multiple attribute values that will be sent to the workflow.

The following examples are from the L3VPNActivation.xml. The L3VPN wizard is organized as two iterations. These are each composed of two pages.

Figure 2-17 shows the high-level structure of the L3VPNActivation.xml file:

<ID> is the name of the activation

<WorkflowTemplateName> identifies the associated workflow that is invoked at the end of the wizard.

<ActivationName> is the label that will be shown on the wizard when the workflow is invoked.

L3VPNActivation.xml contains two <IMetaDataStep> steps and two <IMetaDataIteration> repeat steps. <ID> identifies the first step: Configure L3VPN Sites. The Configure L3VPN Sites step contains 22 wizard attribute to workflow parameter mappings. These are defined in the <IMetaDataAttribute> blocks.

Figure 2-17 L3VPNActivation.xml High Level View

1

<ID>

4

IMetaDataStep <ID>

2

<WorkflowTemplateName>

5

<IMetaDataAttributes>

3

<IMetaDataStep>

   

Figure 2-18 shows the L3VPNActivation.xml file with two mapping blocks expanded:

The NSA_L3VPN.template workflow parameter, "deviceName_list" is obtained from the wizard attribute, Pages.Page1.Device.

The NSA_L3VPN.template workflow parameter, "interfaceName_list" is obtained from the wizard attribute, Pages.Page2.InterfaceName.

Each step does not need to contain attributes from a single page. If the wizard only contains a linear page flow, all attributes can be defined within a single step. The step is needed to group attributes that are part of a wizard iteration.

Figure 2-18 L3VPNActivation.xml File Expanded Mapping Blocks

1

MetaDataAttribute (deviceName_List)

3

MetaDataAttribute (interfaceName_List)

2

Wizard attribute (Pages.Page1.Device)

4

Wizard attribute (Pages.Page2.Device)


Figure 2-19 shows an expanded view of the first L3VPNActivation.xml step:

<ID>—Identifies the name of the step. In this example, it is "repeat1".

<Required> —Indicates that the step is required.

<IterationNames>—The set of steps that will be processed as a RepeatStep. In this example, the Configure L3VPN Sites step can be processed multiple times. This directs the activation feature to assign the attributes from the Configure L3VPN Sites step with potential multiple "|" delimited values. As an example, "deviceName_list" could be assigned the value "device1|device2|device3". The workflow can decide to tokenize the parameter to extract each value.

Because a wizard iteration can populate zero or more times, it is possible for wizard attributes within an iteration to never populate. It is possible to control whether the activation feature even attempts to send a workflow the parameters for these attributes. Setting <Required> to "false" directs the activation feature to not send values for parameters that are not populated within the wizard. For this feature to work, the workflow must provide default values for these parameters.

Figure 2-19 L3VPNActivation.xml File Expanded Step

1

<ID>

3

<IterationNames>

2

<Required>

   

Downloading and Uploading Wizard Files

To customize Cisco ANA NSA wizard metadata files, you must download the files to a local drive using the Service Modification Utility (SMU). After you complete your metadata file customization, you use the SMU to upload the files back to the gateway.

To display the SMU, from the Activation menu, choose Service Modification Utility. The Service Metadata Modification Utility window (Figure 2-20) appears.

Figure 2-20 Service Metadata Modification Utility Window

In the SMU window, wizards are divided into two groups, Shipped and Custom. These correspond to the the metadata directories on the server (Figure 2-21). The two groups allow the shipped metadata files—files provided in the Cisco ANA NSA package—to be separated from customized ones. Because customized metadata files are stored in the to_backup directory, backup protection is provided. For information about backing up customized Cisco ANA NSA files, see Backing Up and Restoring Customized Files, page 1-6.


Note Because the SMU performs semantic and syntactical checking, always use the SMU to download and upload metadata files to the server.


Figure 2-21 Service Metadata Directories

When the operator launches the Activation window, Cisco ANA NSA looks in the to_backup/MetadataDirectoryCustom directory for metadata files. If it finds any, it uses those files, not the ones in the shipped directories. The Activation window takes a combination of both shipped and custom metadata files. If an activation file with the same name is in the shipped and custom directories, Cisco ANA NSA uses the file in the custom directory.

Before you begin any customization, the SMU window displays identical names in the shipped and custom SMU directories, even though the custom directory on the server is empty. This indicates that the Activation window is using the shipped files, not customized ones. Assuming that you give customized files different names, which is a recommended practice, the file names in the SMU window show you which files are actually being used in the Activation window.

Customizing Wizard Files General Flow

The following steps provide the general flow for Cisco ANA NSA wizard metadata customization. The actual steps you follow will depend on the type of customization and files you are customizing.


Step 1 Download the metadata files:

a. In Cisco ANA NetworkVision, click Activation > Service Modification Utility.

b. In the Service Metadata Modification Utility window (Figure 2-20) navigate to the wizard you want to customize.

If this is your first customization, choose metadata files in the Shipped directories.

c. Click Download and choose a local directory.

The wizard pages file, activation file, and Service.xml file are downloaded to the selected directory.

Step 2 Using an XML or text editor (see Cisco ANA NSA Customization Tools, page 1-6), make the metadata file modifications.

Step 3 Save the customized metadata files with a new name.


Note If you modify a wizard pages or Activation file, giving it a modified name is recommended. If you change the pages or activation file names, you must modify the Service.xml file to point to the customized pages and activation files. If you do not, Services.xml will point to the shipped files. If the change is a minor display-only change, you can use the same file name. If the old wizard needs to be retained, a new ID needs to created for the pages and activation metadata, the associated file names need to be modified, and a new entry needs to be added to the Service.xml.


Step 4 Open the Service.xml file.

Step 5 In the Activation file section for the wizard you modified, enter the new pages and activation file names and IDs.

Step 6 Save the Service.xml file.


Note The Service.xml file name can never change. When you upload the customized pages and activation files, you must upload the Service.xml to point to the customized pages and activation files. If a Service.xml file is in the Custom directory, it uses that file, not the one in the Shipped directory.


Step 7 Restart Cisco ANA NetworkVision and test your customized metadata files.