TL1 Tutorial

Table Of Contents

1.0 TL1 TUTORIAL.................................................................................................... 4

1.1 Foreword........................................................................................................................ 5

1.2 Introduction .................................................................................................................... 8 1.3 TL1 Tutorial Tour ......................................................................................................... 10 1.4 Application Overview ................................................................................................... 12

2.0 TRY IT YOURSELF ........................................................................................... 16

3.0 APPLICATION DESIGN .................................................................................... 24

4.0 MODELING MANAGED RESOURCES............................................................. 27

4.1 Modeling the TL1 Managed Object.............................................................................. 29

5.0 IMPLEMENTATION........................................................................................... 32

5.1 Creating TL1 Project.................................................................................................... 34 5.2 Modeling the Switch and its Components.................................................................... 36

5.2.1 Managed Resource Modeling...............................................................................................37 5.2.2 Custom Code for Managed Object Classes .........................................................................40

5.3 Discovering the AcmeMSU devices and GNEs ........................................................... 42 5.3.1 Discovering Switch Devices..................................................................................................44 5.3.2 Custom Code for Discovery Filter.........................................................................................46

5.4 Creating Maps to Display AcmeMSU Devices............................................................. 52 5.4.1 Creating Maps.......................................................................................................................53 5.4.2 Customizing the Map Filter Code .........................................................................................56 5.4.3 Creating and Configuring other Map related files .................................................................58

5.5 Managing the Alerts of AcmeMSU Device................................................................... 61 5.5.1 Correlating Events ................................................................................................................62 5.5.2 Status Propagation ...............................................................................................................63

5.6 Fetching Device Status Periodically ............................................................................ 64 5.6.1 Status Polling for Card..........................................................................................................65 5.6.2 Status Polling for Port ...........................................................................................................67

5.7 Performance Monitoring of the AcmeMSU Device ...................................................... 69 5.7.1 Performance Management ...................................................................................................70

AdventNet Inc. 1

TL1 Tutorial

5.8 Provisioning the AcmeMSU Device ............................................................................. 72

5.8.1 Modifying the Managed Object Property ..............................................................................73 5.8.2 Creating a Cross Connection................................................................................................76 5.8.3 Configuring Provisioning Files ..............................................................................................78

5.9 Client-Server Communication...................................................................................... 81 5.9.1 Creating Client Server Communication Class ......................................................................81

5.10 Re-branding............................................................................................................... 82 5.11 Creating Menus ......................................................................................................... 84 5.12 Packaging the Project................................................................................................ 85

6.0 FAST TRACK IMPLEMENTATION ................................................................... 87

7.0 INSTALLATION AND TESTING........................................................................ 88

7.1 Installation Notes ......................................................................................................... 88 7.2 Testing the Application ................................................................................................ 90

8.0 KNOWN ISSUES ............................................................................................... 97

9.0 TROUBLE SHOOTING TIPS............................................................................. 98

10.0 DESCRIPTION OF CUSTOM CODE AND CLASS FILES ............................ 100

10.1 Description of Discovery Filter Custom Code .......................................................... 100 10.1.1 Customizing the Discovery Filter Code ............................................................................100 10.1.2 Adding Device Components - Part1 .................................................................................102 10.1.3 Adding Device Components - Part2 .................................................................................106

10.2 Description of Map related files ............................................................................... 108 10.2.1 Description of AcmeMSU Device Map Layout Class........................................................108 10.2.2 Description of AcmeMSU Device Map Symbol Renderer Class ......................................111 10.2.3 Description of AcmeMSU Map Applet Extension Class with Complete Code..................112

10.3 Description of Fault Management related files ........................................................ 113 10.3.1 Description of MSU Event Correlation Filter Class...........................................................113 10.3.2 Description of AcmeMSU Alarm Propagation Filter Class ...............................................118

10.4 Description of Status Polling Custom Code............................................................. 120 10.4.1 Description of Custom Code for Status Polling of Card....................................................120 10.4.2 Description of Custom Code for Status Polling of Port.....................................................122

10.5 Description of Performance Management Configuration......................................... 125 10.6 Description of Provisioning Files.............................................................................. 127

10.6.1 Description of ChangeCardType Provisioning Template..................................................127 10.6.2 Description of AcmeCrossConnect Provisioning Template..............................................129 10.6.3 Description of Post Provisioning Filter Class....................................................................131

10.7 Description of Client Server Communication Code ................................................. 133

AdventNet Inc. 2

TL1 Tutorial

11.0 APPENDIX..................................................................................................... 134

11.1 TL1 Command Set used in the Application ............................................................. 134

11.2 TL1 Basics ............................................................................................................... 138 11.2.1 Message Structure............................................................................................................139 11.2.2 Input Message ..................................................................................................................140 11.2.3 Output Response Message ..............................................................................................142 11.2.4 Acknowledgement Message.............................................................................................144 11.2.5 Autonomous Message ......................................................................................................145

12.0 OTHER TUTORIALS ..................................................................................... 147

AdventNet Inc. 3

TL1 Tutorial

TL1 Tutorial

Managing a TL1 Device AdventNet Web NMS Tutorial Version 1.0 A guide to developers on how to build an application to manage a TL1 device. Copyright © 1996-2002 AdventNet, Inc. 5645 Gibraltar Drive Pleasanton, CA 95014 http://www.adventnet.cominfo@adventnet.com

AdventNet Inc. 4

TL1 Tutorial

1.1 Foreword AdventNet Web NMS aims at providing real world network management solutions to telecom and enterprise markets. It meets the demand of the market for advanced network management features. It fulfills the need of the market for shortest possible deployment time. TL1 Tutorial will demonstrate how the above market expectations are met by AdventNet Web NMS.

• Real World TL1 Element Management Solutions • Why AdventNet Web NMS • Application Life Cycle

Real World TL1 Element Management Solutions

Real world TL1 Element management applications that can be made available on AdventNet Web NMS, categorized by specific domains are

Core Network : Optical and IP/ATM core. Metro Network : SONET/DWDM/Ethernet metro equipment. Edge and Access Network

: Cable, DSL, Optical, and Wireless-based Broadband access technologies, with IP, ATM, and SONET protocols.

The list of Web NMS applications goes on. For complete information on TL1 Protocol solutions, visit the web site TL1 GURU.com. Why AdventNet Web NMS

AdventNet Web NMS fulfills your specific network management needs. It comes with the most sought after features in the market. They are

• Massive scalability • High availability • Customization

o Modeling managed systems o Extending management services o Supporting variety of management protocols o Various deployment options

It can be customized and extended to suit your needs. The extensibility makes the design of the application more organized. The customization addresses the specific needs of the application to mange your custom equipment. AdventNet Web NMS comes bundled with a developer suite with rich tools, called AdventNet Web NMS Studio. This tool reduces the development life cycle time drastically. This in turn brings host of benefits:

• The time taken to deploy the application is lesser compared to the conventional development and deployment techniques.

AdventNet Inc. 5

TL1 Tutorial

• The human resources required are cut to a fraction of what is required for conventional techniques.

• The tool supports user from the level of novice to professional. The tool contains UI-based Wizards to accomplish all the simple tasks if you are a novice user and makes room for custom code if you are a professional to handle advanced tasks.

• The required skill level of the user is also brought down. For example, you do not require Java knowledge to use the tool and only network management and your element domain knowledge will suffice.

All these benefits put together will make AdventNet Web NMS a wise choice for your network management solution. Application Life Cycle

AdventNet Web NMS offers a comprehensive development environment for building your management solution. This section explains how the complete product life cycle needs of your management solution are realizable using AdventNet Web NMS. They are captured in five easy steps that you can follow to build your management solution, as below: Step 1: Modeling the managed elements Step 2: Customizing managed object services Step 3: Re-branding the management solution Step 4: Packaging Step 5: Deployment and Testing The following diagram gives an overview of the experience of building management solutions with the AdventNet Web NMS.

AdventNet Inc. 6

TL1 Tutorial

Step 1: Modeling the Managed Elements

Each managed system comprises many inter-related elements that need to be individually managed. You start with modeling your elements, so that you can capture the data, operations and state of the elements, and the relationships between the elements. The Web NMS provides a comprehensive, simple and easy to learn information model, using which the various elements of the managed system can be modelled. The basic element of the Web NMS information model is the ManagedObject. The Web NMS also has models for various common IP network components such as Network, Node, SNMP Node, TL1 Node, etc. These form the core objects of the Web NMS information model. You have to extend any of the core objects of Web NMS to model your managed element. The core objects can be extended, by adding attributes, operations, and state to those objects (modeling the data, operations, and state of your element in addition to capturing the relationship).

This task can easily be accomplished by using the Managed Resources of AdventNet Web NMS Studio. It helps you walk through the steps in terms of the object that needs to be extended, the new attributes of your element, etc. It then generates MO classes, relational classes, and database schema files for your managed element.

Step 2: Customizing Managed Object Services

AdventNet Web NMS offers a number of management services to the managed objects. The southbound services that populate the database with information from the elements such as data collection, status polling, etc. are classified as the mediation services. The services that enable the user to perform network planning, error management, and service deployment tasks are classified as the management services. Management services include event correlation, element configuration, service provisioning, access control, etc. Using the module management services available as part of the Web NMS framework, you could also build other management application modules.

Step 3: Re-branding the Management Solution

You can re-brand the application to display the name of your company, the name of your product, and your logos. The I18N tool, bundled in AdventNet Web NMS Studio, helps you re-brand your application by replacing references to AdventNet and Web NMS. The logos, images, and icons can be changed by modifying configuration files.

Step 4: Packaging

You can package your application resources alone as a NAR (NMS Archive file) that can be installed over the AdventNet Web NMS.

Step 5: Deployment and Testing

Before testing your management solution, make sure all the third-party packages are installed correctly and you have the required privileges to use them for your testing. Once you start your application, look at the Web NMS server log files to make sure all the services are started successfully and are running.

Having deployed your application at a customer's site, you will be required to support the product and provide upgrades as part of support. AdventNet Web NMS Studio available in AdventNet Web NMS makes it easy to handle upgrades.

AdventNet Inc. 7

TL1 Tutorial

1.2 Introduction The purpose of this tutorial is to guide you through designing an EMS for TL1-managed devices and provide illustrative examples to help you understand the choices to be made during development. This tutorial will elaborate the various features in AdventNet Web NMS to manage TL1 Devices and describes how AdventNet Web NMS Studio can be used to simplify the development of an EMS. The Tutorial

Consider a real life scenario. Suppose you want to manage Switches, which are TL1-protocol devices. Then this tutorial will help you to build an EMS (Element Management System) to manage the Switches by using AdventNet Web NMS. The tutorial will walk through a series of steps, which will help you understand how a unique EMS solution can be built using AdventNet Web NMS Studio to suit your needs. Use of AdventNet Web NMS Studio will make the development of the application virtually very little or zero coding. This makes the development faster. This tutorial helps you to build only a sample application. In which, it adopts a generic TL1-managed device (i.e., Acme MSU Switch) as an example. This limited scope example will serve only to illustrate what can be built on AdventNet Web NMS and it is only a subset of the custom capabilities of AdventNet Web NMS. However, for many EMS applications of specific needs, this basic example can be extended. This topic covers the following details of the tutorial:

• The Intended User • Prerequisites • Related Information • Printed Version • Tutorial Conventions • At the end of the Tutorial

The Intended User

This tutorial is intended for those, who are interested in developing an Element Management System for TL1 based Devices using the AdventNet Web NMS. Prerequisites

To develop this tutorial application, you will need a good knowledge of Element Management System and TL1 based Devices. Knowledge of Java programming, SQL, and relational database concepts will be an added advantage, but it is not essential. Related Information

This tutorial provides concise information about AdventNet Web NMS Studio and AdventNet Web NMS. For detailed information about these, refer to the Web sites listed below:

1. AdventNet Web NMS Studio documentation - from the following URL: <Web NMS Home>\StudioTools\Studio\help\index.html

2. AdventNet Web NMS documentation - from the following URL:http://www.adventnet.com/products/webnms/help.html

AdventNet Inc. 8

TL1 Tutorial

Printed Version

To print this tutorial, follow these steps:

1. Ensure that Adobe Acrobat Reader is installed in your system. 2. Download the PDF version of this document from the following URL:

http://download.adventnet.com/products/webnms/tl1_tutorial.pdf

3. Click the printer icon in Adobe Acrobat Reader. Tutorial Conventions

The following table lists the typographic conventions followed in this tutorial:

Font Style Uses Arial Bold File name Arial Italic Directory Arial Bold Italic Methods / Interfaces / Classes Courier New Code snippet Courier New Bold Italic Highlighting important code snippets

At the end of the Tutorial

From this tutorial you will learn how to

• Build an EMS for managing TL1 devices by customizing AdventNet Web NMS with the help of AdventNet Web NMS Studio.

• Model Objects. • Achieve Fault, Configuration, Performance, and Security management and Discovery of

network elements.

AdventNet Inc. 9

TL1 Tutorial

1.3 TL1 Tutorial Tour Welcome to the TL1 Tutorial Tour This tutorial is in three stages. Stage 1 At this stage, you are provided the ready-built tutorial application which can be deployed right away and experienced.

• Try it Yourself - This topic lists the steps to be followed to experience the application. • Application Design - This topic gives you an overview of the Application Design. It elucidates

the various stages involved in building the application. Stage 2 This stage guides you step by step on how to build the application yourself, including the relevant help on AdventNet Web NMS Studio. Refer to the Implementation section for this stage.

AdventNet Inc. 10

TL1 Tutorial

Stage 3 At this stage, you are given the Studio Project of this application. You can compile this project, package and deploy it directly if you are unable to build the project successfully. Further, you can open this project in AdventNet Web NMS Studio and modify it as per your requirement. You can compile, package and deploy it to see the effect of your modifications. Refer to the Fast Track Implementation topic for Stage Three of this tutorial. Hope you will enjoy this tour and experience easy and quick Application development.

Fig: Tutorial Tour

AdventNet Inc. 11

TL1 Tutorial

1.4 Application Overview In this section, an overview of the Tutorial Application is provided. This application has a simple TL1 command set which is designed to be in sync with many of the commercial TL1 Devices available in the market. Over and above the normal TL1 device management, this application highlights the Terminal Server feature of the TL1 devices. The tutorial application provides information on how to develop an EMS to manage TL1 devices. The tutorial application is built exploring the various modules of AdventNet Web NMS.

• Application Specification • Description of System Used in the Application • Implementation in a Nutshell

Application Specification

Name of the Application : TL1_Tutorial Version of Web NMS : AdventNet Web NMS Release 4 Compatibility with other Versions

: Not compatible with previous versions of Web NMS

Tools used and their Versions

: AdventNet Web NMS Studio

Platform-specific requirements

: No special requirements

Description of System Used in the Application

This application uses an imaginary TL1 device called AcmeMSU and Terminal Server of TL1 devices. The AcmeMSU device is a simple switching device interconnecting various external elements. The switching device has a shelf with 11 slots numbered (1-11). Each slot from (1-11) has a card associated with it. Each card will be having only one port. The AcmeMSU holds three types of cards. They are

1. CPU 2. ST1 DSX 3. ST1 CSU

The AcmeMSU holds one CPU card, seven ST1 DSX cards, and three ST1 CSU cards. Each ST1 card has one port and the port is used to connect the devices, which require the service of the AcmeMSU. Terminal Server of TL1 devices, i.e., Gateway Network Element (GNE) provides gateway to IP Addressless TL1 devices through Target IDentifier (TID). This application has been provided with a TL1 Agent Simulator created for demonstration. This simulates a generic network device (AcmeMSU) with a simple TL1 message set. This also supports the Terminal Server of TL1 devices.

AdventNet Inc. 12

TL1 Tutorial

AcmeMSU agent is configured to show each card with only one port (led). The status of the card is shown separately (because in most of the TL1 Devices each and every card used will be intelligent cards and these cards do have various LEDs to show various alarm/status changes). Implementation in a Nutshell

The tutorial application covers various aspects of network management. Various modules of AdventNet Web NMS are used to achieve the network management objectives as listed below:

• Modeling the AcmeMSU Device and Component Objects • Discovering AcmeMSU Devices • Customizing Maps to display the AcmeMSU Devices • Managing Alerts of AcmeMSU Device and Its Components • Provisioning of the AcmeMSU Device • Monitoring the performance of the AcmeMSU Device • Re-branding AdventNet Web NMS as Your AcmeMSU Manager

Modeling the Switch and Component Objects

In AdventNet Web NMS, the managed device data are stored in the database for persistency. For storing the managed devices' data into a database, you need to model the managed device and its components. The tutorial explains how the Acme MSU discovered as an AcmeMSUNode is modeled and it further drills down and sends a few commands to the device to find the list of active cards present in the device. In order to simulate a real time switch, the related components objects such as shelves, slots, cards, and ports are modeled. The Object Modeling topic illustrates how the existing AdventNet Web NMS Managed Object model is extended to emulate a real TL1 Switch device and its sub-components. This tutorial supports MySQL and Oracle databases only. However, the support can be extended to other databases such as MSSQL, Sybase, Solid, and Timesten using AdventNet Web NMS Studio. Discovering Switch Devices

The Discovery process of AdventNet Web NMS discovers all the elements available in the managed network. The tutorial explains how the Discovery process is customized to discover generic TL1 and advanced GNE Nodes. The discovered nodes are modeled as explained above and stored in the topology database for effective management. The Discovery topic illustrates how to customize discovery and store the discovered information in the Topology database. Creating Maps to Display the Switches

AdventNet Web NMS provides default maps with default layouts and symbols to display of various networks and element groups. The tutorial explains how the custom maps are created from the elements of the topology database and how to customize the display and configuration of network maps. Also, if a Gateway Network Element (GNE) is detected, then a TL1 Topo Map will be created. This map displays the GNE. This map can be drilled down further to the Logical objects (Ports)

AdventNet Inc. 13

TL1 Tutorial

to which the GNE will be listening to various TL1 devices and further to the TL1 devices (which are accessed through the GNE). A separate map will be created for each discovered switch and the various components of the switch are shown in the chassis view. The following diagram shows the various components of an individual switch.

Managing Alerts of Switch and Its Components

AdventNet Web NMS implements Fault Management to identify failures in the managed network elements. The tutorial explains how to handle alarms effectively and to generate meaningful outputs. In this application, you will be dealing with alarms which come in the form of Autonomous message from the device. This message from the device is parsed to get the component and its health.

• The Correlating Events and failures topics explains how to minimize the clutter due to multiple related failures and alarms.

• The Alarm propagation topic elaborates how to notify failure events to affected components.

• The Status polling topic explains how to carryout surveillance of Switch and components periodically.

Provisioning the Switch

AdventNet Web NMS enables you to provision the network devices, where you can schedule a task to get executed at any convenient time. If the configuration of the device through Provisioning does not succeed, then the previous settings of the device can be restored. All the Provisioning information (tasks) are cached in an XML file which can be reused. The tutorial illustrates how Provisioning can be implemented to provision the modeled Switch components.

AdventNet Inc. 14

TL1 Tutorial

Monitoring the Performance of the Switch

AdventNet Web NMS monitors the performance of the Switch with TL1 protocol. The tutorial implements Performance management using the Performance Service of Web NMS. Re-branding AdventNet Web NMS as your EMS

The tutorial re-brands AdventNet Web NMS into AcmeMSU Manager. The logo, images, etc. can be replaced with your own using Rebranding tool. You have the i18N tool for internationalization of various UI reference of AdventNet and Web NMS. With these, the EMS developed can easily be re-branded.

AdventNet Inc. 15

TL1 Tutorial

2.0 Try It Yourself In this section, the steps to deploy the ready built application is provided. This would help you run the application by yourself and view the results. The steps involved are

• Before You Begin • Get the Ready Built Application • Deploy the Ready Built Application in AdventNet Web NMS • Run the Application • View the Result

Before You Begin

• Download a copy of AdventNet Web NMS 4. • For trying this tutorial, you have to take a Trial User License from AdventNet, Inc. • Get it installed in your machine.

For pertinent information, refer to the following document resources in the Installation Guide of AdventNet Web NMS 4

• System Requirements • Startup Options

Get the Ready Built Application

The working example comes bundled with AdventNet Web NMS as a NAR file. Alternatively, you can download the latest version of the tutorial from the AdventNet Web site and use the NAR in it.

a. Use the bundled application

OR

b. Download the latest version from the Web site at the following URL:

http://download.adventnet.com/products/webnms/tutorials/tl1_tutorial.zip

If you are using the downloaded tutorial from the Web site, then extract the tutorial under <Web NMS HOME> directory. Select the NAR file mentioned below from the <Web NMS HOME>/tutorials/tl1_tutorial/ems directory.

TL1_Tutorial1.0.nar

Caution: If a NAR is already installed, uninstall that NAR, before you install a new NAR.

Deploy the Ready Built Application in AdventNet Web NMS

• Using the following instructions, deploy the TL1_Tutorial1.0.nar file.

AdventNet Inc. 16

TL1 Tutorial

To install the tutorial application,

• Stop the Web NMS Server if it is running. • Run the DeploymentWizard.bat/.sh file under <Web NMS HOME>/bin directory. • Select the NarInstall/Uninstall tab. • Select Install button in the screen. • Click Browse button in the NAR INSTALLER pop-up screen. • Select the TL1_Tutorial1.0.nar available in the <Web NMS HOME>/tutorials/tl1_tutorial/ems

directory from the File Chooser pop-up screen and click the Select button. • Click OK button in the NAR INSTALLER pop-up screen. • On clicking OK button, NmsPwsNarInstaller screen will pop up. • In that, Select the Application Database (in which you want to run the tutorial) listed from the

combo box. • Click Next button. • In this screen, click Install button. • Now the installation will start and the status will be shown in the progress bar. When the

installation is complete, the Close button will be enabled. • Click Close button. You will see TL1_Tutorial1.0.nar entry listed in the NarInstall/Uninstall

tab. • Now the installation is complete. • Click Exit button to quit the Deployment Wizard. The Confirm.. dialog box will pop-up. • Click Yes button in the dialog box. This will quit the Deployment Wizard.

Start the TL1 Agent

To simulate a single TL1 Device and/or simulate multiple TL1 Devices in one and/or multiple ports refer to Setting Up Environment for Testing section of Testing the Application topic.

Note: You must configure your machine IP address in tl1seed.file located in <Web NMS Home>/conf directory for discovery of TL1 Elements.

• Reinitialize Web NMS using reinitialize_nms.bat/.sh. Reinitialize Web NMS Database option

dialog pops up. Select Yes option in the option dialog for reinitializing Web NMS.

Caution: This tutorial will function only if Web NMS is reinitialized. Therefore, after installing the tutorial, reinitialize Web NMS. Ensure you use separate Web NMS installation for tutorial application development and installation. Do not experiment on Web NMS deployed in real world.

Run the Application

• Start the Web NMS Launcher, by invoking WebNMSLauncher.bat/.sh file in the <Web NMS HOME> directory.

• Click Start NMS Server icon in the Web NMS Launcher. View the Result

Connect a Browser or Application Client to the TL1 Element Manager Server in port 9090. Log in as user root and password public. In the left side frame, you will see the map tree. In that you can see the ACME > EMS-Panels > Network Maps > Switches node. Under this node you can see the five switches discovered.

AdventNet Inc. 17

TL1 Tutorial

Displaying Switches in a Map The Switches map will be the default map when you open the client. The following image is a snapshot taken from the application, which shows the switches map, where all the switches are laid out in the map.

AdventNet Inc. 18

TL1 Tutorial

Device Menus On double-clicking the individual Switch nodes, you can see the Chassis view of the individual switches. Right-click the device to see the device specific menu items. It has TL1-Node and Acme-MSU(N) menu items with more submenus.

AdventNet Inc. 19

TL1 Tutorial

Chassis View of the Switch Device The Chassis view of Switch device shows the various components of an individual switch. The screen shot is given below. The map shows a shelf with slots. Each slot has a card associated with it. Select and right-click a port to see menu specific to it. Right-click a card to see its menu..

AdventNet Inc. 20

TL1 Tutorial

Alerts from the Switch Device and Sub-components and Its Propagation The following diagram depicts how events are propagated from a child node (Port) to the parent container (Card) and how they are correlated to generate more meaningful alarms.

AdventNet Inc. 21

TL1 Tutorial

Events View

AdventNet Inc. 22

TL1 Tutorial

Performance View

AdventNet Inc. 23

TL1 Tutorial

3.0 Application Design Aim

To come up with the design on customizing the AdventNet Web NMS platform features in order to provide various functions to the EMS, as specified in the requirements. The primary design consideration in this tutorial application is to stick on to a simple command set. For this purpose, the TL1 simulator was developed which contains a simple command set. This models a generic Tl1 device (AcmeMSU). The Acme TL1 commands and responses used in this tutorial application are appended to this tutorial. EMS Management Requirements

• Modeling the Switch device as Managed Resource • Discovering the Switch devices in the network • Representing the Switch components in the Map • Managing the Events and Alerts of Switch and its components • Provisioning the Switch Device • Re-branding AdventNet Web NMS as your EMS

Managed Resource Modeling

Objective Modeling a device enables you to represent the various attributes and the behaviour of the corresponding physical device and its components in a convenient way so as to reflect their current state at any point of time. The EMS stores these persistent data in the database. Modeling the Managed Object topic elaborately deals with various aspects to be considered for designing the Managed object. Tasks Define the resources to be managed by the EMS. The properties of the Device and its Components that will be used for modeling the resources are given below: AcmeMSUNode location, contact AcmeMSUShelf Serialno AcmeMSUSlot state. slotno, slotName AcmeMSUCard CRDREV, prodNo, ST1Type, CRDSN, MFDAT, deviceName, priority,

cardName AcmeMSUPort deviceName, portName, portNo Channel Connection, channelNumber CrossConnection Destination, bandWidth, source, deviceName The Role of Studio Using the Resource Factory of the Studio, all the above resources can be modeled easily.

AdventNet Inc. 24

TL1 Tutorial

Discovering AcmeMSU Devices

Objective To automatically discover and add the AcmeMSU devices and their components into the topology database of Web NMS. This will necessitate identifying the component hierarchy of the AcmeMSU devices. Tasks

• Create a Discovery Filter defining the containment hierarchy of the device and its components.

The Role of Studio The Discovery Filter Wizard will help you define the discovery filter. During discovery, Web NMS will discover the device and its components and store them in the database according to the containment hierarchy that has been defined in the discovery filter.

Representing the AcmeMSU Device and its components in the Map

Objective To graphically represent the AcmeMSU Devices and its components, illustrating the Containment hierarchy, in the map view of Web NMS Client. Tasks

• Create a custom map for the AcmeMSU Device and its components • Create a custom map layout class to customize the format in which the Map

Containers are arranged in the map view of Web NMS Client. • Create a custom map renderer class to customize the shape, style and color of the

Map Containers, which gives the flexibility of depicting the various components in the map view of Web NMS Client.

The Role of Studio Using the Map Filter Wizard of the Studio, all the above tasks can be completed.

Managing the Events and Alerts of AcmeMSU and its components

Objective To monitor and manage the failures in the system effectively including, polling the AcmeMSU Device and its components periodically for their status and thereby take preventive action where necessary. Tasks

• Convert the failure notifications (Traps) into meaningful Events. • Write Custom code for Status Polling in the Managed Object classes. This will poll the

necessary devices for their current state on demand. The Role of Studio Using the Trap Filter Wizard of the Studio, it is easy to create a Trap Filter that filters the traps and converts them into meaningful Events which can be managed.

AdventNet Inc. 25

TL1 Tutorial

Provisioning the AcmeMSU Device

Objective The TL1 Application should be capable of controlling and configuring the device. It should be able to switch the status of the card from active state to inactive state. Tasks

• Identify the Configuration commands to activate and deactivate the AcmeMSU Card. The Role of Studio In the Studio, two templates are created using the XML Editor can be used to configure tasks and set Device lists where the tasks have to be executed. Source is generated for executing the task. When the project is installed in Web NMS, there will be an option to execute the defined tasks.

Re-branding AdventNet Web NMS as your AcmeMSU Manager

Objective The EMS has to be renamed according to your requirements. All the relevant images and icons will have be changed to reflect its new name (For example AcmeMSU Manager). Tasks

• Replace the existing AdventNet & Web NMS images and logo to Acme. Internationalize the text and buttons that appear in the Client of the EMS.

The Role of Studio Using the I18N Editor, the EnglishToNative properties file will be changed to internationalize the text that appears in the Client. The images and logo of AdventNet will also be replaced with that of Acme using this Editor

AdventNet Inc. 26

TL1 Tutorial

4.0 Modeling Managed Resources

• What Are the Different Methods Available for Designing Managed Resources? • ManagedObject Parent-Child Containment Relationship • Naming Conventions Used in Modeling the Managed Resources

What Are the Different Methods Available for Designing Managed Resources?

We have two choices for our design of managed elements.

1. Use the dynamic properties feature of Web NMS ManagedObjects 2. Design ManagedObject subclasses

The former is a quick solution requiring less up-front design effort. However, we will choose to do a cleaner design by modeling our objects as ManagedObject subclasses. This will enable us to better serve our application needs, as well as provide a better design. This approach also results in a better table structure for storing our objects in an RDBMS. ManagedObject Parent-Child Containment Relationship

In our EMS example model, we will be applying Parent-Child Containment Relationship. In this Relationship, the Device is called Parent. The Device will hold sub-components called Children. The sub-components will be Parents and the sub-components will hold sub-sub-components called Children. We have to apply the containment relationship modeled to all the device components. That is, ports are contained within a card, cards within a slot, slots within a shelf and the shelf within the node. For mapping this relationship, we use the parent-children modeling feature available in the ManagedObject class. This can be made available to our component classes just by implementing the ContainerInterface in the parent component's class and setting/storing the parent object name/key in the child component object using setParentKey() method of the ManagedObject class. This enables us to fetch all the children of a parent component by using the getChildrenKeys() method of the ManagedObject class, once the parent component and its children are added to the database. Also we need to ensure that the parent component is added to the database before its children. Another benefit of this ManagedObject property, namely ParentKey is it allows for quickly looping up the component object hierarchy as required when propagating alarms. Naming Conventions Used in Modeling the Managed Resources

Although a naming convention is not essential, it provides some benefits. It supports the requirement of providing unique keys for all managed objects. It also allows us to easily identify some useful object properties, without having to explicitly store these properties in the object. We will use a naming convention for these objects that will make it easy to tell which object we are dealing with. This will also help with filtering, etc. if we wish to use them. The naming convention will be of the form:

Shelf : <nodename>_Shelf1 Slots : <nodename>_Shelf1_<slotname> Cards : <nodename>_Shelf1_<slotname>_<cardname> Ports : <nodename>_Shelf1_<slotname>_<cardname>-<portNo>

AdventNet Inc. 27

TL1 Tutorial

where, <nodename> will be the name of the TL1Device, <slotname> is the name of the slot as obtained from RTRV-INVENTORY command, <cardname> is the name of the card as obtained from RTRV-EQPT command and <portNo> is the number of the port in the card.

Note: In this example, although we have used a detailed object naming convention, we have not made use of object names for accessing such properties for better design considerations.

AdventNet Inc. 28

TL1 Tutorial

4.1 Modeling the TL1 Managed Object In the TL1 application, you will be modeling a switch with associated shelves, slots, cards, and ports. The following relationships are assumed between the ManagedObjects:

• AcmeMSUNode : This represents a manageable switch that can be managed via TL1. That is, Web NMS finds it as an TL1Node in the network or is manually added by an operator.

• AcmeMSUShelf : This represents the shelf that acts as the container for slot, cards, and ports.

• AcmeMSUSlot : Each switch consists of 11 slots, which are numbered 1-11.

• AcmeMSUCard : Each slot may contain a card, which can be of different types. Inthis simple example we will work with only one card object, with a type field to specify the card type.

• AcmeMSUPort : Each card can have multiple ports. For the example, only one port is assumed per card.

• Channel : Each port supports 24 Channels, for data transaction.

• CrossConnection : This represents the connection details of a Channel to an external element.

You will model these components in the Web NMS topology database and use these definitions to build AcmeMSU Manager functionality into our application.

• Class Diagram of Managed Resources of AcmeMSU Application • Design of Managed Elements

Class Diagram of Managed Resources of AcmeMSU Application

AdventNet Inc. 29

TL1 Tutorial

Design of Managed Elements

For each of the components of the TL1 device, you will create a ManagedObject subclass. The following list captures the properties you will be providing in each component you model, i.e., the ManagedObject subclasses.

• The AcmeMSUNode object will extend a TL1Node object instead of ManagedObject directly. This is because our example assumes that our node should be discovered as a TL1Node by Web NMS.

• Location (location)

: Denotes the location of the TL1 Network Element.

• Contact (contact)

: The Contact person to be approached in case of failure of this Equipment. (Normally E-Mail ID)

• You will create a ManagedObject subclass AcmeMSUShelf to model the shelf. You will

provide the following additional properties in the slot object, in addition to what is available in a ManagedObject class:

• Serial number (serialNo) : Denotes the serial number of the shelf.

• You will create a ManagedObject subclass AcmeMSUSlot to model the slot. You will provide

the following additional properties in the slot object, in addition to what is available in a ManagedObject class:

• Slot number

(slotNo) : The slot number is the identification of position on the shelf.

• State (state) : An indication of the state of the slot, whether the slot is empty or the card type it contains.

• Slot Name (slotName)

: The name of the slot as obtained from the agent.

• The Card object AcmeMSUCard is modeled using a ManagedObject subclass. You will

provide the following additional properties in the card object, in addition to what is available in a ManagedObject class: • Device Name

(deviceName) : The name of the device in which this card is present.

• CRDSN : Denotes the serial number of the cards as obtained from RTRV-INVENTORY.

• MFDAT : Denotes the manufacturing date of this card as obtained from RTRV-INVENTORY .

• PRODNO (prodNo) : Denotes the production number of the card as obtained from RTRV-INVENTORY.

• CRDREV : Denotes the card revision index as obtained from RTRV-INVENTORY.

• Card Name (cardName)

: Name of the card as obtained from the agent.

• ST1 Type (ST1Type) : Denotes the ST1 Type of the Card.

• Priority (priority) : Denotes the Priority of the Card.

AdventNet Inc. 30

TL1 Tutorial

• The Port object AcmeMSUPort is also directly subclassed from ManagedObject. You will provide the following additional properties in the port object, in addition to what is available in a ManagedObject class.

• Port number

(portNumber) : The port number is the identification of position on the card.

• Device Name (deviceName)

: The name of the device in which this port is present. This is just for using during the status polling.

• Port Name (portName)

: The port name as given by the agent.

• The Channel object is also directly subclassed from ManagedObject. You will provide the

following additional properties in the port object, in addition to what is available in a ManagedObject class.

• Connection (connection) : Denotes whether a connection exists in this channel

or not.

• Channel number (channelNo)

: Denotes the serial number of the Channel in the Port.

• The Cross Connection object is also directly subclassed from ManagedObject. You will

provide the following additional properties in the port object, in addition to what is available in a ManagedObject class.

• Source (source) : Denotes the Network Element or its subcomponent from

where the Cross connection is originating.

• Destination (destination)

: Denotes the Network Element or its subcomponent to where the Cross connection is terminating.

• Device Name (deviceName)

: The name of the device in which this port is present.

• Bandwidth (bandWidth)

: Denotes the bandwidth used by this Cross connection.

AdventNet Inc. 31

TL1 Tutorial

5.0 Implementation This tutorial application has been created using AdventNet Web NMS Studio. This comes bundled with AdventNet Web NMS. Using AdventNet Web NMS Studio

In the AdventNet Web NMS Studio, you have to create a separate project for this application. When the project is complete, compile it and package it into a NAR file. For deploying the application in the AdventNet Web NMS, you will have to deploy the NAR into the AdventNet Web NMS using the Deployment Wizard tool. Various features available in the Studio allow you in creating the Application. However, you need to write certain amount of custom code in order to suit the need of the tutorial application. You need to add certain files as other files in the Studio project, which are specific to the exclusive implementation of this tutorial application.

AdventNet Inc. 32

TL1 Tutorial

Implementation Overview

To start with, you will have to create a new Studio project. In the Project, build the application using the following Service Wizards:

Model the Managed Resource Model your AcmeMSU TL1 devices and their components into Managed Resources of AdventNet Web NMS Topology database. You will be filling up the Managed Resource's Name, Parent Resource, and its attributes in the Managed Resource wizard. In the end, you will get the Managed Resource's class, and its Relational class. Build Discovery-related Files Using Discovery Service Create a Discovery filter to discover the AcmeMSU objects you have modeled in the previous task. Create the filter using the Wizard. Select the Shallow Discovery. Declare the variables. Prepare the Criteria Table using Add/Modify Criteria Editor. View the summary. In the end, you will get the discovery filter. Add the Custom code specific to this application. Build Maps, Layouts, and Other Related Files Using Maps Service and Chassis Wizard Create a Map filter to display the discovered AcmeMSU devices. Modify mapIcon.data file to invoke a Map specific to a particular Icon. Modify maps.conf file to add Custom Map. Create a Map Symbol Renderer class to paint the Map as per your requirement. Create a Map-based Chassis and other related Maps for the AcmeMSU device by extending the MAP API. Build Fault Management Related Files Using Fault Service Create an Event filter to process the events. Create a propagation filter to propagate the status of the Child nodes to the Parent node. Configure the propagation filter. Create an Event filter to group the alerts to one aggregated Alert. Add custom code in the Managed Object classes (Port and Card) to get the status of the discovered devices. Configure Performance Parameters to be Monitored Configure the Performance parameters of the AcmeMSU Device to be monitored in the Polling.conf file. Rest of the functions are handled effectively by Web NMS Performance Management module. Build Provisioning Related Templates, Menus and Filters Create Provisioning related Templates, Associate the templates with the Menus to get it invoked from the Client, and create Post-Provisioning Filter to handle the other related activities.

Re-brand the Application Using the Re-branding and i18N Editor Tools Change the splash image, logo, and frame icons etc. in the Re-branding tool and Company Name, Product, and Version in the i18N Editor tool.

AdventNet Inc. 33

TL1 Tutorial

5.1 Creating TL1 Project The first step in building our application using the AdventNet Web NMS Studio is to create a Project. A Project created in Web NMS Studio copies the necessary files from the reference Web NMS to the workspace where the project will be stored. Starting Web NMS Studio

To start the Web NMS Studio Invoke the Web NMS Launcher by running the script WebNMSLauncher.sh/bat present in <Web NMS Home> directory. Double-click on the sub-Web NMS Launcher icon Web NMS IDE and then double click on the Studio icon. Alternatively, you can start Web NMS Studio by running the script startWebNMSStudio.sh/bat present in <Web NMS Home>/StudioTools/Studio/bin directory. For details of Creating Project of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Instructions

Follow the steps given below to create the project.

Step 1: Invoke the Project Wizard Select File > New Project menu item to invoke the Project Wizard. Step 2: Add Project Details Provide the following details about the TL1 EMS Project. Project Name - TL1_User Package Name - com.adventnet.nms.tutorials.tl1Application Name - TL1_User Version - 1.0 Click Next to proceed. Step 3: Select Device Details Select the Protocol as TL1. Provide the following details about the Device. Device Type - AcmeMSUNode Click Next to proceed. Step 4: Select Web NMS Services Details Select the Services to be customized in your application. All Services are selected by default.

AdventNet Inc. 34

TL1 Tutorial

For the EMS application, select only the following Services:

• MANAGEDRESOURCE • DISCOVERY • MAP • FAULT • PROVISIONING • PERFORMANCE • SECURITY • SERVER_CONFIGURATION • REBRANDING

Out of these services, MANAGEDRESOURCE, SECURITY, and REBRANDING services are selected by default. You cannot uncheck the boxes. Click Next to proceed. Step 5: Select Database Details Select the required Databases that are listed. The Databases that are listed are

• MySQL • MSSQL • Oracle • Solid • Sybase • Timesten

Select MySQL and Oracle. Click Next to proceed. Step 6: Enter User Details Select Single User option by selecting the radio button. The User options are

• Single User • Multiple Users

Selecting Single User option will fill all the selected services rows with User Name Admin. Click Next to proceed. Step 7: Preview the Project Summary You can view the TL1 Project details in the Project Summary screen. Click Finish to create the Project Workspace.

Result

The Workspace for the Project is now created. After the Project is created the Resource Factory starts. Using the Resource factory, you will see how to model the Switch Device and its components.

AdventNet Inc. 35

TL1 Tutorial

5.2 Modeling the Switch and its Components To manage a physical device and its components, you need to model them as database objects. The status and behaviour of the physical device and sub components are modeled as attributes of the objects. By controlling/monitoring the attributes of the objects, the physical device can be managed by the TL1 Element Management Application. By storing the details of the Modeled Resource in the database, the data is made persistent and this helps the Element Management. You are converting the device, its components, status, and behaviour into a network management application manageable form. This is achieved by modeling them as Managed Resources. The following table lists the device/components, which are required to be modeled as Managed Resources, the core Web NMS Resources which are extended in order to these Resources, and the Properties which are mapped for the status/behaviour of the physical device/sub-component.

Managed Resource

Properties to be managed

Core Web NMS Resource

AcmeMSUNode location, contact com.adventnet.nms.topodb.tl1.TL1Node AcmeMSUShelf serialno AcmeMSUSlot state, slotno, slotName AcmeMSUCard CRDREV, prodNo,

ST1Type, CRDSN, MFDAT, deviceName, priority, cardName

AcmeMSUPort deviceName, portName, portNo

Channel connection, channelNumber

CrossConnection destination, bandWidth, source, deviceName

com.adventnet.nms.topodb.ManagedObject

This chapter explains the procedure to model the Managed Resources, using AdventNet Web NMS Studio. The topics in this chapter cover the following procedures:

• Managed Resource Modeling for AcmeMSU Management System. • Writing convenience methods by adding Custom code to Managed Resource's source.

AdventNet Inc. 36

TL1 Tutorial

5.2.1 Managed Resource Modeling Aim The AcmeMSU Device and its components have to be represented as Managed Resources. During the discovery process, Web NMS discovers these managed resources and stores them in the database to manage them. For details of Creating Managed Resource of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Instructions

The AcmeMSU system consists of seven major components. The components with a short description are given below. • AcmeMSUNode : This represents a manageable switch that can be managed via TL1, i.e.

Web NMS finds it as an TL1Node in the network or is manually added byan operator.

• AcmeMSUShelf : This represents the shelf that acts as the container for slot, cards, and ports.

• AcmeMSUSlot : Each switch consists of 11 slots, which are numbered 1-11.

• AcmeMSUCard : Each slot may contain a card, which can be of different types. In this simple example we will work with only one card object, with a type field to specify the card type.

• AcmeMSUPort : Each card can have multiple ports. For example only one port is assumed per card.

• Channel : Each port supports 24 Channels for data transaction.

• CrossConnection : This represents the connection details of a Channel to an external element.

Steps to Model AcmeMSU Device

Step 1: Managed Resource Details Specify the managed resource details. Name of the Managed Resource : AcmeMSUNode Click Select button, Parent Resource Detail screen pops up. Select the Parent Resource from the list. Name the Parent Resource : com.adventnet.nms.topodb.tl1.TL1Node Click Next to proceed. Step 2 : MIB Details Skip Step 2 of Resource Factory.

Note: Because this Application is based on TL1 Protocol Device. This does not require MIB which is exclusive for SNMP protocol.

Click Next to proceed.

AdventNet Inc. 37

TL1 Tutorial

Step 3: Attributes of the Managed Resource Add the following attributes.

Attribute Name Attribute Typelocation contact

String

All the properties of the Managed Resource with type and description are listed in the Attribute table. Click Next to proceed. Step 4: View the Source View the source of the Managed Resource, Relational Managed Resource, schema to store the persistent data in the database and aliases for the tables. Click Finish.

Adding Custom Codes for AcmeMSUNode Managed Resource

Now the AcmeMSUNode Managed Resource is modeled. Before compiling, add the custom code to the Java source file generated by the Wizard. You can add the custom code to the source using the JMACS editor directly as per your requirement. The details of the custom code meant for various objects added to the respective Managed Resource classes are discussed in the next topic. Compile the AcmeMSUNode node created under MANAGEDRESOURCE. Steps to Model Other Managed Resources

Follow the above steps to model the AcmeMSUShelf, AcmeMSUSlot, AcmeMSUCard, AcmeMSUPort, Channel, and CrossConnection as per the table given below:

Managed Resource

Attribute Name

Attribute Type

Parent Resource

AcmeMSUShelf serialno String state slotName

String AcmeMSUSlot

slotno Int CRDREV prodNo ST1Type CRDSN MFDAT deviceName priority

AcmeMSUCard

cardName

String

com.adventnet.nms.topodb.ManagedObject

AdventNet Inc. 38

TL1 Tutorial

Managed Resource

Attribute Name

Attribute Type

Parent Resource

deviceName portName

String AcmeMSUPort

portNo Int connection String Channel channelNumber Int destination bandWidth source

CrossConnection

deviceName

String

Adding Custom Codes for Other Managed Resources

Now the AcmeMSUShelf, AcmeMSUSlot, AcmeMSUCard, and AcmeMSUPort Managed Resource are modeled. Before compiling, add the custom code to the Java source files generated by the Wizard. You can add the custom code to the source using the JMACS editor directly as per your requirement. The details of the custom code meant for various objects added to the respective Managed Resource classes are discussed in the next topic. Compile the AcmeMSUShelf, AcmeMSUSlot, AcmeMSUCard, AcmeMSUPort, Channel, and CrossConnection nodes created under MANAGEDRESOURCE. Result

All the Managed Resources are created now. We can proceed toward customization of Web NMS Services. The first task is to define a Discovery Filter to discover the Switch components.

AdventNet Inc. 39

TL1 Tutorial

5.2.2 Custom Code for Managed Object Classes You will be adding custom code to the Managed object Java source files after their generation. Add the following import statement in AcmeMSUShelf and AcmeMSUSlot MO Classes. import com.adventnet.nms.topodb.ContainerInterface; Also append the following at the end of the Class Declaration lines in the AcmeMSUNode, AcmeMSUShelf, AcmeMSUSlot, AcmeMSUCard, and AcmeMSUPort MO Classes. implements ContainerInterface Add the custom code in the following source files:

• AcmeMSUNode - Custom code is added to accomplish Alarm propagation from the

AcmeMSUCard managed object. • Add custom code in the managed objects source files given below to achieve status polling

of these managed objects. • AcmeMSUCard - Custom code is added to accomplish status polling of the AcmeMSUCard

managed object. • AcmeMSUPort - Custom code is added to accomplish status polling of the AcmeMSUPort

managed object.

Add the following imports in AcmeMSUNode. import java.util.Vector; import java.util.Properties; import com.adventnet.nms.topodb.ContainerInterface; import com.adventnet.nms.topodb.TopoAPI; import com.adventnet.nms.topodb.ManagedObject; import com.adventnet.nms.util.NmsUtil; Add the following custom code in the AcmeMSUNode managed resource after the //<End_Variable_Declarations> tag. public AcmeMSUNode() { setType("acme_msu_node"); setClassname("AcmeMSUNode"); } Add the following custom code in the AcmeMSUNode managed resource after the Object clone() method. public Vector getParentNets() { return super.getParentNets(); } public Vector getCardNames() { try { TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); Properties prop = new Properties(); prop.put("type","acme_msu_card_*");

AdventNet Inc. 40

TL1 Tutorial

Vector cardsAndPorts = topoapi.getObjectNamesWithProps(prop); return cardsAndPorts; }catch(Exception exp) { exp.printStackTrace(); } return null; } public int checkStatus() throws java.rmi.RemoteException { if (true) { Vector cardNames = getCardNames(); int if_status_min = 5; try { for(int i = 0; i < cardNames.size(); i++) { String nextCardName = (String)cardNames.elementAt(i); TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); ManagedObject cardObj = topoapi.getByName(nextCardName); int intStat = 5; if(cardObj != null) { intStat = cardObj.getStatus(); } else { System.err.println("Slot Object is null for: " + nextCardName); } if(intStat > 0) { if(intStat < if_status_min) { if_status_min = intStat; } } } }catch(Exception exp) { exp.printStackTrace(); } if(getStatus() != if_status_min) { System.out.println("STATUS OF " + getName() + " MODIFIED FROM " + getStatus() + " TO --> " + if_status_min); setStatus(if_status_min); } return getStatus(); }

AdventNet Inc. 41

TL1 Tutorial

5.3 Discovering the AcmeMSU devices and GNEs Discovering the AcmeMSU Devices and Gateway Network Elements After modeling the Managed Resource, you need to make the AcmeMSU Manager to discover the Acme MSU devices and add them to the Topology database. To achieve this, you need to customize the existing AdventNet Web NMS Discovery process. This is done by writing a Discovery filter. This filter will ensure that the AcmeMSU Devices and GNEs and the TL1 Devices through the Terminal Servers (GNEs) are discovered. This filter retrieves the details of the AcmeMSU and other TL1 devices and stores in the Topology database. Discovery Filter Code Description in a Nutshell

The Discovery filter gets called when any new object is discovered by Web NMS and decides whether the discovered object can be passed through. As stated earlier, the filter will discover the AcmeMSU Devices and GNEs and the TL1 Devices through the Terminal Servers (GNEs) and add components such as shelves, slots, cards, etc. Refer to the Discovery Filter Flowchart for a pictorial representation Discovery filter class code implementation. This chapter explains the procedure to customize the discovery for the modeled Managed Resources and to populate the database with the network elements' details, using the AdventNet Web NMS Studio.

AdventNet Inc. 42

TL1 Tutorial

Discovery Filter Flowchart

AdventNet Inc. 43

TL1 Tutorial

5.3.1 Discovering Switch Devices Aim To create a discovery filter to discover the AcmeMSU Device and its components and to set the properties for the discovered Managed Resources. The components of the AcmeMSU device are discovered by querying the Agent. For details of Creating Shallow Discovery Filter of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Instructions to Create a Discovery Filter

Follow the steps given below to discover the Switch Device and its components.

Step 1: Invoke the Shallow Discovery Filter Wizard Select the node SERVICES > DISCOVERY > DISCOVERY FILTER. Right-click on the node and select New menu item. Shallow Discovery Filter Wizard pops up. Step 2: Enter the Shallow Discovery Filter Details Provide the following details about the deep discovery filter

Class Name - AcmeMSUDiscFilter

Click Next to proceed. Step 3: Declare the Variables Skip this Variable Declaration screen. Click Next. Step 4: Specify the Filter Criteria In the Filter Criteria screen, choose the Code_Builder node. Right click and select Create Sub Node menu. Create all the three nodes Criteria1, Criteria1, and Criteria1 as SubNodes under Code_Builder node in the tree by right-clicking the node and selecting Add. This brings up the Add/Modify Criteria Editor. Add the following criteria against the nodes, using the Add/Modify Criteria Editor.

Criteria flow

Criteria

Criteria1 (managedObject == null) Criteria2 (managedObject instanceof TL1GatewayNode) || (managedObject

instanceof TL1GatewayAccessSession) Criteria3 ( !(managedObject instanceof TL1Node) )

Click Next to see the Property Information screen. Click Next in this screen.

AdventNet Inc. 44

TL1 Tutorial

Step 5: View the summary of Criteria and Modified properties In the Criteria and Modified Properties screen, you can check the Properties specified. Click Next. Step 6: View the Source In the Source screen, check the generated source code for the Criteria and the Properties defined. Click Finish.

Adding custom codes

After this, the Java source file is generated by the Wizard. You can add the custom code or modify the existing code of the source using the JMACS editor directly as per your requirement. The details of the custom code added to the Discovery filter class in discussed in the following topics. Result

Now you are ready with the device and its components needed to manage the AcmeMSU system. You can now proceed to the next phase, that is Creating custom map and map containers for the AcmeMSU Device and its components.

AdventNet Inc. 45

TL1 Tutorial

5.3.2 Custom Code for Discovery Filter You will be adding custom code to the Discovery Filter Java source files after their generation. The details of the custom code added to the Discovery Filter are available in the Description of Discovery Filter Custom Code topic of this document. Add the following import statements in AcmeMSUDiscFilter class. import java.util.Vector; import java.util.Properties; import java.rmi.RemoteException; import com.adventnet.nms.util.NmsUtil; import com.adventnet.nms.util.LockableObject; import com.adventnet.nms.topodb.tl1.TL1Node; import com.adventnet.nms.topodb.tl1.TL1GatewayNode; import com.adventnet.nms.topodb.tl1.TL1GatewayAccessSession; import com.adventnet.tl1.message.TL1ResponseMessage; import com.adventnet.tl1.message.TL1Line; Add the following variable in the AcmeMSUDiscFilter after the //<End_Variable_Declarations> tag. static String tl1type = null; Add the following code in the AcmeMSUDiscFilter after the //<UserCode_Begin_METHOD_FINISH> tag. Object invObj=null; Object eqptObj=null; tl1type = managedObject.getUserProperty("tl1type"); invObj = TL1SwitchUtil.syncSendCommand((TL1Node)managedObject, "RTRV-INVENTORY", ""); if(invObj == null) { return managedObject; } eqptObj= TL1SwitchUtil.syncSendCommand((TL1Node)managedObject, "RTRV-EQPT", "ALL"); Vector invPropVector,eqptPropVector=null; AcmeMSUNode device=null; if(invObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply=(TL1ResponseMessage)invObj; if(reply==null || reply.getTextBlock()==null) { return null; } device=createTL1Node(managedObject); addObject(device); invPropVector = getPropVector(reply); } else { System.out.println("SOME Other object obt: " + invObj.getClass().getName() + " VALUE: " + invObj); return null; } AcmeMSUShelf shelf=createShelf(device);

AdventNet Inc. 46

TL1 Tutorial

addObject(shelf); if(eqptObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply=(TL1ResponseMessage)eqptObj; if(reply!=null && reply.getTextBlock()!=null) { eqptPropVector=getPropVector(reply); } } if(invPropVector!=null&& eqptPropVector!=null) { for(int i=0;i<invPropVector.size();i++) { Properties prop = (Properties)invPropVector.elementAt(i); addSlots(i+1,device,shelf,prop,eqptPropVector,topoApi); } } else { for(int i=0;i<invPropVector.size();i++) { Properties invProp=(Properties)invPropVector.elementAt(i); addEmptySlots(shelf,invProp,i+1); } } managedObject=null; Add the following custom code in the AcmeMSUDiscFilter at the end of the filter class and before the last "}". private Vector getPropVector(TL1ResponseMessage resp) { Vector slotNames = resp.getTextBlock().getTL1LineList(); Vector inventory=new Vector(); for(int i = 0; i < slotNames.size(); i++) { TL1Line currLine = (TL1Line)slotNames.elementAt(i); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); if ((prop == null) || (prop.size() == 0)) continue; inventory.add(i,prop); } return inventory; } //-------------------------------------------------------------------------------- ------------------------------------------- private AcmeMSUNode createTL1Node(ManagedObject obj) { AcmeMSUNode device = new AcmeMSUNode(); device.setName(obj.getName()); device.setLocation("California"); device.setContact("SysAdmin"); device.setProperties(obj.getProperties()); return device; } //------------------------------------------------------------------------------- -------------------------------------------- private AcmeMSUShelf createShelf(AcmeMSUNode device)

AdventNet Inc. 47

TL1 Tutorial

{ AcmeMSUShelf shelf=new AcmeMSUShelf(); shelf.setName(device.getName()+"_Shelf1"); shelf.setParentKey(device.getName()); shelf.setSerialno(device.getName()+"Bank1"); return shelf; } private void addEmptySlots(AcmeMSUShelf shelf,Properties invProp, int slotNo) throws com.adventnet.nms.store.NmsStorageException, com.adventnet.management. transaction.UserTransactionException { String shelfName = shelf.getName(); AcmeMSUSlot slot = new AcmeMSUSlot(); slot.setName(shelfName+"_"+invProp.getProperty("SLOTNAME")); slot.setSlotno(slotNo); slot.setState("Empty"); slot.setDisplayName(invProp.getProperty("SLOTNAME")); slot.setParentKey(shelf.getName()); addObject(slot); } private void addSlots(int slotNo,AcmeMSUNode device,AcmeMSUShelf shelf, Properties invProp,Vector eqptPropVector,TopoAPI api) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException { AcmeMSUSlot slot = new AcmeMSUSlot(); String slotName = invProp.getProperty("SLOTNAME"); slot.setName(shelf.getName()+"_"+slotName); slot.setSlotno(slotNo); slot.setSlotName(slotName); slot.setState("Empty"); slot.setDisplayName(invProp.getProperty("SLOTNAME")); slot.setParentKey(shelf.getName()); addObject(slot); String name=""; if(slotName.equalsIgnoreCase("SLT-1")) name="CPU-1"; else { String numStr = slotName.substring(slotName.indexOf("-")+1); int num = Integer.parseInt(numStr); name = "ST1-"+String.valueOf(num-1); } for(int i=0;i<eqptPropVector.size();i++) { Properties eqptProp = (Properties)eqptPropVector.elementAt(i); String cardName = eqptProp.getProperty("field0:0"); if(cardName.equalsIgnoreCase(name)) { addCard(slot,device,eqptProp,invProp,api); break; } } } public static void addCard(AcmeMSUSlot slot,AcmeMSUNode device,Properties eqptProp, Properties invProp,TopoAPI api) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException

AdventNet Inc. 48

TL1 Tutorial

{ boolean bool=true; if(eqptProp.getProperty("field0:0").startsWith("CPU")) { bool=false; } AcmeMSUCard card = new AcmeMSUCard(); String cardName = eqptProp.getProperty("field0:0"); card.setName(slot.getName()+"_"+cardName); card.setDisplayName(cardName); card.setDeviceName(device.getName()); card.setType("acme_msu_card_"+invProp.getProperty ("CRDTYPE").toLowerCase()); card.setCRDSN(invProp.getProperty("CRDSN")); card.setMFDAT(invProp.getProperty("MFDAT")); card.setProdNo(invProp.getProperty("PRODNO")); card.setCRDREV(invProp.getProperty("CRDREV")); card.setPriority(eqptProp.getProperty("PRIORITY")); card.setCardName(cardName); if((tl1type != null) && (tl1type.equals("tl1node_gne"))) { card.setUserProperty("tl1cardtype", "tl1card_gne"); } if(invProp.getProperty("CRDTYPE").equalsIgnoreCase("ST1")) { card.setST1Type(eqptProp.getProperty("TYPE")); } else { card.setST1Type("N/A"); } card.setParentKey(slot.getName()); addObject(card); String[] cardChild = {card.getName()}; slot.addChildrenKeys(cardChild); slot.setState("Access"); try { api.lock(slot,LockableObject.WRITE_LOCK,2); api.updateObject(slot,true,true); } catch (com.adventnet.management.transaction. UserTransactionException ute) { System.err.println("Exception while updating the object : " +slot.getName()+"\n"+ ute); ute.printStackTrace(); throw ute; } catch (com.adventnet.nms.store.NmsStorageException nse) { System.err.println("Exception while updating the object : " + slot.getName()+"\n"+nse); nse.printStackTrace(); throw nse; } catch (RemoteException re) { System.err.println("Exception while updating the

AdventNet Inc. 49

TL1 Tutorial

object : " + slot.getName()+"\n"+re); re.printStackTrace(); } catch (com.adventnet.nms.util.AccessDeniedException ade) { System.err.println("Exception while updating the object : " + slot.getName()+"\n"+ade); ade.printStackTrace(); } catch(Exception e) { System.err.println("Error while updating object " +slot); e.printStackTrace(); } if(bool)//This check is made since there is no port for CPU card { addPort(device,card,api); } } private static void addPort(AcmeMSUNode device , AcmeMSUCard card, TopoAPI api) throws com.adventnet. nms.store.NmsStorageException,com.adventnet. management.transaction.UserTransactionException { AcmeMSUPort port = new AcmeMSUPort(); int portNo = 1;//Currently only one port is assumed per card. String portName = card.getCardName()+"-"+String.valueOf(portNo); port.setName(card.getName()+"-"+portNo); port.setDisplayName(card.getDisplayName()+"-"+portNo); port.setPortNo(portNo); port.setPortName(portName); port.setDeviceName(device.getName()); port.setParentKey(card.getName()); addObject(port); if(tl1type != null && tl1type.equals("tl1node_gne")) { port.setUserProperty("tl1porttype", "tl1port_gne"); } for(int i=0;i<5;i++) { addChannel(i+1,port,device); } } private static void addChannel(int chNo , AcmeMSUPort port,AcmeMSUNode device) throws com.adventnet.nms.store. NmsStorageException,com.adventnet. management.transaction.UserTransactionException { Channel channel = new Channel(); String channelName = port.getPortName()+"-"+chNo; channel.setName(device.getName()+channelName); channel.setDisplayName(channelName); String portName=port.getName(); channel.setChannelNumber(chNo); channel.setParentKey(portName); addObject(channel); }

AdventNet Inc. 50

TL1 Tutorial

private static void addObject(ManagedObject obj) throws com.adventnet.nms.store.NmsStorageException,com.adventnet. management.transaction.UserTransactionException { try { TopoAPI api = (TopoAPI)NmsUtil.getAPI("TopoAPI"); api.addObject(obj); } catch (com.adventnet.management.transaction.UserTransactionException ute) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+ute); ute.printStackTrace(); throw ute; } catch (com.adventnet.nms.store.NmsStorageException nse) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+nse); nse.printStackTrace(); throw nse; } catch (RemoteException re) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+re); re.printStackTrace(); } catch(Exception exp) { exp.printStackTrace(); } }

AdventNet Inc. 51

TL1 Tutorial

5.4 Creating Maps to Display AcmeMSU Devices Creating Maps to Display AcmeMSU Devices The AcmeMSU devices discovered need to be represented by images/icons. These representations need to be laid out and displayed in a map. Apart from this, individual Switch device is represented as an actual model of the physical equipment. This is called Chassis view. In this view, the AcmeMSU device with Shelves, Slots, Cards, and Ports are displayed in an exclusive map. This chapter explains the procedure to achieve the following tasks using AdventNet Web NMS Studio:

• Create new Map for the AcmeMSU devices using Map Filter. • Configure the filter in mapIcon.data file. • Creating Map-based Chassis View using Map Filter.

The map filter assigns the Map Symbols for each Slot and Card into a Map Container, capable of containing map symbol children. The filter also sets the parentName property of the child symbol to its containing parent symbol name. Map server generates one map symbol for each map in which the ManagedObject is displayed. In this application, there is one map for every switch. So one map symbol gets generated.

AdventNet Inc. 52

TL1 Tutorial

5.4.1 Creating Maps Aim To create custom map and map containers for the Switch objects and their components. This will also include identifying the Layout to represent the Switch device components. For details of Creating Map Filter of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Instructions

Follow the steps given below to define a Map filter

Step 1 : Invoking the Map Filter Wizard Click on the node SERVICES > MAP > MAP FILTER. Right-click on the node and select New menu item. Step 2 : Map Filter Details Provide the following details about the Map Filter: Class Name - AcmeMSUMapFilter

Click Next to proceed. Step 3 : Add the variables Add the following variable for the respective criteria. Criteria Variable Type Variable NameCriteria1 String netmapname Enter the values as given above and click Add button. Click Next to proceed. Step 4 : Defining Criteria To add the next few criteria, select and right-click Criteria1 node in the tree. Select Create Node option and proceed to add the nodes and their corresponding criteria. Provide the following inputs to define criteria based map representation. Click the Add button to declare Connectors/ Left Operand/ Operator/ Value. Criteria flow Criteria Criteria1 (index != -1) Criteria2 (managedObject instanceof AcmeMSUNode)Criteria3 (managedObject instanceof AcmeMSUShelf)Criteria4 (managedObject instanceof AcmeMSUSlot) Criteria5 (managedObject instanceof AcmeMSUCard)Criteria6 (managedObject instanceof AcmeMSUPort) Click the Next button to proceed. Step 5: Specify the Filter Properties

AdventNet Inc. 53

TL1 Tutorial

Modify the Filter Properties of the respective criteria. Criteria1 Nil Criteria2 Select Map instance from the Map components List Property Name Property Value

mapName "Acme"+managedObject.getName()+".netmap" label managedObject.getName()+"ChassisView" anchored true treeIconFileName images/ipn.png mapSymbolRenderer com.adventnet.nms.mapui.MSUMapSymbolRenderer autoplacement true topology $tl1_components currentTopology tl1_components Criteria3 Select MapContainer instance from the Map components List. Property Name Property Value name managedObject.getName() label managedObject.getDisplayName() objName managedObject.getName() topology $tl1_components currentTopology tl1_components Criteria4 Select MapContainer instance from the Map components List. Property Name Property Value name managedObject.getName() label managedObject.getDisplayName() objName managedObject.getName() parentName managedObject.getParentKey() mapName netmapname topology $tl1_components currentTopology tl1_components Criteria5 Select MapContainer instance from the Map components List. Property Name Property Value name managedObject.getName() label managedObject.getDisplayName() objName managedObject.getName() parentName managedObject.getParentKey() mapName netmapname Topology $tl1_components CurrentTopology tl1_components

AdventNet Inc. 54

TL1 Tutorial

Criteria6 Select MapSymbol instance from the Map components List. Property Name Property Value name managedObject.getName() label managedObject.getDisplayName() objName managedObject.getName() parentName managedObject.getParentKey() mapName netmapname Click Next. Step 6: View the summary of Criteria and Modified properties In the Criteria and Modified Properties screen, check if the Properties are set in the right order you want. If not, use the UP or DOWN buttons to set the order. Click Next. Step 7: View the Source In the Source screen, check the generated source code for the Criteria and the Properties defined. Click Finish.

Adding custom codes

After this, the Java source file is generated by the Wizard. You can add the custom code or modify the existing code of the source using the JMACS editor directly as per your requirement. The details of the custom code added to the Map filter class in discussed in the next topic. Result

The map view illustrating the Containment relationship between the Switch object and their components are ready.

AdventNet Inc. 55

TL1 Tutorial

5.4.2 Customizing the Map Filter Code In this section, you can look at how to customize Map to display TL1 elements of a network. Add the custom code in the Map filter in the appropriate locations as given below: Add the following import statements in AcmeMSUMapFilter class. import java.util.*; import com.adventnet.nms.topodb.ManagedObject; import com.adventnet.nms.mapdb.*; import com.adventnet.nms.util.NmsUtil; import java.sql.Time; import java.sql.Date; import java.sql.Timestamp; Add the following variables in the AcmeMSUMapFilter before the //<Begin_filterMapSymbols_Vector_ManagedObject_MapAPI> tag. String moname=managedObject.getName(); int index=moname.indexOf("_Shelf"); Add the following custom code for Criteria1 after the //<UserCode_Begin_Criteria1_IF_START> tag. String mapname=moname.substring(0,index); netmapname="Acme"+mapname+".netmap"; Add the following code after the //Usercode_Begin_Criteria2_IF_START tag. Vector parentMaps = ((AcmeMSUNode)managedObject).getParentNets(); String parentMap = "Network Maps"; if(parentMaps!=null && !parentMaps.isEmpty()) { parentMap = (String)parentMaps.elementAt(0); } Add the following code after the //Usercode_Begin_Criteria2_IF_FINISH tag. map0.put("parentNode",parentMap+".netmap"); Add the following custom code, after the //<UserCode_Begin_Criteria3_PROPERTIES_FINISH> tag, for the shelf object since the shelf is assumed to be a container which contains slots, cards, and ports. mapContainer0.setMapName("Acme"+managedObject.getParentKey()+".netmap"); mapSymbols.removeAllElements(); Add the following custom code, after the //<UserCode_Begin_Criteria4_PROPERTIES_FINISH> tag, for each and every AcmeMSUSlot discovered instead of adding a MapSymbol, since a slot is assumed to be a container which contains a Card inside it. mapContainer1.setUserProperty("slotnumber",String.valueOf(((AcmeMSUSlot) managedObject).getSlotno())); mapSymbols.removeAllElements();

AdventNet Inc. 56

TL1 Tutorial

Add the following custom code for each and every AcmeMSUCard discovered instead of adding a MapSymbol, since a card is assumed to be a container which contains a port inside it, also we set the parent name to be the slot name so that the card will be added inside the slot. Add the following custom code after the //<UserCode_Begin_Criteria5_IF_START> tag. AcmeMSUCard cardObj = (AcmeMSUCard)managedObject; String st1Type = cardObj.getST1Type(); Add the following custom code after the tag //<UserCode_Begin_Criteria5_PROPERTIES_FINISH>. mapContainer2.setUserProperty("st1type",st1Type); mapSymbols.removeAllElements();

AdventNet Inc. 57

TL1 Tutorial

5.4.3 Creating and Configuring other Map related files Create/Configure the following files for viewing the ACME MSU Device Maps.

• Create a Custom Map Layout for AcmeMSU Device. • Create a Custom Map Symbol Renderer Class. • Create a Custom Class for Chassis View of AcmeMSU device, extending NMS Map Applet. • Configure the Chassis Map. • Configure NMS Panels.

Creating Custom AcmeMSU Device Map Layout

This topic explains the layout to be adopted in the AcmeMSU device map. In order to lay the shelf, slots, cards, and ports on the map for the switch, you have to write a Map Symbol Layout class called the MSUMapSymbolLayout class. Create this Symbol Layout class using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. The description of the MSU Map Layout class is available in the Description of Custom AcmeMSU Device Map layout topic of this document. Creating Custom Map Symbol Renderer

This topic explains the Map Symbol Renderer to be adopted in the AcmeMSU device map. You have to create the MSUMapSymbolRenderer class. This, you have to create using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. The description of the MSU Map Symbol Renderer class is available in the Description of Custom Map Symbol Renderer topic of this document. Creating Custom Class for AcmeMSU Chassis View

Creating a Class Extending Map Applet for AcmeMSU Chassis View

In order to customize the AcmeMSU Device's Chassis View, you have to write an Map Applet extension class called the AcmeExtMapApplet class. Create this class using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer the AdventNet Web NMS Studio documentation. The description of the AcmeMSU Map Applet class is available in the Description of Custom Class for AcmeMSU Chassis View topic of this document.

AdventNet Inc. 58

TL1 Tutorial

Configuring the Chassis Map

This topic explains how to associate the map filters and objTypes to AcmeMSU device components. Also the image that is associated with each component is mentioned in this file. Follow the procedure given below:

• Open the mapIcon.data file under <Project HOME>/WebNMS/conf directory in a text editor. • Append the following entries.

Note: The file mapIcon.data file must be opened only in a text editor separately.

<!-- Add the following element after the root element, i.e., <MAP_ICON_DATA> --> <OBJTYPES background node="1" network="2" gateway="3" sub-symbol="4" site="5" acme_msu_shelf="400" acme_msu_slot="100" acme_msu_card_st1="200" acme_msu_port_11="300"/> <!-- Add the following nodes in the end, after the default nodes --> <DATA

TYPE="acme_msu_shelf" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter" menuName="cardmenu" objType="400"/>

<DATA

TYPE="acme_msu_slot" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter" objType="100" menuName="cardmenu" iconName="emptyslot.png" />

<DATA

TYPE="acme_msu_card_cpu" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter" objType="200" menuName="cardmenu" iconName="cpuio.png" />

<DATA

TYPE="acme_msu_card_st1" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter"

AdventNet Inc. 59

TL1 Tutorial

objType="200" menuName="provmenu" />

<DATA

TYPE="acme_msu_port" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter" menuName="crossconnectmenu" objType="300" iconName="led.png" />

Configuring NMS Panels

To change the NMS Panels shown in the Left-side frame of the Web NMS Client, configure the NmsPanels.conf file with appropriate data present in the <Project Home>/WebNMS/conf directory. Using Studio to Configure NMS Panels

Configuring NMS Panels in this application was achieved with the help of the AdventNet Web NMS Studio. Open the NmsPanels.conf file in the Other Files and add the nodes and their details. You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with XML files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Change the package name as given below for the MANAGED-OBJECT-FORM parameter in NmsPanels.conf file. <NMS_PANELS_CONF> <PANEL NO-OF-MAPS-TO-BE-REMEMBERED="15" TREE-POPUP-MENU="Custom Views,frameoptions.xml,TreeOperations.xml" MANAGED-OBJECT-FORM="com.adventnet.nms.mapui.MapCustomProp" className="com.adventnet.nms.tutorials.tl1.AcmeExtMapApplet" DEFAULT-CLOSE-OPERATION="HIDE_ON_CLOSE" PROPERTIES-FORM="com.adventnet.nms.mapui.MapCustomProp" PANEL-KEY="MapApplet"/> </NMS_PANELS_CONF>

AdventNet Inc. 60

TL1 Tutorial

5.5 Managing the Alerts of AcmeMSU Device Managing the Alerts of AcmeMSU Device To receive, process the failures in the managed network elements (i.e., AcmeMSU devices) and present it in a meaningful form, you have to implement Fault management service of AdventNet Web NMS. The AcmeMSU device notifies any abnormality in the operations, parameters and failures to the AcmeMSU Manager application in the form of Autonomous Messages. Status Polling of AcmeMSU Device

You have to ensure that AcmeMSU Manager gets the status of the AcmeMSU device and its components periodically. This will be updated in the database and displayed in the Client. The tutorial explains how to customize the Fault management features. • The Correlating events topic explains how to minimize the clutter due to multiple related event

and alarms. • The Status propagation topic deals in a detailed manner on how to notify failure events to

affected components above in the hierarchy.

AdventNet Inc. 61

TL1 Tutorial

5.5.1 Correlating Events Creating Event Correlation Filter Class In order to correlate events and failures of the AcmeMSU device, you have to write an event filter class called the MSUEventFilter class. Create this filter class using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. This Event filter you will use for correlating the Events from ports to cards, slots, shelves, and nodes. The description of the Event filter class is available in the Description of MSU Event Correlation Filter Class topic of this document.

AdventNet Inc. 62

TL1 Tutorial

5.5.2 Status Propagation Using Studio to Configure Status Propagation Filter Adding the Status propagation filter used in this application was achieved with the help of the AdventNet Web NMS Studio. Open the propagation.filters file in the Other Files and add the nodes and their details. You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with XML files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Add the following node to the propagation.filters file. <PROPAGATION_FILTERS> <FILTER className="com.adventnet.nms.tutorials.tl1.StatusPropagation"/> </PROPAGATION_FILTERS> In order to set up alarm propagation class, called StatusPropagation class, configure it as given in the above node as Filter class. In order to invoke this class an entry has to be given in the propagation.filters file under <Web NMS Home>/conf directory. Creating Status Propagation Filter Class In order to set up status propagation, you have to write an alarm propagation filter class called StatusPropagation class. Create this filter class using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. This status propagation filter you will use for propagating status from ports to cards, slots, shelves, and nodes. The description of the Status Propagation filter class is available in the Description of AcmeMSU Status Propagation Filter Class topic of this document.

AdventNet Inc. 63

TL1 Tutorial

5.6 Fetching Device Status Periodically You need to ensure that the status of the Managed Objects are monitored and displayed in the Client UI. For each type of device, Web NMS performs status polling of these devices based on the configuration. For each managed object, it invokes the status polling specified by the configuration, which may be a standard operation such as pinging the device already supported by Web NMS or a custom polling that is needed for a specific device or component. You can override the status polling code for your managed object. You will see how the Port object is used, for which you will poll the operational status of an interface corresponding to the port number on a card. The custom code for achieving the above task is added to the Port object as explained in the Customizing Port object topic of this tutorial document.

AdventNet Inc. 64

TL1 Tutorial

5.6.1 Status Polling for Card The description of the Custom Code for the Status Polling of Card Managed Object is available in the Description of Custom Code for Status Polling of Card topic of this document. Add the following imports in AcmeMSUCard MO Class. import java.util.Vector; import java.util.Properties; import com.adventnet.nms.topodb.ContainerInterface; import com.adventnet.nms.topodb.TopoAPI; import com.adventnet.nms.util.NmsUtil; import com.adventnet.tl1.message.TL1ResponseMessage; import com.adventnet.tl1.message.TL1TextBlock; import com.adventnet.tl1.message.TL1Line; Add the following Custom Code after the //<End_Variable_Declarations> tag. public AcmeMSUCard() { setClassname("AcmeMSUCard"); setPollInterval(300); } Add the following Custom Code before the //<Begin_checkStatus> tag. public int checkStatus() throws java.rmi.RemoteException { try { TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); AcmeMSUNode myswitch = (AcmeMSUNode)topoapi.getByName(getDeviceName()); String cardName = getName().substring(getParentKey().length()+1); Object resultObj = TL1SwitchUtil.syncSendCommand(myswitch, "RTRV-EQPT", cardName); if(resultObj == null) { return getStatus(); } if(resultObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply = (TL1ResponseMessage)resultObj; String cmdCode = reply.getResponseId().getCompletionCode(); int status = getStatus(); if(cmdCode.equals(TL1ResponseMessage.COMPLETED)) { status = 5; } else if(cmdCode.equals(TL1ResponseMessage.DELAYED_ACTIVATION)) { status = 4; } else if(cmdCode.equals(TL1ResponseMessage.PARTIAL_SUCCESS)) { status = 3; }

AdventNet Inc. 65

TL1 Tutorial

else if(cmdCode.equals(TL1ResponseMessage.DENIED)) { status = 2; } else if(cmdCode.equals(TL1ResponseMessage.RETRIEVE)) { status = 2; } TL1TextBlock textBlk = reply.getTextBlock(); if(textBlk != null) { Vector resp = textBlk.getTL1LineList(); if(resp.size() == 0) { return status; } else { TL1Line currLine = (TL1Line)resp.elementAt(0); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); String str = null; if(getType().equalsIgnoreCase("CPU")) { str = prop.getProperty("PST"); } else { str = prop.getProperty("PST"); } if(str != null) { status = severityForCardStatus(str); } } } if(status==1 || status==4) { setManaged(false); } else { setStatus(status); } } return getStatus(); }catch(Exception exp) { exp.printStackTrace(); }

AdventNet Inc. 66

TL1 Tutorial

5.6.2 Status Polling for Port The description of the Custom Code for the Status Polling of Port Managed Object is available in the Description of Custom Code for Status Polling of Port topic of this document. Add the following imports in AcmeMSUPort MO Class. import java.util.Vector; import java.util.Properties; import com.adventnet.nms.topodb.ContainerInterface; import com.adventnet.nms.topodb.TopoAPI; import com.adventnet.nms.util.NmsUtil; import com.adventnet.tl1.message.TL1ResponseMessage; import com.adventnet.tl1.message.TL1TextBlock; import com.adventnet.tl1.message.TL1Line; Add the following Custom Code after the //<End_Variable_Declarations> tag. public AcmeMSUPort() { setType("acme_msu_port"); setClassname("AcmeMSUPort"); setPollInterval(300); } Add the following Custom Code before the //<Begin_checkStatus> tag. public int checkStatus() throws java.rmi.RemoteException { try { TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); AcmeMSUNode mySwitch = (AcmeMSUNode)topoapi.getByName(getDeviceName()); AcmeMSUCard card = (AcmeMSUCard)topoapi.getByName(getParentKey()); String portName = getName().substring(card.getParentKey().length()+1); Object resultObj = TL1SwitchUtil.syncSendCommand(mySwitch, "RTRV-FAC", portName); if(resultObj == null) { return getStatus(); } if(resultObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply = (TL1ResponseMessage)resultObj; String cmdCode = reply.getResponseId().getCompletionCode(); int status = getStatus(); if(cmdCode.equals(TL1ResponseMessage.COMPLETED)) { status = 5; } else if(cmdCode.equals(TL1ResponseMessage.DELAYED_ACTIVATION)) { status = 4; } else if(cmdCode.equals(TL1ResponseMessage.PARTIAL_SUCCESS))

AdventNet Inc. 67

TL1 Tutorial

{ status = 3; } else if(cmdCode.equals(TL1ResponseMessage.DENIED)) { status = 2; } else if(cmdCode.equals(TL1ResponseMessage.RETRIEVE)) { status = 2; } TL1TextBlock textBlk = reply.getTextBlock(); if(textBlk != null) { Vector resp = textBlk.getTL1LineList(); if(resp.size() == 0) { return status; } else { TL1Line currLine = (TL1Line)resp.elementAt(0); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); String str = prop.getProperty("PST"); if(str != null) { status = TL1SwitchUtil.severityForCardStatus(str); if (status==-1) status=getStatus(); } } } setStatus(status); return getStatus(); } }catch(Exception exp) { exp.printStackTrace(); }

AdventNet Inc. 68

TL1 Tutorial

5.7 Performance Monitoring of the AcmeMSU Device The Performance Management permits the AcmeMSU device to accumulate data to validate the integrity of incoming electrical and optical data. This data is then used to calculate performance parameters for each entity being monitored. These parameters can then be used to identify potential trouble, to locate a fault, for tariffs and for preventive maintenance. For all performance monitoring parameters, data is accumulated for two time periods, 15 minutes and day (24 hours). The PM parameters for the current 15-minute, and 32 previous 15-minute periods are maintained. For the day periods, the PM data for 1 current, and 7 previous day periods is maintained. The following Performance parameters are monitored for the T1 line:

CVL - Code Violations (Line) ESL - Errored Seconds (Line) SESL - Severely Errored Seconds (Line)LOSSL - Loss Of Signal Seconds (Line)

The following Performance parameters are monitored for the T1 path:

CVP - Code Violations (Path) ESP - Errored Seconds (Path) SESP - Severely Errored Seconds (Path) AISSP - Alarm Indication Signal Seconds (Path) SASP - Severely Errored Frame / Alarm indication

signal Seconds (Path) CSSP - Controlled Slip Seconds (Path) UASP - UnAvailable Seconds (Path) FCP - Failure Count (Path)

In the case of this tutorial application, only ESL,SESL,LOSSL,ESP,CSSP, PST and SST parameters are monitored.

AdventNet Inc. 69

TL1 Tutorial

5.7.1 Performance Management This section explains how to customize the performance for the AcmeMSU device. Using Studio to Configure the Performance Parameters of AcmeMSU Device to be Polled Adding the Performance parameters to be polled for this application will be with the help of the AdventNet Web NMS Studio. Follow steps to edit the Polling.conf file and add the nodes and their details.

Click on the node Services > Performance > Polling.conf. The Performance service wizard of the Studio provides the facility to create and edit the nodes of the conf file and its details (which are in XML format). You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with Configuration files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. In this application create three polling objects to represent the port, card, and the node. Append the following lines to perform the data collection for the port in the Polling.conf file. <POLLING_OBJECT name="acme_msu_port"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="equals" value="acme_msu_port" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" > <DATA_TO_POLL dataIdentifier="RTRV-PM::${portName}:;" protocol="TL1" type="multiple" name="Port_Dol_Integer" response="ESL,SESL,LOSSL,ESP,CSSP" /> </DATA_COLLECTION> </POLLING_OBJECT> Similarly to collect data for the card the following entries have been appended in the Polling.conf file. <POLLING_OBJECT name="acme_msu_card"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="startsWith" value="acme_msu_card_" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" > <DATA_TO_POLL dataIdentifier="RTRV-EQPT::${cardName}:;" protocol="TL1" type="multiple" name="Port_Dol_String" response="PST,SST" /> </DATA_COLLECTION> </POLLING_OBJECT>

AdventNet Inc. 70

TL1 Tutorial

In order to collect data for the node as a whole, append the following entries in the Polling.conf file. <POLLING_OBJECT name="acme_msu_node"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="equals" value="acme_msu_node" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" protocol="TL1" > <DATA_TO_POLL dataIdentifier="RTRV-EQPT::ALL:;" type="multiple" name="Eqpt_ALL_String" response="PST,SST" componentId="0" /> <DATA_TO_POLL dataIdentifier="RTRV-PM::ALL:;" type="multiple" name="Port_ALL_Integer" response="ESL,SESL,LOSSL,ESP,CSSP" componentId="0" /> </DATA_COLLECTION> </POLLING_OBJECT>

AdventNet Inc. 71

TL1 Tutorial

5.8 Provisioning the AcmeMSU Device To show the features of the provisioning module two examples have been taken in this tutorial application.

• Modifying the Managed Object properties • Static Cross Connect

To perform any provisioning operation three tasks need to be performed :

• You need to write a template which takes care of all the inputs required for the provisioning operation.

• You need to associate the template with a menu, so that it can be invoked from the client. • You require to write a Template filter or Post Provisioning or a Pre Provisioning Filter to

perform additional operations. In this chapter, the above example tasks are explained in detail.

AdventNet Inc. 72

TL1 Tutorial

5.8.1 Modifying the Managed Object Property In this example, you will see how you can change some of the managed object properties of a card through provisioning. In this tutorial application, you will change the priority of the card and also change the status of the card, i.e., make the card in service or out of service. To carryout the provisioning task of Modifying the Managed Object Property, carryout the following steps.

• Writing a Provisioning Template • Creating Pre-Provisioning Filter • Processing the Result Using Post Provisioning Filter

Writing a Provisioning Template The first step is to write a template. AdventNet provides XML-based Templates. For this application, an XML Template called ChangeCardType must be created. For easy development, you can take the file available in the ready-built project and place it under otherfiles of the application that you are building. The file is available in <Web NMS Home>/StudioTools/Studio/projects/TL1_Tutorial/otherfiles directory.

Note:The DTD reference cannot be provided in the XML editor that opens in Studio. Include the reference manually after you create the file. The reference is given in the code snippet below, but will not be visible when you open in Studio.

Using Studio to Generate Template

Create a file called ChangeCardType in the Other Files and add the nodes and their details. You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with XML files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation.

Add the following node to the ChangeCardType file. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE Template SYSTEM "Template.dtd"> <Template name="ChangeCardType" owner="root" displayForms="tab" autoDeregister="true"> <Stage label="3#"> <InventoryInput id="1#" MOName="$TemplateParam$Host" MOField="name" default="" useInventoryService="TopoAPI"/> <InventoryInput id="2#" MOName="$TemplateParam$Host" MOField="priority" default="" useInventoryService="TopoAPI"/> <InventoryInput id="3#" MOName="$TemplateParam$Host" MOField="cardName" default="" useInventoryService="TopoAPI"/> <InventoryInput id="4#" MOName="$TemplateParam$Host" MOField="deviceName" default="" useInventoryService="TopoAPI"/> <InventoryInput id="5#" MOName="$TemplateParam$Host" MOField="CRDSN" default="" useInventoryService="TopoAPI"/> <InventoryInput id="6#" MOName="$TemplateParam$Host" MOField="prodNo" default="" useInventoryService="TopoAPI"/> <InventoryInput id="7#" MOName="$TemplateParam$Host" MOField="CRDREV"

AdventNet Inc. 73

TL1 Tutorial

default="" useInventoryService="TopoAPI"/> <InventoryInput id="8#" MOName="$TemplateParam$Host" MOField="MFDAT" default="" useInventoryService="TopoAPI"/> <InventoryInput id="9#" MOName="$TemplateParam$Host" MOField="tl1cardtype" default="" useInventoryService="TopoAPI"/> <Form title="Configuration" description="This template enables to change the priority and status of the card" id="3#"> <UserInput id="1#" name="cardname" label="CARD NAME" default="$InventoryInput$1#" editable="false" required="false"/> <UserInput id="6#" name="crdsn" label="CRDSN" default="$InventoryInput$5#" editable="false" required="false"/> <UserInput id="7#" name="mfdat" label="MFDAT" default="$InventoryInput$8#" editable="false" required="false"/> <UserInput id="8#" name="prodno" label="PRODNO" default="$InventoryInput$6#" editable="false" required="false"/> <UserInput id="9#" name="crdrev" label="CRDREV" default="$InventoryInput$7#" editable="false" required="false"/> <UserInput id="3#" name="priority" label="PRIORITY" default="$InventoryInput$2#" editable="false" required="false"> <Qualifier type="choice"> <Enum name="1" value="1"/> <Enum name="2" value="2"/> </Qualifier> </UserInput> <UserInput id="5#" name="status" label="PST" default="IS" editable="false" required="false"> <Qualifier type="choice"> <Enum name="IS" value="IS"/> <Enum name="OOS" value="OOS"/> </Qualifier> </UserInput> </Form> <ConfigTask taskName="EditCardProps" isNewTask="true" isOverwrite="true" isSequential="false" persistence="true" deviceResult="false" isTemplate="false" rollbackNeeded="false" version="1.0"> <ProtocolMap name="tl1"> <Device host="$InventoryInput$4#" port="9099"/> </ProtocolMap> <!-- configuration attributes --> <Attribute identifier="ED-EQPT" commandCode="ED-EQPT" targetID="" accessID="$InventoryInput$3#" generalBlock="" messagePayLoadBlock="PRIORITY=$UserInput$3#"/> <Attribute identifier="ED-EQPT" commandCode="ED-EQPT" targetID="" accessID="$InventoryInput$3#" generalBlock="" messagePayLoadBlock="PST=$UserInput$5#"/> </ConfigTask> </Stage> </Template>

Creating and Configuring Pre-Provisioning Filter Create TL1GatewayPreProvisioningFilter.java file using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in the newly created file. For details of Working with other files of AdventNet Web NMS Studio, refer the AdventNet Web NMS Studio documentation.

AdventNet Inc. 74

TL1 Tutorial

Configuring the Pre-Provisioning Filter topic To invoke this class, entry has to be given in the ProvisioningFilters.xml file within the <PreProvisioningFilters> tag. This file is present under <Project HOME>/WebNMS/conf directory. ......... <PreProvisioningFilters> <PreProvisioningFilter template="AcmeCrossConnect" class="com.adventnet.nms.tutorials.tl1.TL1GatewayPreProvisioningFilter"/> <PreProvisioningFilter template="ChangeCardType" class="com.adventnet.nms.tutorials.tl1.TL1GatewayPreProvisioningFilter"/> .......... Processing the Result Using Post Provisioning Filter After the provisioning activity gets completed (whether successful or not), one may need to do specific custom functions to complete the provisioning operation. Post-provisioning filters provide this capability. In this tutorial application, if the configuration result is successful it would set the priority of the card. Also it would set the status of the card. The ChangeCard.java file acts as the PostProvisioning Filter. Create ChangeCard.java file using other files option of the Studio project. Create the file with dummy inputs. Copy the contents from the above given URL and overwrite completely in your file. For details of Working with other files of AdventNet Web NMS Studio, refer the AdventNet Web NMS Studio documentation. Configuring the Post-Provisioning Filter topic To invoke this class, entry has to be given in the ProvisioningFilters.xml file within the <PostProvisioningFilters> tag. This file is present under <Project HOME>/WebNMS/conf directory. ........ <PostProvisioningFilters> <PostProvisioningFilter template="ChangeCardType" class="com.adventnet.nms.tutorials.tl1.ChangeCard"/> <PostProvisioningFilter template="inv_ne_form_config_update" class="test.PostProvisioningFilterExample"/> </PostProvisioningFilters> ....... For the details of configuring both the Pre and Post Provisioning Filters, refer the Configuring Provisioning Filters topic

AdventNet Inc. 75

TL1 Tutorial

5.8.2 Creating a Cross Connection In this section, you would see the second provisioning example that is establishing static cross connection between the Channels of a Port. To carryout the provisioning task of Creating a Cross Connection, carryout the following steps.

• Writing a Provisioning Template • Creating Custom Classes for Provisioning

Writing a Provisioning Template

The first step is to write a template. AdventNet provides XML-based Templates. For this application, an XML Template called AcmeCrossConnect must be created. For easy development, you can take the file available in the ready-built project and place it under otherfiles of the application that you are building. The file is available in <Web NMS Home>/StudioTools/Studio/projects/TL1_Tutorial/otherfiles directory.

Note: The DTD reference cannot be provided in the XML editor that opens in Studio. Include the reference manually after you create the file. The reference is given in the code snippet below, but will not be visible when you open in Studio. The files AcmeCrossConnect.xml, CrossConnectUI.java, CrossConnectUtil.java must be loaded in OTHERFILES.

Using Studio to Generate Template

Create a file called AcmeCrossConnect in the Other Files and add the nodes and their details. You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with XML files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation.

Add the following node to the AcmeCrossConnect file. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE Template SYSTEM "Template.dtd"> <Template name="AcmeCrossConnect" owner="root" displayForms="tab" autoDeregister="true"> <Stage label="1#"> <ConfigTask taskName="AcmeCrossConnectTask" isNewTask="true" isOverwrite="true" isSequential="false" persistence="true" deviceResult="false" isTemplate="false" rollbackNeeded="false" version="1.0"> <ProtocolMap name="tl1"> <Device host="localhost" port="9099"/> </ProtocolMap> <!-- configuration attributes --> <Attribute identifier="ENT-CRS-T0" commandCode="ENT-CRS-T0" targetID="" accessID="ST1-1-1-1,ST1-1-1-2" generalBlock="" messagePayLoadBlock="TYPE=DATA,MODE=2WAY,NAME=CUSTOMER1,PST=IS"/> </ConfigTask> <InventoryUpdate> <MOUpdate MOName="Conn1"

AdventNet Inc. 76

TL1 Tutorial

MOClass="com.adventnet.nms.tutorials.tl1.CrossConnection" isNew="true" when="onSuccess"> <Property name="source" value="ST1-1-1-1"/> <Property name="destination" value="ST1-1-1-2"/> <Property name="bandWidth" value="20MB"/> <Property name="deviceName" value="hostName"/> </MOUpdate> <MOUpdate MOName="ST1-1-1-1" MOClass="com.adventnet.tutorials.tl1.Channel" isNew="false" when="onSuccess"> <Property name="connection" value="unknown"/> </MOUpdate> </InventoryUpdate> </Stage> </Template>

Creating Custom Classes for Provisioning

The CrossConnectUI.java and CrossConnectUtil.java are the two classes that are responsible for the UI representation and establishment of the cross connect. Create CrossConnectUI.java and CrossConnectUtil.java files using other files option of the Studio project. Create the files with dummy inputs. Copy the contents from the above given URLs and overwrite completely in your files. For details of Working with other files of AdventNet Web NMS Studio, refer the AdventNet Web NMS Studio documentation. For the details of configuring both the Pre and Post Provisioning Filters, refer the Configuring Provisioning Filters topic

AdventNet Inc. 77

TL1 Tutorial

5.8.3 Configuring Provisioning Files Carryout the following Provisioning Files configurations.

• Configuring the Provisioning Filters • Associating the Template With a Menu • Adding Template.dtd file for Provisioning

Configuring the Provisioning Filters

Adding the Provisioning filter used in this application was achieved with the help of the AdventNet Web NMS Studio. Open the ProvisioningFilters.xml file in the Provisioning Service node and add the nodes and their details. You can add or edit the node or modify the existing node directly as per your requirement using the UI. The UI is invoked by the right click menu items Add, Modify, and Delete . For details of Working with XML files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Add the following node to the ProvisioningFilters.xml file. <ProvisioningFilters> <TemplateFilters> <TemplateFilter template="inv_ne_form_config_update" class="test.TemplateFilterExample"/> </TemplateFilters> <PostProvisioningFilters> <PostProvisioningFilter template="ChangeCardType" class="com.adventnet.nms.tutorials.tl1.ChangeCard"/> <PostProvisioningFilter template="inv_ne_form_config_update" class="test.PostProvisioningFilterExample"/> </PostProvisioningFilters> <PreProvisioningFilters> <PreProvisioningFilter template="AcmeCrossConnect" class="com.adventnet.nms.tutorials.tl1.TL1GatewayPreProvisioningFilter"/> <PreProvisioningFilter template="ChangeCardType" class="com.adventnet.nms.tutorials.tl1.TL1GatewayPreProvisioningFilter"/> <PreProvisioningFilter template="inv_ne_form_config_update" class="test.PreProvisioningFilterExample"/> </PreProvisioningFilters> </ProvisioningFilters> Associating the Template With a Menu

Configure Provisioning Menu ChangeCardType To invoke ChangeCardType template from the client you associate it with a menu. For this purpose, the provmenu.xml file under the <Web NMS Home>mapdata/menus directory is provided. The entry for associating the menu is provided in the provmenu.xml file .

AdventNet Inc. 78

TL1 Tutorial

• Open the provmenu.xml file under <Web NMS HOME>/mapdata/menus directory in a text editor.

• Append the following entries.

Note: This file is not supported in the Studio, you can create/edit the file only in a text editor separately.

<MENU name="MSUProv" owner="root" group="users"> <MENU-ITEM name="Provision"> <JAVA-UI action_type="openframe" action_value="test.provisioning.TemplateNmsFrame?Host=${name}&amp; TemplateName=ChangeCardType&amp;"> </JAVA-UI> </MENU-ITEM> </MENU> CrossConnectUI To invoke CrossConnectUI class from the Client, the crossconnectmenu.xml file has been provided under the <Web NMS Home>mapdata/menus directory of this tutorial. The entries in this file are shown below: <?xml version="1.0" ?> <!DOCTYPE MENU SYSTEM "menu.dtd"> <MENU name="CrossConnect" owner="root" group="users"> <MENU-ITEM name = "Managed Object Properties" action_type="function" action_value="Managed Object Properties"> </MENU-ITEM> <MENU-ITEM name="CrossConnect"> <JAVA-UI action_type="INVOKE_CLASS" action_value="com.adventnet.nms.tutorials.tl1.CrossConnectUI? Host=${objName}&amp;parentName=${parentName}&amp;" > </JAVA-UI> </MENU-ITEM> <MENU-ITEM name="Alerts" action_type="openpanel" action_value="AlertApplet?FILTER_ENTITY=${objName}*" /> </MENU> Configure mapIcon.data file The pre-built Web NMS Frame (TemplateNmsFrame) is used to open the template. The Host (managed object which is associated with this menu) and the template that needs to be opened are passed as arguments to this class.

• Open the mapIcon.data file under <Project HOME>/WebNMS/conf directory in a text editor. • Append the following entries.

The entry for provmenu.xml menu is provided in the mapIcon.data file.

AdventNet Inc. 79

TL1 Tutorial

<DATA TYPE="acme_msu_card_st1" MAP_FILTER="com.adventnet.nms.tutorials.tl1.AcmeMSUMapFilter" objType="200" menuName="provmenu" /> The entry for crossconnectmenu.xml menu is provided in the mapIcon.data file. <DATA TYPE="acme_msu_port_t1" MAP_FILTER="com.acme.msu.MSUMapFilter" menuName="crossconnectmenu" objType="300" iconName="led.png" /> Adding Template.dtd file for Provisioning In order to define the contents of the XML files in this case it is provisioning templates, you have to create a dtd (Document Type Definition) file called the Template.dtd file. Follow the procedure given below:

• Create the Template.dtd file under <Project HOME>/WebNMS/otherfiles directory in a text editor.

• Copy the contents from the URL given above and completely overwrite in the newly created files.

Warning: The file Template.dtd file must be opened only in a text editor separately. Do not open and edit this file in Studio.

Bundle the Template.dtd in the Other Resources and set <Project Home>/WebNMS/provisioningtemplates as Destination directory.

AdventNet Inc. 80

TL1 Tutorial

5.9 Client-Server Communication 5.9.1 Creating Client Server Communication Class

• Creating Client Server Communication Classes using Studio • Configuring Client Server Communication Classes

Creating Client Server Communication Class using Studio

The data from the client are sent to the server through the common socket. This is handled in the AcmeMsuClientSocketConn.java class. For detailed description refer Detailed Description of Provisioning Client Server Communication Code topic of this document. Creating Client Server Communication Classes using Studio

• AcmeSocketSessionConnBE.java • AcmeSocketServerConnBE.java

Creating Utility Class for Client Server Communication using Studio

• TL1SwitchUtil.java Create all the above classes using other files option of the Studio project. Create the files with dummy inputs. Copy the contents from the above given URLs and overwrite completely in your files. For details of Working with other files of AdventNet Web NMS Studio, refer the AdventNet Web NMS Studio documentation. Configuring Client Server Communication for Provisioning

Server Configuration - Editing NmsProcessesBE.conf File

The Studio provides a normal text Editor to edit NmsProcessesBE.conf file.

For details of Working with Configuration files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation.

Click on the node Services > Server_Configuration > NmsProcessesBE.conf.

Parameters of NmsProcessesBE.conf File

In the configuration file, the fully qualified class name of your implementation of com.adventnet.nms.util.RunProcessInterface should be specified against the keyword PROCESS, and the parameters for the module have to be specified against the keyword ARGS.

Make the following entry in the conf file. To keep listening for client requests AcmeMsuSocketServerConnBE class is started as a process, when the server is started. For this make an entry in the NmsProcessesBE.conf file.

#java com.adventnet.nms.tutorials.tl1.AcmeMsuSocketServerConnBE PROCESS com.adventnet.nms.tutorials.tl1.AcmeMsuSocketServerConnBE ARGS NULL

AdventNet Inc. 81

TL1 Tutorial

5.10 Re-branding In building your AcmeMSU Manager, you may wish to customize the basic user interface functions. AdventNet Web NMS supports such customization for creating new products in multiple ways. To illustrate how this can be done, you will make a few changes to the user interface to build an TL1 Element Manager that you will call as AcmeMSU Manager. These are only a subset of the many changes that can be made to the user interface for specific applications. Aim This section explains how to re-brand the application that is built to suit the customers requirements. Re-branding includes internationalization, changing the name of the product, its version, splash images, logo images, etc. For details of Using i18N Editor tool of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. For details of Re-branding the Project of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Internationalization is achieved using i18N Editor

Step 1: Invoking the I18nEditor Select the node TL1_User. Proceed to the menu Tools > I18nEditor. Step 2: Selecting Entities to be Modified Select EnglishToNative.properties file from <Web NMS Home>/StudioTools/Studio/projects/ TL1_Tutorial/WebNMS/html directory. Right-click on the nodes to be modified and then specify the new entry for it. The details of the change are explained below. Change the value of the following Property Keys <PROMINENT_KEY>AdventNet - AcmeMSU <PROMINENT_KEY>Web NMS - MSU <PROMINENT_KEY>Version x.x - 1.0 <PROMINENT_KEY>WebNMS Version - MSU Release 1.0 <PROMINENT_KEY>Product Name - Acme <PROMINENT_KEY>WebNMS Server modules started...

- Acme MSU Server modules started successfully...

<PROMINENT_KEY>AdventNet Inc - Acme Inc Step 3: Closing the i18N Editor Select File > Save menu item. Select File > Exit menu item.

Re-branding is achieved using the Re-branding tool. The images logopane.png and logo.png in the <Web NMS Home>/images directory represent the AdventNet company and the Web NMS product respectively in the Client. Replace these logos with the Acme logo for Re-branding to take effect.

AdventNet Inc. 82

TL1 Tutorial

Invoking the Rebranding tool

• Select the node TL1_Tutorial. Proceed to the menu Tools > Rebranding Tool. • Click Browse button besides the parameters node and select the appropriate value. • All the attributes of the node with their default values are displayed.

Change the values for the Entries as specified in the table below: Re-branded Entities Entity Name Values Logo Icon acme.png Frame Icon logo.png Splash Image acmemsu.png Progressbar Foreground Color 0-0-255 Progressbar Background Color 255-255-255 Logo URL www.adventnet.com

Configuring clientparameters.conf

Change the value of the following parameters in clientparameters.conf as specified below: This file is available in <Project Home>/WebNMS/conf directory. Open the file in an editor and make the required changes. INIT_PANEL= "TL1-MAP.netmap" MAP_LAYOUT_CLASSES= "com.adventnet.nms.mapui.MSUMapSymbolLayout" Result The AdventNet Web NMS is re-branded as AcmeMSU Manager. The final step toward creating AcmeMSU Manager is to follow in the next chapter - Packaging and Installation.

AdventNet Inc. 83

TL1 Tutorial

5.11 Creating Menus Map Menus You have to create the following Map Menu files for XML Devices.

• cardmenu.xml • crossconnectmenu.xml • provmenu.xml • tl1menu.xml

Create these below mentioned XML files using other files option of the Studio project. For details of Working with other files of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation. Create the files. Add the entries as given in the files from the respective URLs given below and save the newly created files.

• cardmenu.xml • crossconnectmenu.xml • provmenu.xml • tl1menu.xml

AdventNet Inc. 84

TL1 Tutorial

5.12 Packaging the Project This topic explains the process of compiling and packaging the Studio project.

• Compile the Project • Importing Client-side Classes as JAR • Package the Application

Compile the Project

After building the project, save it, and compile it.

• Select the File > Save Project menu from the Studio. • Select the Project > Compile menu from the Studio.

Importing Client-side Classes as JAR

You have to pack the client-side classes of this application into a JAR file. Import the JAR into the Studio Project of this application. Before importing, you have to create the JAR file. To create the JAR file, follow the steps given below:

1. Create a JAR file of the client-side classes to pack the classes into NAR. 2. Using Notepad or Word pad application, create a Shell / Batch file with the contents given

below: cd CLASSES set AUTH_PATH=com/adventnet/nms/tutorials/tl1 set CLIENT_PATH=com/adventnet/nms/mapui %JAVA_HOME%/bin/jar -cvf AcmeExtMapApplet.jar %AUTH_PATH%/AcmeExtMapApplet.class %AUTH_PATH%/CrossConnectUI.class %AUTH_PATH%/CrossConnectUI$1.class %AUTH_PATH%/CrossConnectUtil.class %CLIENT_PATH%/MSUMapSymbolLayout.class %CLIENT_PATH%/MSUMapSymbolRenderer.class >> output.txt

3. Save the file named as createClientJar.bat. 4. Execute the bat/sh file to create the JAR. You can find the AcmeExtMapApplet.jar created

under the <Project Home> directory. For Linux/Solaris system, create the shell file with above content with appropriate modification and create the JAR file.

5. Now invoke the Deployment Wizard. Run the DeploymentWizard.bat/.sh file in the <Web NMS Home>/bin directory.

6. In the Deployment Options, select the Deploy Client Application option. 7. Select the AcmeExtMapApplet.jar with the help of Browse button. 8. Select a deployable class type from the combo box. The class to be selected should of type

NMS Panel. Select AcmeExtMapApplet for deployment. 9. Set the destination directory. Enter NMS Panel Key as MapApplet. 10. Click Next button twice and click Finish button. 11. Now the created JAR is available with name of deployable class name selected, in the

destination directory.

AdventNet Inc. 85

TL1 Tutorial

Import this JAR to Studio Project. The menu needed during the time of deployment will be dummymenu.xml (menu file name), menu name (dummymenu), menu item name (dummy). Select only the panel menu information screen. Package the Application

After compiling the project, package the application into a NAR file. For details of Packaging Studio Applications of AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation.

• Select the Project > Package menu from the Studio. Package Wizard comes up and carry out the packaging in 8 steps.

1. Project and NAR Details - Enter the Nar File Name as TL1_User.nar, Destination Directory, and README File Name and click Next button.

2. Select Services - Select the Services you have configured so far in the project and click Next button.

3. Database Details - Select the database. Enter the database details URL, Driver Name, User Name, Password, Trans-Connection, and Non Trans-Connection and click Next button.

4. Map and List Icons - Select the Map Icon to represent the type of device (switch, printer etc).This project uses pc.png located in <Web NMS Home>images directory to represent a node. Select List Icons to represent severity of the device and click Next button. The icons for this project are selected from <Web NMS Home>icons directory. Note that, if you enable the Transparent option, you can just choose one icon and the severity will be rendered automatically.

5. Other Resources - Select the menus and images needed to bundled in the NAR. In the Resource Path, select the NmsPanels.conf and in the Target Directory enter ./conf. Click Add button. Using the same procedure add Polling.conf file and click Next button.

6. Additional JARs - Add the additional JARs required and click Next button. 7. Client NARs - Add the required Client NARs imported using Import NAR Wizard and click

Next button. 8. Create NAR - In this project, we have selected Complete Packaging so that files pertaining

to all Services are packaged. Select Selective Packaging option to package the files for the selected Services only. This will package the dependent files (conf files, classes, jars etc.) also using certain algorithm. Click Finish.

This will generate a NAR file called TL1_User.nar. You can deploy this NAR directly into Web NMS to install the application. Including Menu Files The files that need to be included for menus are listed below.

File Name Location cardmenu.xml crossconnectmenu.xml provmenu.xml tl1menu.xml

Source Directory : <Web NMS Home>/StudioTools/Studio/projects/TL1_Tutorial/WebNMS/mapdata/menus Destination Directory : <Web NMS Home>/StudioTools/Studio/projects/TL1_User/WebNMS/mapdata/menus

Include the mentioned files in the specified location and then proceed with packaging the project.

AdventNet Inc. 86

TL1 Tutorial

6.0 Fast Track implementation This topic will guide you through shortcut to the tutorial, if you are unable to complete the Tutorial Project. It will also guide you, if you want to try quick modifications in the available project and check the results. Successful completion of Project

After the building of application is complete, compile the project and package it as a NAR file. If you are able to create the NAR successfully then skip this topic. Try your requirements quickly in the Project

If you want to try your requirements in the Studio project on your own efforts, then you can use the Studio project of this application which is bundled in AdventNet Web NMS Studio. The Studio project of the application comes bundled in AdventNet Web NMS Studio in the following URL:

<Web NMS Home>/StudioTools/Studio/projects/TL1_Tutorial.proj In this you have two options:

1. Compiling without modifications. 2. Compiling with modifications.

First option

• Open the Project in AdventNet Web NMS Studio. • Compile the Project. • Package the Project as (You will be using the ready built application

TL1_Tutorial1.1.nar) NAR file. Second Option

• Open the project in AdventNet Web NMS Studio. • Carryout the Studio supported changes in the project. • Compile the Project. • Package the Project as (You will be using the ready built application

TL1_Tutorial1.1.nar) NAR file.

• Using the instructions given in the Installing the application section, deploy the ready built application TL1_Tutorial1.1.nar file.

• Run the Application. • View the Result. If you have modified the Project, test the application for the desired result.

Note: If you find difficulty in opening the Project, in the Project Properties check Web NMS Home in the General tab screen and Class Path of various JAR files in the Compiler tab screen. These will be having the values in which they were developed. Change both the parameters with respect to your Web NMS Installation.

AdventNet Inc. 87

TL1 Tutorial

7.0 Installation and testing 7.1 Installation Notes Installing the Application

To install the tutorial application,

• Stop the Web NMS Server if it is running. • Run the DeploymentWizard.bat/.sh file under <Web NMS HOME>/bin directory and also

ensure that the server is not running. • Select the NarInstall/Uninstall tab. • Select Install button in the screen. • Click Browse button in the NAR INSTALLER pop-up screen. • Select the TL1_User.nar available in the <Web NMS HOME>/tutorials/tl1_tutorial/ems

directory from the File Chooser pop-up screen and click the Select button. • Click OK button in the NAR INSTALLER pop-up screen. The NmsPwsNarInstaller screen

will pop up. • Select the Application Database (in which you want to run the tutorial) listed from the combo

box. • Click Next button. • In this screen, click Install button. • This will install and show the status in the progress bar. See that the progress is 100%. • Click Close button. • Now the installation is complete. The entries TL1_Tutorial1.0.nar and AcmeExtMapApplet will

be found. • Click Exit button to quit the Deployment Wizard. • Reinitialize Web NMS using reinitialize_nms.bat/.sh. Reinitialize Web NMS Database option

dialog pops up. Select Yes option in the option dialog for reinitializing Web NMS and click OK in the confirmation dialog.

Caution: This tutorial will function only if Web NMS is reinitialized. Therefore, after installing the tutorial, reinitialize Web NMS. Ensure you use separate Web NMS installation for tutorial application development and installation. Do not experiment on Web NMS deployed in real world.

When this tutorial application is installed, the existing files which require changes, from the installed Web NMS are backed up. However, when you uninstall this tutorial application, the files modified will be restored from the backup. Uninstalling the Application

To uninstall the tutorial application,

• Run the DeploymentWizard.bat/.sh file under <Web NMS HOME>/bin directory. • Select the NarInstall/Uninstall tab.

In the Uninstall section, • Select the TL1_Tutorial entry • Click Uninstall button in the screen. • On clicking Uninstall button, NmsPwsNarUninstaller screen will pop up. • In that, click Uninstall button. • This will uninstall and show the status in the progress bar. See that the progress is 100%. • Click Close button. • Now the uninstallation is complete. • Click Exit button to quit the Deployment Wizard.

AdventNet Inc. 88

TL1 Tutorial

Modifying the Application

If you want to modify the application and try out other features, you can edit the Studio project of this application bundled with this tutorial. You can open the project <Web NMS Home>/StudioTools/Studio/projects/TL1_User.proj in the AdventNet Web NMS Studio. Make the changes (supported by the AdventNet Web NMS Studio) to the project as per your requirement. Compile the project and package it into NAR. Now, uninstall the existing installed NAR and install the new NAR generated with your changes.

Caution: Uninstalling the original NAR is mandatory as only one Studio NAR is permitted to be deployed in AdventNet Web NMS.

For complete details of Working with AdventNet Web NMS Studio, refer to the AdventNet Web NMS Studio documentation.

Note: To install the NAR for the Application that you have created, you must select TL1_User1.0.nar.

Note: After installing the NAR, in the AcmeCrossConnect.xml and ChangeCardType.xml present under <Web NMS Home>/provisioningtemplates following tag should be added before the <Template> tag. <!DOCTYPE Template SYSTEM "Template.dtd"> The above will enable you to work with the provisioning in the TL1 application.

AdventNet Inc. 89

TL1 Tutorial

7.2 Testing the Application After installing TL1_User project NAR in Web NMS, set the testing environment as mentioned below. Once discovery process completes, you will be able to see the ACME MSU device discovered under the TL1 Panels Map of Client. Setting Up Environment for Testing Please follow the listed steps in order to test this application. Running the Simulator

• Starting simulator with single Agent To start the simulator, open a command line window. Change directory to <Web NMS Home>/StudioTools/ClientBuilder/bin. Run the startCmdTL1Agent.bat/sh file -c "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/Agents/Acme-MSU/Acme-MSU.prp" as argument. Give absolute path of the prp file in the argument. The Agent will run in the default Port 8000. The command will like the one as given below: startCmdTL1Agent.bat -c "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/Agents/Acme-MSU/Acme-MSU.prp"

• Starting simulator with multiple Agents To start the simulator, open a command line window. Change directory to <Web NMS Home>/StudioTools/ClientBuilder/bin. Run the startCmdTL1GNE.bat/sh file -m "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/MultipleAgent1.txt" -p 9091 as arguments. Give absolute path of the txt file in the argument. The command for the multiple agents in port 9091 will like the one as given below: startCmdTL1GNE.bat -m "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/MultipleAgent1.txt" -p 9091

To start the Agents in multiple ports, run the above command in two more separate command line windows. Configure the configuration files of the devices according to your requirement in the MultipleAgent1.txt, MultipleAgent2.txt, and MultipleAgent3.txt file in the <Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator directory. Configure the configuration files of Device1 to Device4 in the MultipleAgent1.txt, Device5 and Device6 in the MultipleAgent2.txt, and Device7 and Device8 in the MultipleAgent3.txt Target IDs.

The command for the multiple agents in port 9092 will like the one as given below:

startCmdTL1GNE.bat -m "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/MultipleAgent2.txt" -p 9092

The command for the multiple agents in port 9093 will like the one as given below:

startCmdTL1GNE.bat -m "<Web NMS Home>/tutorials/tl1_tutorial/AdventNetTL1Simulator/MultipleAgent3.txt" -p 9093

AdventNet Inc. 90

TL1 Tutorial

Sending Autonomous Messages

• To test the autonomous messages from the agent, right-click the TL1Node under TL1-Panels.

• From the Acme-MSU menu item, select ALM Card or ALM Port. This would send an Input Message based Autonomous Message.

• A UI will appear with the response from the agent. Configure the tl1seed.file

• Use the Discovery Configurator tool to configure the tl1seed.file. • Invoke the tool by running the DiscoveryConfigurator.bat file present in the <Web NMS

Home>/bin directory. Select the tl1seed.file. • Enter the IP Address and Port of the Agent. For using the Discovery Configurator tool, refer

to the Configuring Discovery of TL1 Devices in Administrator Guide. For Terminal Server support, refer to the example_tl1seed.file and configure the tl1seed.file as explained in the examples of example_tl1seed.file.

Alternate Configuration of tl1seed.file

Configuration of tl1seed.file for single TL1 device • Copy the following into the tl1seed.file.

<TO_DISCOVERIP tl1port="10000" type="TL1Node" dictionary="default.xml" connectionHandler="com.adventnet.nms.topodb.tl1. TL1BlankConnHandler" MessageRationalizer="com.adventnet.nms.tutorials.tl1. MessageRationalizerImpl" > <GROUP deviceGroupName="Acme-MSU" tl1port="8000" type="acme_msu_node"> <loginCommand command="ACT-USER::ROOT:::PUBLIC;"/> <initCommand command="RTRV-IP::ETHER:;" response="IntfCard=IPTYPE,Gateway=GATEWAY, GatewayIP=IP,GatewayMask=MASK,BroadcastIP=BRDCAST,MTU=MTU, MacAddr=MacAddr"/> <statpollCommand command="RTRV-IP::ETHER:;"/> <IP ipaddress="192.168.9.42" tl1port="8000"> </IP> </GROUP> </TO_DISCOVERIP>

• Before the </TL1DISCOVERY> tag. • In the IP tag, modify the ipaddress values as the IP Address of the machines and the

tl1port values as Ports in which the TL1 Agents are running.

AdventNet Inc. 91

TL1 Tutorial

Configuration of tl1seed.file for multiple TL1 devices in multiple ports • Copy the following into the tl1seed.file.

<TO_DISCOVERIP tl1port="9091" type="TL1Node" dictionary="default.xml" connectionHandler= "com.adventnet.nms.topodb.tl1. TL1BlankConnHandler" MessageRationalizer="com.adventnet.nms.tutorials. tl1.MessageRationalizerImpl" > <GROUP deviceGroupName="CHUNGHWA" tl1port="9091" type= "acme_msu_node"> <loginCommand command="ACT-USER::ROOT:::PUBLIC;"/> <initCommand command="RTRV-IP::ETHER:;" response= "IntfCard=IPTYPE,Gateway=GATEWAY,GatewayIP=IP, GatewayMask=MASK, BroadcastIP=BRDCAST,MTU=MTU,MacAddr=MacAddr" /> <statpollCommand command="RTRV-IP::ETHER:;"/> <GNE ipaddress="192.168.4.103" tl1port="9091"> <GATEWAY_PROP dictionary="default.xml" connectionHandler= "com.adventnet.nms.topodb. tl1.TL1BlankConnHandler" MessageRationalizer= "com.adventnet.nms.tutorials. tl1.MessageRationalizerImpl"> <loginCommand command="ACT-USER::ROOT:::PUBLIC;"/> <initCommand command="RTRV-IP::ETHER:;" response= "IntfCard=IPTYPE,Gateway=GATEWAY, GatewayIP=IP,GatewayMask=MASK, BroadcastIP=BRDCAST, MTU=MTU,MacAddr=MacAddr" /> <statpollCommand command="RTRV-IP::ETHER:;"/> </GATEWAY_PROP> <TID tid= "Device1"> <loginCommand command="ACT-USER:DEVICE1:ROOT:::PUBLIC;"/> </TID> <TID tid="Device2"> <loginCommand command="ACT-USER:DEVICE2:ROOT:::PUBLIC;"/> </TID> <TID tid="Device3"> <loginCommand command="ACT-USER:DEVICE3:ROOT:::PUBLIC;"/> </TID> <TID tid="Device4"> <loginCommand command="ACT-USER:DEVICE4:ROOT:::PUBLIC;"/> </TID> </GNE> <GNE ipaddress="192.168.4.103" tl1port="9092"> <GATEWAY_PROP dictionary="default.xml" connectionHandler= "com.adventnet.nms.topodb.tl1.TL1BlankConnHandler" MessageRationalizer="com.adventnet.nms.tutorials. tl1.MessageRationalizerImpl"> <loginCommand

AdventNet Inc. 92

TL1 Tutorial

command="ACT-USER::ROOT:::PUBLIC;"/> <initCommand command="RTRV-IP::ETHER:;" response= "IntfCard=IPTYPE,Gateway=GATEWAY, GatewayIP=IP,GatewayMask=MASK, BroadcastIP=BRDCAST,MTU=MTU, MacAddr=MacAddr" /> <statpollCommand command="RTRV-IP::ETHER:;"/> </GATEWAY_PROP> <TID tid= "Device5"> <loginCommand command="ACT-USER:DEVICE5:ROOT:::PUBLIC;"/> </TID> <TID tid="Device6"> <loginCommand command="ACT-USER:DEVICE6:ROOT:::PUBLIC;"/> </TID> </GNE> <GNE ipaddress="192.168.4.103" tl1port="9093"> <GATEWAY_PROP dictionary="default.xml" connectionHandler= "com.adventnet.nms.topodb. tl1.TL1BlankConnHandler" MessageRationalizer="com.adventnet.nms.tutorials. tl1.MessageRationalizerImpl"> <loginCommand command="ACT-USER::ROOT:::PUBLIC;"/> <initCommand command="RTRV-IP::ETHER:;" response= "IntfCard=IPTYPE,Gateway=GATEWAY,GatewayIP=IP,GatewayMask=MASK, BroadcastIP=BRDCAST,MTU=MTU,MacAddr=MacAddr" /> <statpollCommand command="RTRV-IP::ETHER:;"/> </GATEWAY_PROP> <TID tid= "Device7"> <loginCommand command="ACT-USER:DEVICE7:ROOT:::PUBLIC;"/> </TID> <TID tid="Device8"> <loginCommand command="ACT-USER:DEVICE8:ROOT:::PUBLIC;"/> </TID> </GNE> </GROUP> </TO_DISCOVERIP>

• Before the tag </TL1DISCOVERY>. • In the IP tag, modify the ipaddress values as the IP Address of the machines and the

tl1port values as Ports in which the TL1 Agents are running.

• Leave the rest of the values as it is. • Save the tl1seed.file.

This tutorial discovers all the TL1 Devices configured in the tl1seed.file and also discovers the various cards and slots installed in those devices. If the machines in which the TL1 Simulated Agent and Web NMS are running, are in different networks, then configure the seed.file as given below.

AdventNet Inc. 93

TL1 Tutorial

Configure the seed.file

• Use the Discovery Configurator tool to configure SNMP devices in the seed.file. • Invoke the tool by running the DiscoveryConfigurator.bat/sh file present in the

<Web NMS Home>/bin directory. Select the SNMP Devices. • Enter the IP Address and Port of the Agent. For using the Discovery Configurator

tool, refer to the Configuring Discovery of SNMP Devices topic in Administrator Guide.

Alternate Configuration of seed.file.

• Copy the following into the seed.file. <TO_DISCOVERIP> <ip NODE_ID="192.168.9.50" NETMASK="255.255.255.0"/> <ip NODE_ID="192.168.9.14" NETMASK="255.255.255.0"/> </TO_DISCOVERIP>

• Before the </SEED> tag. • Modify the NODE_ID values as the IP Address of the machines in which the TL1

Agents are running and set the NETMASK values accordingly. • Leave the rest of the values as it is. • Save the seed.file.

Testing Output in Web NMS Start NMS

• Before starting the Web NMS server, you have to set the agent. Refer to Setting up

Environment for Testing for details. • Reinitialize and start the Web NMS Server. • Start the NMS Toolkit, by invoking startNmsToolkit.bat/.sh file in the <Web NMS HOME>

directory. • Click Start NMS Server icon in the NMS Toolkit.

Viewing the result

• Once the server is up and running, start the Java client by executing the startApplicationClient.bat/sh. OR

• Connect a Browser or Application client to the NMS Server in port 9090.

• Log in root against user and public against password.

• The splash screen that comes up with the progress bar at the bottom will now show ACME MSU Manager instead of the default splash screen.

• In the left-side frame, you will see the map tree. Select TL1-Panels node from the tree. • Check whether ACME MSU Node discovered has been displayed under the TL-Map and TL1-

Topo-Map tree node. You can also use the HTML client for this application.

Displaying ACME MSU Devices in a separate Map The TL1-Map / TL1-Topo-Map is a default map in which the ACME MSU Devices will be displayed. The following image is a snapshot taken from the application, which shows the TL1-Map, where all the ACME MSU devices are laid out in the map. Right-click the ACME MSU device nodes and select View Chassis. You can see the Chassis view of the individual ACME MSU device.

AdventNet Inc. 94

TL1 Tutorial

Chassis View of ACME MSU Device The Chassis view of ACME MSU device shows the various components of a ACME MSU device. The screen shot for the same is given below. The chassis view shows a shelf with eleven slots. Each slot has a card associated with it. You can find three types of cards, viz., CPU Card, ST1 CSU Card, and ST1 DSX Card. Each card contains a status icon and one port and CPU Card has no port.

Autonomous Messages from the ACME MSU Device Send Autonomous Messages from the ACME MSU Agent Simulator, using the Acme-MSU menu item, select ALM Card or ALM Port. This would send an Input Message based Autonomous Message. A UI will appear with the response from the agent. Select the TL1-Events node under Fault Management node in the tree. You can find events displayed in the right-side frame.

Configuring ACME MSU Device Parameters through Provisioning Templates Change Card Type The configuration application is used to configure ACME MSU device Cards. Right-click on a Card in the ACME MSU device node in map and select Change Card Type. Following screen pops up. You can change the PRIORITY and PST (Primary Status) of the card and see the effect in the Card MO Properties.

AdventNet Inc. 95

TL1 Tutorial

Cross Connect The configuration application is used to configure a Port of ACME MSU device. Right-click on a Port of a Card in the ACME MSU device node in map and select Cross Connect. Following screen pops up. You can connect one of the first five Channels in the Source to one of the first five Channels in the Destination and the effect cannot be noticed visibly anywhere.

AdventNet Inc. 96

TL1 Tutorial

8.0 Known Issues When this application is installed, it replaces some of the existing conf files with the new ones needed for this tutorial. If the user has made any changes in the already existing filters, then the changes will not take effect during the tutorial session. Though all the original conf files will be restored once the tutorial is uninstalled. For the cross connect example currently the cross connection can be established between the first five channels of a port only. The user has to configure the TL1Simulator by editing the Acme-MSU_inputcode.xml file and also slightly modify the AcmeMSUDiscFilter.java for establishing more cross connections.

AdventNet Inc. 97

TL1 Tutorial

9.0 Trouble Shooting Tips

Problem Reason Solution

In the individual Switch Map, the components overlap one another

The Layout for the map has not been set properly.

Check whether the specified layout is present in the clientparameters.conffile under <Web NMS HOME>/conf directory.

No chassis view in the client.

The response for the command sent might be timed out. This may happen if the ManagementServer does not respond to the command sent.

Reinitialize and start the server again.

NAR may not have been installed. Install the TL1_Tutorial1.0.nar TL1 Agent may not be running. Start the TL1 Agent Simulator.

In the application, the device is not discovered as TL1 Device The seed.file and tl1seed.file may

not have been configured. Configure the seed.file and tl1seed.file with proper entries.

The entries in the seed.file may not be retained after starting the server.

Ensure that the entries in the seed.file are retained after starting the server. Event after carrying out the

above procedure, the device is not discovered as TL1 Device The entries in tl1seed.file may be

incomplete or improper.

Ensure none of the entries in tl1seed.file is incomplete or improper. Improper or incomplete entries will stop the discovery process.

When the Web NMS Server is started, the entries that were made in the seed.file are not retained.

When the Web NMS Server is started, improper or incomplete entries in the seed.file will be deleted.

Ensure the entries in seed.file are complete and proper.

The TL1-Panels exist in the tree even after un-installing the TL1_Tutorial1.0.nar.

The entries that are made in the seed.file and tl1seed.file after the NAR installation are retained even after un-installing the NAR.

Ensure that the entries that are made in the seed.file and tl1seed.file after the NAR installation are removed after un-installing the NAR.

After un-installing the TL1_Tutorial1.0.nar, the entries in the seed.file and tl1seed.file are not restored with pre-installation values.

- Manually restore the entries in the seed.file and tl1seed.file to the pre-installation values.

The Terminal Agent may not be running.

Start the Terminal Agent, if it is not running.

The entries for two Terminal Agents may not be there in the tl1seed.file

Make the entries for two Terminal Agents in the tl1seed.file Started two Terminal

Agents, but only one is getting discovered.

The device entries may not be there for two Agents in MultipleAgent.xml file.

Make the device entries for two Agents in MultipleAgent.xml file. Ensure that the tl1seed.file and MultipleAgent.xml file entries are matching.

Event after carrying out the above procedure, the discovery of two Terminal Agents takes too long time.

Disabling Local Net discovery and adding entries in the seed.file will speed up the discovery of intended Terminal Agents.

In the seed.file, select the attribute DISCOVERY_LOCALNET and set value as false. Make the entries for two Terminal Agents in the seed.file

AdventNet Inc. 98

TL1 Tutorial

Cross Connection could not be established.

Out of 20 Channels listed as Source and Destination Channels, only the first five can be configured. Giving a Connection Name is Mandatory.

Ensure you select the first five channels in the Source and Destination Channels options. Also ensure that you give a Connection Name.

It takes a long time for the major alarms to be generated when a GAS Object is disconnected.

- After selecting Disconnect Device Ring menu, click Update Status menu for faster alarm generation.

In the Chassis View, the colour of the LEDs of the Card is not getting changed.

- Ensure that the Device is not in Unmanaged State.

AdventNet Inc. 99

TL1 Tutorial

10.0 Description of Custom Code and Class Files 10.1 Description of Discovery Filter Custom Code 10.1.1 Customizing the Discovery Filter Code In this section, you can look at how to customize discovery to discover TL1 elements of a network device. You proceed with the example you have modeled earlier and show how to extend the discovery and populate the database with the network elements you have modeled. AcmeMSU Discovery Filter

The discovery filter AcmeMSUDiscFilter class, which will try to identify the list of slots, cards, ports, and channels present in the device. The filter sends a syncSend request to the device requesting for the inventory details from the device. This will help us in identifying the list of slots present in the device. Object invObj=null; Object eqptObj=null; The result Object here is expected to be a TL1ResponseMessage object. If the object is null, then it means that there has been some problem while communicating to the device for requesting the inventory. So in that case we do return the object as we obtained. tl1type = managedObject.getUserProperty("tl1type"); invObj = TL1SwitchUtil.syncSendCommand((TL1Node)managedObject, "RTRV-INVENTORY", ""); if(invObj == null) { return managedObject; } Once the result object from the inventory command is obtained, the filter will send a syncSend request to the device for the equipment details. The equipment details give the total number of cards in the device and its health. eqptObj= TL1SwitchUtil.syncSendCommand((TL1Node)obj, "RTRV-EQPT", "ALL"); A check is made if the result object is an instance of TL1ResponceMessage. If true and if the text block of the resultObject is not null the createTL1Node() method is called where a switch object is created. The object is added to the database in the addObject method. 0 Also the getPropVector method is called with the TL1Responce message as the argument. In this method, the response message is parsed and each of the TL1Line is converted into properties by using the static utility method convertLineToProperties of TL1SwitchUtil. These properties are stored in a vector and the vector is returned. Vector invPropVector,eqptPropVector=null; AcmeMSUNode device=null; if(invObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply=(TL1ResponseMessage)invObj; if(reply==null || reply.getTextBlock()==null) { return null; } device=createTL1Node(managedObject); addObject(device);

AdventNet Inc. 100

TL1 Tutorial

invPropVector = getPropVector(reply); } else { System.out.println("SOME Other object obt: " + invObj.getClass().getName() + " VALUE: " + invObj); return null; } Creating Custom Map and associating it with the Switch are dealt in later topics. The createShelf method, with the switch object as the parameter, will be called to create Shelf Object, after creating a switch object and associating it with a map. In this method the name and serialno of the shelf is set and to obtain the container relationship, the switch object is associated as the parent key. AcmeMSUShelf shelf=createShelf(device); addObject(shelf); if(eqptObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply=(TL1ResponseMessage)eqptObj; if(reply!=null && reply.getTextBlock()!=null) { eqptPropVector=getPropVector(reply); } } After adding the shelf, the property vector is obtained for the RTRV-EQPT result object similar to the inventory result object, i.e. by calling the getPropVector method. eqptPropVector=getPropVector(reply); The other components such as slots, cards, ports and channels are created by calling the addSlots, addCard, addPort, and the addChannel method. The following chapters describe these methods in detail. The filter creates AcmeMSUNode object based on the properties of the TL1Node discovered. For example, TL1Line could be "ST1-1::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" The following lines of code convert the response message to a property vector. The codes appearing hereafter are appended after the //<End_filterObject_ManagedObject_TopoAPI> tag in the file. private Vector getPropVector(TL1ResponseMessage resp) { Vector slotNames = resp.getTextBlock().getTL1LineList(); Vector inventory=new Vector(); for(int i = 0; i < slotNames.size(); i++) { TL1Line currLine = (TL1Line)slotNames.elementAt(i); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); if ((prop == null) || (prop.size() == 0)) continue; inventory.add(i,prop); } return inventory; }

AdventNet Inc. 101

TL1 Tutorial

10.1.2 Adding Device Components - Part1 After obtaining the equipment property vector, a check is made if the invPropVector and eqptPropVector are not null. This check is made because if the response for the RTRV-EQPT is null, then we add empty slots corresponding to the details obtained from the RTRV-INVENTORY command. if(invPropVector!=null&& eqptPropVector!=null) { for(int i=0;i<invPropVector.size();i++) { Properties prop = (Properties)invPropVector.elementAt(i); addSlots(i+1,device,shelf,prop,eqptPropVector); } } else { for(int i=0;i<invPropVector.size();i++) { Properties invProp=(Properties)invPropVector.elementAt(i); addEmptySlots(shelf,invProp,i+1); } } managedObject=null; In order to add the slots, the filter traverse the invPropVector and for each of the properties the filter calls the addSlots method. The arguments for the addSlots method being the slotNo, tl1switch, shelf, prop, and eqptPropVector. This method sets the name, the state (empty/Access), the display name and the parent key. The parent key for slot is assigned as shelf. The slot object is added to the database by calling the addObject method. After adding the slot object, the filter obtains the card for this particular slot. This is done because there are certain restrictions in the TL1 Device like the first slot is meant for CPU card only. Also this is helpful for leaving the slots empty when there is no response for the card in the RTRV-EQPT command. Once the filter has the card name, the filter traverses the eqptVector in order to look for the particular card. Then the filter calls the addCard method with the slot, device(TL1Switch), eqptProp, and the invProp as the parameters. private void addSlots(int slotNo,AcmeMSUNode device,AcmeMSUShelf shelf, Properties invProp,Vector eqptPropVector) { AcmeMSUSlot slot = new AcmeMSUSlot(); slot.setName(shelf.getName()+"_"+invProp.getProperty("SLOTNAME")); slot.setSlotno(slotNo); slot.setSlotName(slotName); slot.setState("Empty"); slot.setDisplayName(invProp.getProperty("SLOTNAME")); slot.setParentKey(shelf.getName()); addObject(slot); String slotName=invProp.getProperty("SLOTNAME"); String name=""; if(slotName.equalsIgnoreCase("SLT-1")) name="CPU-1"; else { String numStr = slotName.substring(slotName.indexOf("-")+1); int num = Integer.parseInt(numStr); name = "ST1-"+String.valueOf(num-1); } for(int i=0;i<eqptPropVector.size();i++)

AdventNet Inc. 102

TL1 Tutorial

{ Properties eqptProp = (Properties)eqptPropVector.elementAt(i); String cardName = eqptProp.getProperty("field0:0"); if(cardName.equalsIgnoreCase(name)) { addCard(slot,device,eqptProp,invProp); break; } } } The addCard method sets different parameters for the card. Each attribute of the invProp(CRDTYPE, MFDAT, CRDSN, etc.) is set as a card parameter. There is a special parameter ST1Type for the card because the ST1 card can be of two types, i.e., DSX or CSU. Since the card object has been added, the filter sets the state for the slot as Access. As the CPU card does not contain any port, there is a boolean variable bool for making this check. In order to show the status of the card, there is a check for the PST attribute in the eqptProp. The severityForCardStatus method is called which returns the corresponding severity integer of the PST attribute. When the value of the PST attribute is either OOSMT or RESET the card is unmanaged. For all other values, the corresponding severity is set. Once all the parameters have been set, the card object is added to the database by calling the addObject method. Other than the CPU card for all the other cards, the addPort method is called, with the device (TL1Switch) and card as the input parameters. public static void addCard(AcmeMSUSlot slot,AcmeMSUNode device, Properties eqptProp, Properties invProp,TopoAPI api) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException { boolean bool=true; if(eqptProp.getProperty("field0:0").startsWith("CPU")) { bool=false; } AcmeMSUCard card = new AcmeMSUCard(); String cardName = eqptProp.getProperty("field0:0"); card.setName(slot.getName()+"_"+cardName); card.setDisplayName(cardName); card.setDeviceName(device.getName()); card.setType("acme_msu_card_"+invProp.getProperty("CRDTYPE"). toLowerCase()); card.setCRDSN(invProp.getProperty("CRDSN")); card.setMFDAT(invProp.getProperty("MFDAT")); card.setProdNo(invProp.getProperty("PRODNO")); card.setCRDREV(invProp.getProperty("CRDREV")); card.setPriority(eqptProp.getProperty("PRIORITY")); card.setCardName(cardName); if((tl1type != null) && (tl1type.equals("tl1node_gne"))) { card.setUserProperty("tl1cardtype", "tl1card_gne"); } if(invProp.getProperty("CRDTYPE").equalsIgnoreCase("ST1")) { card.setST1Type(eqptProp.getProperty("TYPE")); } else { card.setST1Type("N/A"); }

AdventNet Inc. 103

TL1 Tutorial

card.setParentKey(slot.getName()); addObject(card); String[] cardChild = {card.getName()}; slot.addChildrenKeys(cardChild); slot.setState("Access"); try { api.lock(slot,LockableObject.WRITE_LOCK,2); api.updateObject(slot,true,true); } catch (com.adventnet.management.transaction.UserTransactionException ute) { System.err.println("Exception while updating the object : " +slot.getName()+"\n"+ ute); ute.printStackTrace(); throw ute; } catch (com.adventnet.nms.store.NmsStorageException nse) { System.err.println("Exception while updating the object : " + slot.getName()+"\n"+nse); nse.printStackTrace(); throw nse; } catch (RemoteException re) { System.err.println("Exception while updating the object : " + slot.getName()+"\n"+re); re.printStackTrace(); } catch (com.adventnet.nms.util.AccessDeniedException ade) { System.err.println("Exception while updating the object : " + slot.getName()+"\n"+ade); ade.printStackTrace(); } catch(Exception e) { System.err.println("Error while updating object " +slot); e.printStackTrace(); } if(bool)//This check is made since there is no port for CPU card { addPort(device,card,api); } } In the addPort method, the name, displayName, portNo, portName, deviceName, and the parent key for the port object are set. In this tutorial application, it is assumed that there is only one port per card. The addObject method adds the port object to the database. For each port, the filter will add Channels by calling the addChannel method. private void addPort(AcmeMSUNode device , AcmeMSUCard card) { AcmeMSUPort port = new AcmeMSUPort(); int portNo = 1;//Currently only one port is assumed per card. port.setName(card.getName()+"-"+portNo);

AdventNet Inc. 104

TL1 Tutorial

port.setDisplayName(card.getDisplayName()+"-"+portNo); port.setPortNo(portNo); port.setPortName(card.getDisplayName()+"-"+portNo); port.setDeviceName(device.getName()); port.setParentKey(card.getName()); addObject(port); if(tl1type != null && tl1type.equals("tl1node_gne")) { port.setUserProperty("tl1porttype", "tl1port_gne"); } for(int i=0;i<5;i++) { addChannel(i+1,port,device); } } In the addChannel method, the name, channel number, and the parentKey are set for the Channel and added to the database. private static void addChannel(int chNo , AcmeMSUPort port, AcmeMSUNode device) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException { Channel channel = new Channel(); String channelName = port.getPortName()+"-"+chNo; channel.setName(device.getName()+channelName); channel.setDisplayName(channelName); String portName=port.getName(); channel.setChannelNumber(chNo); channel.setParentKey(portName); addObject(channel); }

AdventNet Inc. 105

TL1 Tutorial

10.1.3 Adding Device Components - Part2 The Managed Object is added to the database and this method is database transaction compliant. This will catch the exceptions occurring while adding the Managed Object to the database. private static void addObject(ManagedObject obj) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException { try { TopoAPI api = (TopoAPI)NmsUtil.getAPI("TopoAPI"); api.addObject(obj); } catch (com.adventnet.management.transaction.UserTransactionException ute) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+ute); ute.printStackTrace(); throw ute; } catch (com.adventnet.nms.store.NmsStorageException nse) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+nse); nse.printStackTrace(); throw nse; } catch (RemoteException re) { System.err.println("Exception while adding the object " + obj.getName()+"\n"+re); re.printStackTrace(); } catch(Exception exp) { exp.printStackTrace(); } } private void addEmptySlots(AcmeMSUShelf shelf,Properties invProp,int slotNo) throws com.adventnet.nms.store.NmsStorageException,com.adventnet.management. transaction.UserTransactionException { String shelfName = shelf.getName(); AcmeMSUSlot slot = new AcmeMSUSlot(); slot.setName(shelfName+"_"+invProp.getProperty("SLOTNAME")); slot.setSlotno(slotNo); slot.setState("Empty"); slot.setDisplayName(invProp.getProperty("SLOTNAME")); slot.setParentKey(shelf.getName()); addObject(slot); }

AdventNet Inc. 106

TL1 Tutorial

private AcmeMSUNode createTL1Node(ManagedObject obj) { AcmeMSUNode device = new AcmeMSUNode(); device.setName(obj.getName()); device.setLocation("California"); device.setContact("SysAdmin"); device.setProperties(obj.getProperties()); return device; } private AcmeMSUShelf createShelf(AcmeMSUNode device) { AcmeMSUShelf shelf=new AcmeMSUShelf(); shelf.setName(device.getName()+"_Shelf1"); shelf.setParentKey(device.getName()); shelf.setSerialno(device.getName()+"Bank1"); return shelf; }

AdventNet Inc. 107

TL1 Tutorial

10.2 Description of Map related files 10.2.1 Description of AcmeMSU Device Map Layout Class In setting up the custom Chassis map to represent the AsmeMSUNode, you will be using a custom layout. This layout supports the placement of shelf, slots, cards, and ports on the map for the switch. Since the simple layouts such as grid, ring, etc. are insufficient for this purpose, you will implement a new layout class and plug it into the Web NMS maps. Also this layout relies on the map container hierarchy, which you have implemented in the map filter MSUMapFilter, for laying out the switch components. You have associated different layouts for the shelf, slots, cards, and ports based on the objTypes that are set in the mapIcon.data file. The doLayout method accepts mapSymbol vector, the width and height of the MapContainerComponent and the objType as the input parameters. Any custom layout should implement the AutoLayout interface and overwrite the layoutMap method. The basic idea behind this layout is to get the mapContainer width and height, i.e., vw and vh. Then get the total number of symbols that will be appearing on this mapContainer, i.e., calculate the size of the symbols vector. Once you have the total width of the container and the number of components in that container, you can easily calculate the size of each component. Once the individual component size is obtained, assign this size to the MapSymbolComponent. One thing that is to be kept in mind is that, since the parent-child containment relationship is set for the device component containers, the size of MapContainerComponent will keep differing, i.e., when you lay out the slots, the MapContainerComponent will be the shelf and for cards it will be the slot. So, while laying out the slots, the width and height of the MapContainerComponent would be the size of the shelf. To leave some gap on the sides, a constant is added to the number of symbols.

public void layoutMap(MapContainerComponent model, int depth) { Vector symbols = (Vector) model.getSymbols(); int numSymbols = symbols.size(); int vw = model.getWidth(); int vh = model.getHeight(); if ((numSymbols <= 0)||(vw <= 0)||(vh <= 0)) return; MapSymbolComponent symb = (MapSymbolComponent) symbols.elementAt(0); int type = symb.getObjType(); doLayout(symbols,vw, vh,type); } private void doLayout(Vector symbols,int vw,int vh,int type) { int num = symbols.size(); if(type==400) // Layout for shelf { for (int i=0;i<num;i++) { MapSymbolComponent obj = (MapSymbolComponent) symbols.elementAt(i); obj.dim.width=vw; obj.dim.height=vh; obj.p=new Point(0,0); }

AdventNet Inc. 108

TL1 Tutorial

} if(type==100) { //The idea behind dividing by +.5 is to divide leave some gap on the left //and right side of the shelf, spanning 1 card width. int slotWidth=(int)(vw/(num+0.5)); int slotHeight=vh*2/3; int partWidth = 0; //Denotes the partition width int leftGap = (vw-((num*slotWidth)+((num-1)*partWidth)))/2; for(int i=0;i<num;i++) { MapSymbolComponent obj=(MapSymbolComponent)symbols.elementAt(i); obj.dim.width = slotWidth; obj.dim.height = slotHeight; obj.p = new Point((leftGap+i*(obj.dim.width+partWidth)),((vh-obj.dim.height)/2)); } } if(type==200) { if(num!=1) { System.out.println(" Number of cards not equal to 1"); } else { for(int i=0;i<num;i++) { MapSymbolComponent obj = (MapSymbolComponent) symbols.elementAt(i); String st1Type = obj.getUserProperty("st1type"); if(st1Type.equalsIgnoreCase("DSX")) { obj.setIconName("clkio.png"); } if(st1Type.equalsIgnoreCase("CSU")) { obj.setIconName("teio.png"); } obj.dim.width = vw; obj.dim.height = vh; obj.p = new Point(0,0); } } } if(type==300) { int cardWidth = vw*5/6; //The idea behind dividing by +2 is to divide leave some gap on the left //and right side of the shelf, spanning 1 card width. int cardHeight = (int)vh/(20); // The LED is exepected to be 1/20 of the card height. if(cardHeight < cardWidth) {

AdventNet Inc. 109

TL1 Tutorial

cardHeight = cardWidth*2/3; } else { cardWidth = cardHeight; } for (int i=0;i<num;i++) { MapSymbolComponent obj = (MapSymbolComponent) symbols.elementAt(i); if (obj.getObjType() == 0) continue; obj.setWidth(cardWidth); obj.setHeight(cardHeight); obj.setX(vw/2 - obj.getWidth()/2); obj.setY((int)(obj.getHeight()*2.5)); } } }

In the getName method, the class returns a string that specifies the name of this layout.

public String getName() { return "tl1_components"; }

AdventNet Inc. 110

TL1 Tutorial

10.2.2 Description of AcmeMSU Device Map Symbol Renderer Class Once you have written the layout for the application, the next step is to write a renderer. A renderer as its name suggests renders the layout, i.e., associates certain label string for each component, marking the component when the user selects a particular component, and painting the component with different colors. This renderer extends the MapSymbolRendererImpl class and overrides the paintIcon, paintShapeAndSeverity, and paintLabelString methods. The paintIcon method paints four dark squares at each corner of the component to show that the component is selected. The following lines show the code for achieving this. if (selected) { g.setColor(Color.black); int orgsize = d.height; if(d.width < orgsize) { orgsize = d.width; } int markHt = orgsize/5; if (markHt < 5) markHt = 5; g.fillRect(p.x-markHt, p.y-markHt, markHt,markHt); g.fillRect(p.x+d.width, p.y-markHt, markHt,markHt); g.fillRect(p.x-markHt, p.y+d.height, markHt,markHt); g.fillRect(p.x+d.width, p.y+d.height, markHt,markHt); } The paintShapeAndSeverity method associates an icon for the shelf and also paints the background of the cards and ports to show their status. The cards and ports are differentiated based on their objTypes which are set in the mapIcon.data file. Since the NMS automatically paints the background of the components based on their status, use this color (the bg parameter of this method) to set the color of the component. For showing the LEDs for port and card keep the LED portion in the card image and the port image as transparent. This is a unique feature of the Application. When painting the background, the corresponding color becomes automatically visible. Sample code for the card is shown below. Similar approach is taken for the port. else if (type == 200) // If it is a card { g.setColor(bg); g.fillRect(p.x,p.y,d.width,d.height); } The paintLabelString method calls the super class paintLabelString method to associate a label for each component except the shelf and the port. if(type==200) { font = new Font (s0,Font.BOLD|Font.PLAIN,mapSymbol.getWidth()/5); g.setFont(font); super.paintLabelString(g, mapSymbol, s0, p, font); }

AdventNet Inc. 111

TL1 Tutorial

10.2.3 Description of AcmeMSU Map Applet Extension Class with Complete Code package com.adventnet.nms.tutorials.tl1; import com.adventnet.nms.mapui.MapApplet; import com.adventnet.nms.mapui.EditableMap; public class AcmeExtMapApplet extends MapApplet { public AcmeExtMapApplet () { } public void constructUI(EditableMap emap) { super.constructUI(emap); if (currentMapViewed.startsWith("Acme")) { emap.hideToolBar(); } } }

AdventNet Inc. 112

TL1 Tutorial

10.3 Description of Fault Management related files 10.3.1 Description of MSU Event Correlation Filter Class AdventNet Web NMS supports two forms of event correlation, time-correlation and grouping of failed elements.

• The first results in multiple events over time on any given component being correlated to a single alert in Web NMS.

• The second relates multiple alerts into an alert group, based on the alert group field in the alert.

For grouping of failed components, we use the Alert group field to relate alerts on multiple components where the failures have a common cause. The user sees only one alert from each group and can see the failures or alerts in that group when he opens up the alert details. Since Web NMS is not aware of the slot, card, port configuration in the device, it cannot correlate an autonomous message from the device to the respective card / slot / port. For this purpose we write an event filter. In this Event Filter we are doing three jobs.

• Identifying the corresponding slot/ card/ port to be updated based on the Autonomous Messages.

• Parsing and retrieving the status of the object from the text block and setting the correct severity for the event.

• Generating an event for this particular card or port. First, we check for the events which belong to the autonomous message category. From this event the autonomous message is extracted by using the getUserProperty method. Some special characters are removed from this autonomous message by calling the findAndReplace method and the parseAutonomousMessageText method is called with the event and the message as the parameters. public Event filter(Event event) { String category = event.getCategory(); if (category == null) return event; if (category.equalsIgnoreCase("topology")) { TopoAPI tapi = (TopoAPI) NmsUtil.getAPI("TopoAPI"); if (tapi == null) return event; String objname = event.getSource(); if (objname == null) return event; ManagedObject obj = null; try { obj = tapi.getByName(objname); } catch (Exception rex) { return event; } if (obj == null) return event; if ( (obj instanceof AcmeMSUNode) || (obj instanceof AcmeMSUShelf) || (obj instanceof AcmeMSUSlot) || (obj instanceof AcmeMSUCard) || (obj instanceof AcmeMSUPort) || (obj instanceof Channel) ) { event.setUserProperty("agentProtocol", "TL1"); return event;

AdventNet Inc. 113

TL1 Tutorial

} //return event; } else if (category.equalsIgnoreCase("TL1AutonomousMessage")) { String autoMessage = event.getDeviceNotification().toString(); if(autoMessage != null) { autoMessage = findAndReplace(autoMessage,"<CR>\n","\r"); autoMessage = findAndReplace(autoMessage,"<LF>","\n"); event = parseAutonomousMessageText(event, autoMessage); } } return event; } In the parseAutonomousMessageText method we use the TL1AutonomousMessageParser class to parse the response. public com.adventnet.nms.alertdb.Alert filter(com.adventnet. nms.alertdb.Alert a) { return a; } private Event parseAutonomousMessageText(Event event, String text) { try { TL1AutonomousMessageParser parser = new TL1AutonomousMessageParser(text); TL1TextBlock textBlk = parser.getTextBlock(); Vector vect = textBlk.getTL1LineList(); String host = event.getSource(); TopoAPI api = (TopoAPI)NmsUtil.getAPI("TopoAPI"); EventAPI evAPI = (EventAPI)NmsUtil.getAPI("EventAPI"); for(int i = 0; i < vect.size(); i++) { TL1Line currLine = (TL1Line)vect.elementAt(i); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); String cardName = prop.getProperty("field0:0"); String slotName=""; if(cardName.equalsIgnoreCase("SYS")||cardName. equalsIgnoreCase("DOWNLOAD COMPLETE")) { return event; } Here, we are doing the first job, i.e., getting the card/port name from the Autonomous message and then getting the corresponding managed object for that particular card or port by using the getByName method of Topo API. if(cardName.startsWith("CPU")) { slotName = "SLT-1"; } else { String numStr = cardName.substring(cardName.indexOf("-")+1); if(numStr.indexOf("-")!= -1)

AdventNet Inc. 114

TL1 Tutorial

{ numStr=numStr.substring(0,numStr.indexOf("-")); } int num = Integer.parseInt(numStr); slotName = "SLT-"+String.valueOf(num+1); } String sltName = host+"_"+"Shelf1"+"_"+slotName; String hostName = host+"_"+"Shelf1"+"_"+slotName+"_"+cardName; ManagedObject slotObj = api.getByName(sltName); ManagedObject obj = api.getByName(hostName); Here, we are doing the second job mentioned, i.e., Getting the equivalent severity from the message and accordingly set the status of the card/port. But before setting the severity we check if the managed object is an instance of AcmeMSUCard or PortInTL1Card and proceed accordingly. When the managed object is an instance of AcmeMSUCard, you get the severity string and the failure type where severity string represents the level of severity and the failure type (the cause of failure). When the failure type is CRDRMVD, i.e., when the card is removed the particular card is deleted from the database. Correspondingly the card gets removed in the chassis view as the map database is notified about the card being removed from the topology database. This scenario is shown in the image given below:

Note: In the above image, ST1 cards 7 and 10 are removed.

For all the other cases, we set the status of the card based on the severityStr. Once the status is set, the third work of the event filter is accomplished, i.e., an event is created and added to the EventAPI.

AdventNet Inc. 115

TL1 Tutorial

if(obj instanceof AcmeMSUCard) { AcmeMSUSlot slot = (AcmeMSUSlot)slotObj; AcmeMSUCard card = (AcmeMSUCard)obj; String severityStr = prop.getProperty("field1:0"); String failureType = prop.getProperty("field1:1"); int sev = getEqvSeverity(severityStr); if(failureType.equalsIgnoreCase("CRDRMVD")&& severityStr.equalsIgnoreCase("MJ")) { String sevStr = SeverityInfo.getInstance().getName(sev); InputEvent inEvent = new InputEvent (card.getClassname(), "The card "+ card.getName()+" is removed", sevStr,card.getName(), card.getName(),card.getName()); inEvent.setUserProperty("agentProtocol","TL1"); inEvent.setGroupName(card.getDeviceName()); try { evAPI.addEvent(inEvent); }catch(RemoteException rex) { System.out.println("Event could not be generated for failed card"); } api.deleteObjectAndSubElements(card.getName()); slot.setState("Empty"); try { api.lock(slot,LockableObject.WRITE_LOCK,2); api.updateObject(slot, true, true); }catch(AccessDeniedException e) { System.err.println("Error while updating the card object"); } } else { String sevStr = SeverityInfo.getInstance().getName(sev); InputEvent inEvent = new InputEvent (card.getClassname(), "The card "+ card.getName()+" has failed", sevStr,card.getName(),card.getName(), card.getName()); inEvent.setUserProperty("agentProtocol","TL1"); inEvent.setGroupName(card.getDeviceName()); try { evAPI.addEvent(inEvent); }catch(RemoteException rex) { System.out.println("Event could not be generated for failed card"); } } }

AdventNet Inc. 116

TL1 Tutorial

if(obj instanceof AcmeMSUPort) { AcmeMSUPort port = (AcmeMSUPort)obj; String severityStr = prop.getProperty("field1:0"); int sev = getEqvSeverity(severityStr); String sevStr = SeverityInfo.getInstance().getName(sev); InputEvent inEvent = new InputEvent (port.getClassname(), "The port "+port.getName()+" has failed ", sevStr,port.getName(), port.getName(),port.getName()); inEvent.setUserProperty("agentProtocol","TL1"); inEvent.setGroupName(port.getDeviceName()); try { evAPI.addEvent(inEvent); }catch(RemoteException e) { System.err.println("Event could not be sent for failed port"); } } } Similar to the card when the managed object is an instance of AcmeMSUPort, the status is set accordingly and an event is generated.

AdventNet Inc. 117

TL1 Tutorial

10.3.2 Description of AcmeMSU Alarm Propagation Filter Class Propagation filters need to implement the PropagationFilter interface in the com.adventnet.nms.alertdb package. These filters implement the applyPropagation() method, whose argument is a reduced version of the Alert. The reason for a reduced version is to reduce the amount of data being passed around. Using AlertAPI, we would get the complete Alert from the mini alert. /** This is the filter method called to propogate each alert **/ public void applyPropagation(MiniAlert miniAlert) { if (miniAlert == null) return; int sev = miniAlert.getSeverity(); if ( !SeverityInfo.getInstance().contains(sev) || SeverityInfo.getInstance().isNoCriticality(sev) || SeverityInfo.getInstance().isUnknown(sev) || SeverityInfo.getInstance().isInfo(sev) || (SeverityInfo.getInstance().getSpecialPurposeSeverity() == sev) ) return; String source = miniAlert.getSource(); if (source == null) return; TopoAPI topo_api = (TopoAPI)NmsUtil.getAPI("TopoAPI"); try { ManagedObject obj = topo_api.getByName(source); if (obj == null) return; // We'll first see if it's a port, card, slot, or shelf if ( !(obj instanceof AcmeMSUSlot) && !(obj instanceof AcmeMSUCard) && !(obj instanceof AcmeMSUPort) && !(obj instanceof AcmeMSUShelf)) { return; } // We need to fetch the complete alert, e.g. to get the group name Alert alert=((AlertAPI)(NmsUtil.getAPI("AlertAPI"))).getAlert (miniAlert.getEntity());

Once the Alert is obtained, we will propagate the Alert one level at a time. propagateToContainer(alert, obj, topo_api); In this method, first we would get the parentKey of the managedObject. A check is made if the status of the parent is different from that of the current object. If the status of both are same nothing is done. If the status of both are different an input event is generated for the parent. In this method the status is propagated from the port to the card and from card to the node. /** * Propagate the alert up the container hierarchy, i.e. to * the parent container. **/ void propagateToContainer(Alert alert, ManagedObject obj, TopoAPI topo_api) throws java.rmi.RemoteException { String parentKey="unknown"; if(obj instanceof AcmeMSUPort) { parentKey = obj.getParentKey();

AdventNet Inc. 118

TL1 Tutorial

} if(obj instanceof AcmeMSUCard) { parentKey = ((AcmeMSUCard)obj).getDeviceName(); } if (parentKey == null) { // no container or parent error System.err.println("No parentKey reference. Error: " + obj.getName()); return; } ManagedObject parent = topo_api.getByName(parentKey); if (parent == null) { System.err.println("Parent object: "+parentKey+" not found for object: "+obj.getName()); return; } if(obj instanceof AcmeMSUPort) { if(parent.getStatus() == alert.getSeverity()) { return; } else { sendEvent(parentKey, alert.getSeverity(), alert, parent); } } if(obj instanceof AcmeMSUCard) { AcmeMSUNode device = (AcmeMSUNode)parent; int parentStatus = device.checkStatus(); sendEvent(parentKey, parentStatus, alert, parent); } } private void sendEvent(String source, int status, Alert alert, ManagedObject parent) { InputEvent event = new InputEvent(parent.getClassname(), // use class as category "One or more of the objects in this "+parent.getType()+" have failed", parent.getStatusColor(status)source, source, source); event.setUserProperty("agentProtocol","TL1"); event.setGroupName(alert.getGroupName()); // to group alerts try { ((EventAPI)NmsUtil.getAPI("EventAPI")).addEvent(event); }catch(Exception exp) { exp.printStackTrace(); } } }

AdventNet Inc. 119

TL1 Tutorial

10.4 Description of Status Polling Custom Code

10.4.1 Description of Custom Code for Status Polling of Card Add the following Custom Code to accomplish status polling of the AcmeMSUCard managed object in the AcmeMSUCard object class at the end before the last "}". The status polling for the AcmeMSUCard object is also done in the same way as it is done for the port. Except that the command sent here is RTRV-EQPT with the access id as the card name instead of RTRV-FAC command. First the name of the card is obtained and then for this card the RTRV-EQPT command is sent. public int checkStatus() throws java.rmi.RemoteException { try { TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); AcmeMSUNode myswitch = (AcmeMSUNode)topoapi.getByName(getDeviceName()); String cardName = getName().substring(getParentKey().length()+1); Object resultObj = TL1SwitchUtil.syncSendCommand(myswitch, "RTRV-EQPT", cardName); if(resultObj == null) { return getStatus(); } if(resultObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply = (TL1ResponseMessage)resultObj; String cmdCode = reply.getResponseId().getCompletionCode(); int status = getStatus(); if(cmdCode.equals(TL1ResponseMessage.COMPLETED)) { status = 5; } else if(cmdCode.equals(TL1ResponseMessage.DELAYED_ACTIVATION)) { status = 4; } else if(cmdCode.equals(TL1ResponseMessage.PARTIAL_SUCCESS)) { status = 3; } else if(cmdCode.equals(TL1ResponseMessage.DENIED)) { status = 2; } else if(cmdCode.equals(TL1ResponseMessage.RETRIEVE)) { status = 2; } TL1TextBlock textBlk = reply.getTextBlock(); if(textBlk != null) {

AdventNet Inc. 120

TL1 Tutorial

Vector resp = textBlk.getTL1LineList(); if(resp.size() == 0) { return status; } else { TL1Line currLine = (TL1Line)resp.elementAt(0); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); String str = null; if(getType().equalsIgnoreCase("CPU")) { str = prop.getProperty("PST"); } else { str = prop.getProperty("PST"); } if(str != null) { status = severityForCardStatus(str); } } } if(status==1 || status==4) { setManaged(false); } else { setStatus(status); } } return getStatus(); }catch(Exception exp) { exp.printStackTrace(); } Now, similar to the check status of the port first the status is set based upon the completion code. Then from the response message the value of the PST/ST (PST for CPU card and ST for ST1 card) is obtained and correspondingly the status is set.

AdventNet Inc. 121

TL1 Tutorial

10.4.2 Description of Custom Code for Status Polling of Port Once you have defined managed objects for the components of your network, you also need to ensure the status of these objects is monitored and communicated to users. Status polling is needed, and Web NMS supports flexible status polling of your devices and components. For each type of device, Web NMS performs status polling of these devices based on the configuration. For each managed object, it invokes the status polling specified by the configuration, which may be a standard operation like pinging the device already supported by Web NMS or a custom polling that is needed for a specific device or component. We can also override the status polling code for your managed object. We will illustrate an example using the Port object & the same approach is handled to identify the status of the card object too. The Status of the port is identified by using the RTRV-FAC command (Retrieve Facility command, which has been already mentioned in the Command Set provided). Add the following imports in AcmeMSUPort MO Class. import java.util.Vector; import java.util.Properties; import com.adventnet.nms.topodb.ContainerInterface; import com.adventnet.nms.topodb.TopoAPI; import com.adventnet.nms.util.NmsUtil; import com.adventnet.tl1.message.TL1ResponseMessage; import com.adventnet.tl1.message.TL1TextBlock; import com.adventnet.tl1.message.TL1Line; Add the following Custom Code to accomplish status polling of the AcmeMSUPort managed object in the AcmeMSUPort object class at the end before the last "}". The method below in the managed object class is called whenever status polling of this object is scheduled. Using this method, you can directly control what happens when status polling is to be done for this object. Also each managed object can be configured to support failure counts, i.e. allowing multiple failures before a managed object failure is reported to the system. This is done by using the setFailureThreshold() method in the ManagedObject class. The code snippet of the checkStatus method is given below public int checkStatus() { try { TopoAPI topoapi = (TopoAPI)NmsUtil.getAPI("TopoAPI"); AcmeMSUNode mySwitch = (AcmeMSUNode)topoapi.getByName(getDeviceName()); AcmeMSUCard card = (AcmeMSUCard)topoapi.getByName(getParentKey()); String portName = getName().substring(card.getParentKey().length()+1); Object resultObj = TL1SwitchUtil.syncSendCommand(mySwitch, "RTRV-FAC", portName); if(resultObj == null) { return getStatus(); }

AdventNet Inc. 122

TL1 Tutorial

Here we are executing the RTRV-FAC command to the device with the port name as the accessid, we are sending it via the Management Server, which has been explained earlier in this tutorial. if(resultObj instanceof TL1ResponseMessage) { TL1ResponseMessage reply = (TL1ResponseMessage)resultObj; String cmdCode = reply.getResponseId().getCompletionCode(); int status = getStatus(); First Identify the severity with the Response completion status. if(cmdCode.equals(TL1ResponseMessage.COMPLETED)) { //Parse And Identify Status. status = 5; } else if(cmdCode.equals(TL1ResponseMessage.DELAYED_ACTIVATION)) { status = 4; } else if(cmdCode.equals(TL1ResponseMessage.PARTIAL_SUCCESS)) { status = 3; } else if(cmdCode.equals(TL1ResponseMessage.DENIED)) { status = 2; } else if(cmdCode.equals(TL1ResponseMessage.RETRIEVE)) { status = 2; } TL1TextBlock textBlk = reply.getTextBlock(); if(textBlk != null) { Vector resp = textBlk.getOutputText(); if(resp.size() == 0) { return status; } else { TL1Line currLine = (TL1Line)slotNames.elementAt(0); Properties prop = TL1SwitchUtil.convertLineAsProperties(currLine); Convert the TL1Line in the response as properties and get the value of PST variable which defines the status of the port. (whether it is in service / it is out of service etc., and get the corresponding severity and set it as the severity for the port. String str = prop.getProperty("PST"); if(str != null) { status = severityForCardStatus(str); } setStatus(status); } return getStatus(); }

AdventNet Inc. 123

TL1 Tutorial

The severityForCardStatus method where based on the value of the PST value an integer showing the status of port is returned is given below private int severityForCardStatus(String str) { if(str.equalsIgnoreCase("IS")) { return 5; } else if(str.equalsIgnoreCase("OOSMT")) { return 4; } else if(str.equalsIgnoreCase("OOS")) { return 2; } else if(str.equalsIgnoreCase("RESET")) { return 1; } return getStatus(); } Based on this return value a status update message is generated by the server. The fields of the generated event are based on the values in the managed object.

AdventNet Inc. 124

TL1 Tutorial

10.5 Description of Performance Management Configuration You will customize the performance by configuring the Polling.conf file. This file is present under <Web NMS HOME>/conf directory. As explained in the TL1 Command Set topic of Appendix you would use the RTRV-PM and RTRV-EQPT command to do the performance Management for ports and cards respectively. In this application create three polling objects to represent the port, card, and the node. Append the following lines to perform the data collection for the port in the Polling.conf file. <POLLING_OBJECT name="acme_msu_port"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="equals" value="acme_msu_port" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" > <DATA_TO_POLL dataIdentifier="RTRV-PM::${portName}:;" protocol="TL1" type="multiple" name="Port_Dol_Integer" response="ESL,SESL,LOSSL,ESP,CSSP" /> </DATA_COLLECTION> </POLLING_OBJECT> In order to filter out the port objects, the managed object property "TYPE" is used which was set in the discovery filter (AcmeMSUDiscFilter). The match criteria are given within the <MATCH_CRITERIA> tag . The command, protocol, name, and the parameters for polling are specified in the <DATA_TO_POLL> tag. For specifying the port name in the command Web NMS provides "$" support . This considerably reduces the time of specifying command for each port. For this, the port object should just have "portName" as a column which would give the name of the port. This value gets substituted in the place of $ {portName} and the command is executed. Similarly to collect data for the card the following entries have been appended in the Polling.conf file. <POLLING_OBJECT name="acme_msu_card"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="startsWith" value="acme_msu_card_" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" > <DATA_TO_POLL dataIdentifier="RTRV-EQPT::${cardName}:;" protocol="TL1" type="multiple" name="Port_Dol_String" response="PST,SST" /> </DATA_COLLECTION> </POLLING_OBJECT> Here the card object should just have "cardName" as a column which would return the name of the card. Also because there are two types of cards, the match criteria have been given as "type startsWith acme_msu_card" .

AdventNet Inc. 125

TL1 Tutorial

In order to collect data for the node as a whole, append the following entries in the Polling.conf file. <POLLING_OBJECT name="acme_msu_node"> <MATCH_CRITERIA> <MO_PROPERTIES> <STRING_TYPE property="type" condition="equals" value="acme_msu_node" /> </MO_PROPERTIES> </MATCH_CRITERIA> <DATA_COLLECTION pollingPeriod="300" protocol="TL1" > <DATA_TO_POLL dataIdentifier="RTRV-EQPT::ALL:;" type="multiple" name="Eqpt_ALL_String" response="PST,SST" componentId="0" /> <DATA_TO_POLL dataIdentifier="RTRV-PM::ALL:;" type="multiple" name="Port_ALL_Integer" response="ESL,SESL,LOSSL,ESP,CSSP" componentId="0" /> </DATA_COLLECTION> </POLLING_OBJECT> To collect data for TL1 protocol, the provider for the protocol must be plugged in. For this purpose, a TL1 protocol provider TL1DataCollecterAsync has been provided.

AdventNet Inc. 126

TL1 Tutorial

10.6 Description of Provisioning Files

10.6.1 Description of ChangeCardType Provisioning Template <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE Template (View Source for full doctype...)> <Template name="ChangeCardType" owner="root" displayForms="tab" autoDeregister="true"> <Stage label="3#"> <InventoryInput id="1#" MOName="$TemplateParam$Host" MOField="name" default="" useInventoryService="TopoAPI" /> <InventoryInput id="2#" MOName="$TemplateParam$Host" MOField="priority" default="" useInventoryService="TopoAPI" /> <InventoryInput id="3#" MOName="$TemplateParam$Host" MOField="cardName" default="" useInventoryService="TopoAPI" /> <InventoryInput id="4#" MOName="$TemplateParam$Host" MOField="deviceName" default="" useInventoryService="TopoAPI" /> <InventoryInput id="5#" MOName="$TemplateParam$Host" MOField="CRDSN" default="" useInventoryService="TopoAPI" /> <InventoryInput id="6#" MOName="$TemplateParam$Host" MOField="prodNo" default="" useInventoryService="TopoAPI" /> <InventoryInput id="7#" MOName="$TemplateParam$Host" MOField="CRDREV" default="" useInventoryService="TopoAPI" /> <InventoryInput id="8#" MOName="$TemplateParam$Host" MOField="MFDAT" default="" useInventoryService="TopoAPI" /> <InventoryInput id="9#" MOName="$TemplateParam$Host" MOField="tl1cardtype" default="" useInventoryService="TopoAPI" /> In this template you will get the name, priority, cardName, deviceName, CRDSN, PRODNO, CRDREV, MFDAT, and the tl1cardtype of the card from the database. For this purpose the entries are given within the <InventoryInput> tag. The MOName attribute contains the name of the Managed Object and MOField contains the name of the ManagedObject property that needs to be obtained. <Form title="Configuration" description="This template enables to change the priority and status of the card" id="3#"> <UserInput id="1#" name="cardname" label="CARD NAME" default="$InventoryInput$1#" editable="false" required="false" /> <UserInput id="6#" name="crdsn" label="CRDSN" default="$InventoryInput$5#" editable="false" required="false" /> <UserInput id="7#" name="mfdat" label="MFDAT" default="$InventoryInput$8#" editable="false" required="false" /> <UserInput id="8#" name="prodno" label="PRODNO" default="$InventoryInput$6#" editable="false" required="false" /> <UserInput id="9#" name="crdrev" label="CRDREV" default="$InventoryInput$7#" editable="false" required="false" /> - <UserInput id="3#" name="priority" label="PRIORITY" default="$InventoryInput$2#" editable="false" required="false"> - <Qualifier type="choice"> <Enum name="1" value="1" /> <Enum name="2" value="2" /> </Qualifier> </UserInput> - <UserInput id="5#" name="status" label="PST" default="IS" editable="false" required="false"> - <Qualifier type="choice"> <Enum name="IS" value="IS" /> <Enum name="OOS" value="OOS" /> </Qualifier> </UserInput> </Form>

AdventNet Inc. 127

TL1 Tutorial

Next, the form is created wherein the UserInputs are specified. This is specified within the Form tag. You create seven UserInputs each for the name, serial number of the card, manufacturing date of the card, production number of the card, card revision, priority, and the status of the card. These UserInputs would appear as label and text fields on the template. <ConfigTask taskName="EditCardProps" isNewTask="true" isOverwrite="true" isSequential="false" persistence="true" deviceResult="false" isTemplate="false" rollbackNeeded="false" version="1.0"> - <ProtocolMap name="tl1"> <Device host="$InventoryInput$4#" port="9099" /> </ProtocolMap> - <!-- configuration attributes --> <Attribute identifier="ED-EQPT" commandCode="ED-EQPT" targetID="" accessID="$InventoryInput$3#" generalBlock="" messagePayLoadBlock="PRIORITY=$UserInput$3#" /> <Attribute identifier="ED-EQPT" commandCode="ED-EQPT" targetID="" accessID="$InventoryInput$3#" generalBlock="" messagePayLoadBlock="PST=$UserInput$5#" /> </ConfigTask> </Stage> </Template> Then, in the ConfigTask tag specify the commands that will be used to perform the provisioning. You would name the config task as EditCardProps and specify the protocol as TL1. Since you are changing the priority of the card, you will use the ED-EQPT command. Then, the status is set for the card again by executing the ED-EQPT command.

AdventNet Inc. 128

TL1 Tutorial

10.6.2 Description of AcmeCrossConnect Provisioning Template For the cross connect example, a template AcmeCrossConnect.xml has been provided. In this file you set the config task. For the cross connect example, the ENT-CRS-T0 command is used to establish cross connection and the DLT-CRS-T0 command is used to delete the existing cross connection. This template would be used to send the command to the agent. <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE Template (View Source for full doctype...)> <Template name="AcmeCrossConnect" owner="root" displayForms="tab" autoDeregister="true"> <Stage label="1#"> <ConfigTask taskName="AcmeCrossConnectTask" isNewTask="true" isOverwrite="true" isSequential="false" persistence="true" deviceResult="false" isTemplate="false" rollbackNeeded="false" version="1.0"> <ProtocolMap name="tl1"> <Device host="localhost" port="9099" /> </ProtocolMap> <!-- configuration attributes --> <Attribute identifier="ENT-CRS-T0" commandCode="ENT-CRS-T0" targetID="" accessID="ST1-1-1-1,ST1-1-1-2" generalBlock="" messagePayLoadBlock="TYPE=DATA,MODE=2WAY,NAME=CUSTOMER1,PST=IS" /> </ConfigTask>

The CrossConnectUI.java and CrossConnectUtil.java are the two classes that are responsible for the UI representation and establishment of the cross connect. The CrossConnectUI.java class mainly concentrates on the UI representation. The command is sent to the agent in the CrossConnectUtil.java class. You would concentrate on how the ProvisioningAPI handle is obtained and the template is sent for provisioning after setting the various attributes. You will also see how the TopoAPI method calls are made from the server to the client using the client server communication. You get the ProvisioningAPI handle in the client through RMI. URL BE_Url = NmsClientUtil.applet.getCodeBase(); String BEHostName = "localhost"; BEHostName = BE_Url.getHost();

The name of the system, where the server is running, will be derived from the output of getCodeBase() method of NmsUtil. The template is sent for provisioning in the syncSendCommand method of CrossConnectUtil.java class. In this method, the template is obtained. xmlTemp = prAPI.getTemplate("AcmeCrossConnect"); temp = new Template(xmlTemp);

Once the template is obtained, it is parsed to get the various attributes of the config task. These attributes are set based on the action selected by the user in the cross connect UI.

AdventNet Inc. 129

TL1 Tutorial

Vector taskVect = temp.getConfigTasks(); for(int tv=0;tv<taskVect.size();tv++)

{ ConfigTask ct = (ConfigTask)taskVect.elementAt(tv); Device[] devArr = ct.getDevices(); devArr[0].setAttribute("host",ipaddress); devArr[0].setAttribute("port",tl1port); Attribute[] attrib = ct.getConfigAttributes(); attrib[0].setAttribute("identifier",commandCode); attrib[0].setAttribute("commandCode",commandCode); attrib[0].setAttribute("targetID", tid); attrib[0].setAttribute("accessID",aid); if(action.equalsIgnoreCase("connect"))

{ attrib[0].setAttribute("messagePayLoadBlock","TYPE="+type+", MODE="+mode+",NAME="+connName+",PST=IS"); }

else { attrib[0].setAttribute("messagePayLoadBlock",""); }

} }

After setting the various attributes, the template is sent for provisioning. The provisionNow() method of ProvisioningAPI is used to send the template for provisioning. id = prAPI.provisionNow(temp.toString()); Specified template is synchronously executed. Clients supply the fully populated templates which are used by the server to execute the provisioning operation. The returned XML (i.e., TemplateResult in string format) has the complete results of what was provisioned. From this XML template result, the TemplateResult is created. tempRes = new TemplateResult(id); From this result template, the provisioning status is obtained and returned. String status = tempRes.getStatus();

AdventNet Inc. 130

TL1 Tutorial

10.6.3 Description of Post Provisioning Filter Class Once the Apply button is selected from the template, the set of config tasks is sent to the device. After the provisioning activity gets completed (whether successful or not), one may need to do specific custom functions to complete the provisioning operation. Post-provisioning filters provide this capability. In this tutorial application, if the configuration result is successful it would set the priority of the card. Also it would set the status of the card. The ChangeCard.java file acts as the PostProvisioning Filter. The post provisioning filter should implement the PostProvisioningFilter interface. Therefore define the following method. public TemplateResult postProvision(TemplateResult templateResult,Template) throws OperationFailedException The completely populated template is passed here and the template result contains the results of the each configuration task that is executed. This method will check for the status of the provisioning task by getting the value returned by the status attribute. The status attribute in the template returns FAILED, if any one of the configuration tasks has failed. If all the configuration tasks were successful, then FINISHED is returned. If the status is FAILED, the filter will return the template. public TemplateResult postProvision(TemplateResult templateResult,Template template) throws OperationFailedException { Template fullTemplate = template; ProvisioningAPIImpl prov = null; //We will check for the result status. If the status is failed we will just return the template result. if(fullTemplate.getAttribute("status").equalsIgnoreCase("FAILED")) { return templateResult; } If the status is not FAILED, the filter will parse the template and store the different values. Vector invInputVect = fullTemplate.getInventoryInputs(); for(int i=0; i<invInputVect.size() ;i++) { InventoryInput invInput = (InventoryInput)invInputVect.elementAt(i); String moField = invInput.getMOField(); if(moField.equalsIgnoreCase("name")) { cardMOName = invInput.getAttribute("value"); } if(moField.equalsIgnoreCase("cardName")) { cardname = invInput.getAttribute("value"); } if(moField.equalsIgnoreCase("deviceName")) { deviceName = invInput.getAttribute("value"); } if(moField.equalsIgnoreCase("priority")) { actPriority = invInput.getAttribute("value"); }

AdventNet Inc. 131

TL1 Tutorial

} Vector formVect = fullTemplate.getForms(); for(int s=0; s<formVect.size();s++) { Form form = (Form)formVect.elementAt(s); Vector userInputVect = form.getUserInputs(); for(int x=0;x<userInputVect.size();x++) { UserInput uInput = (UserInput)userInputVect.elementAt(x); String inputName = uInput.getName(); if(inputName.equalsIgnoreCase("priority")) { priority = uInput.getValue(); } if(inputName.equalsIgnoreCase("status")) { status = uInput.getValue(); } } } The filter will get corresponding card managed object from the name of the card. AcmeMSUCard cardObj = (AcmeMSUCard)api.getByName(cardMOName); The filter will check if the current card priority and the selected priority are different. If different, it would set the priority of the card. if(!actPriority.equalsIgnoreCase(priority)) { cardObj.setPriority(priority); api.lock(cardObj,LockableObject.WRITE_LOCK,2); api.updateObject(cardObj,true,true); } Also, based on the PST value selected from the template, an event is generated for the card. if(status.equalsIgnoreCase("IS")) { int cardStatus=5; String sev = SeverityInfo.getInstance().getName(cardStatus); InputEvent inEvent = new InputEvent(cardObj.getClassname(), "Status updation through configuration", sev,cardObj.getName(),cardObj.getName(), cardObj.getName()); inEvent.setUserProperty("agentProtocol","TL1"); inEvent.setGroupName(cardObj.getDeviceName()); try { ((EventAPI)NmsUtil.getAPI("EventAPI")). addEvent(inEvent); }catch(RemoteException rex) { System.out.println("Event could not be generated for failed card"); } }

AdventNet Inc. 132

TL1 Tutorial

10.7 Description of Client Server Communication Code To use the common socket, the AcmeMsuClientSocketConn class must implement the SocketConnection interface. Therefore, overwrite the close and receive methods. To get the responses back from the server, the class must register itself with the MainSocketClient. PureClientUtils.commonSocket.registerForResponses(this,MSU_ID); The class registers itself with a unique ID which helps in identifying correct client requests. First the send method calls the server. The syncSend method is called and the method name and the required parameters are passed as arguments. These data are serialized and sent to the server through the common socket. byte[] resultByteArr = PureClientUtils.commonSocket.syncSend(MSU_ID,retData); For the server to handle requests from the client, the class has to implement SocketServerConnectionBE. This is done in the AcmeMsuSocketServerConnBE.java file. First the class registers itself with the MainSocketServerBE . PureServerUtilsBE.serverSocketBE.registerForResponses(this); This class gets notification about the client requests through its init method. In init method, to handle the client requests, the AcmeMsuSocketSessionConnBE.java is instantiated. This class implements the SocketSessionConnectionBE interface. To get packets from the client, this class registers itself with the MainSocketSessionBE. public AcmeMsuSocketSessionConnBE(MainSocketSessionBE mainSocketSession) { mssbe=mainSocketSession; mssbe.registerForResponses(this,ACME_MSU); } The receive method is called whenever a packet arrives from the client. In this method, the data that come in the form of a byte array are deserialized into a Vector. The method name along with the parameters is obtained. The topoAPI handle is created and the method is executed. Based on the result the properties resultProp is created. This property is again serialized and the sendDataToClient method is called. result_byte=NmsUtil.serializeProperties(resultProp); sendDataToClient(SYNC_SEND,uniqueId,result_byte); In this method, the processed data are sent back to the client through the MainSocketSessionBE. mssbe.send(ACME_MSU,uniqueId,retData);

AdventNet Inc. 133

TL1 Tutorial

11.0 Appendix 11.1 TL1 Command Set used in the Application ACME MSU TL1 MESSAGE SET Login Command ACT-USER::ROOT:::[PUBLIC]; FACTORY 2001-05-12 04:13:07 M COMPLD ; Activates an user login session. Logout Command CANC-USER:::; FACTORY 2001-05-12 04:23:12 M COMPLD ; Cancels (terminates) a login session on the channel that the command is entered. Retrieve Network Element Information Command RTRV-NE:::; FACTORY 2001-05-12 04:17:29 M COMPLD "-1:FACTORY" ; The command is to retrieve the NE local node or target node identification information. Retrieve System Inventory Command RTRV-INVENTORY:::; FACTORY 2001-05-12 01:44:43 M COMPLD "CPU-1::CRDTYPE=CPU,CRDSN=57,MFDAT=01/24/2000,PRODNO=712700,CRDREV=A2" "SLT-1::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-2::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-3::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-4::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-5::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-6::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-7::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-8::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-9::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" "SLT-10::CRDTYPE=ST1,CRDSN=23,MFDAT=01/25/2000,PRODNO=712800,CRDREV=A0" ; The command gives the slots and the details about the card in that slot. This data is used for creating the slot object in the discovery filter.

AdventNet Inc. 134

TL1 Tutorial

Retrieve Card Settings Command RTRV-EQPT::ALL:; FACTORY 2001-05-12 01:53:13 M COMPLD "CPU-1:::PST=IS" "ST1-1::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" "ST1-2::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" "ST1-3::PRIORITY=1,TYPE=CSU,WKMOD=WK,ST=IS" "ST1-4::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" "ST1-5::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" "ST1-6::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=OOS" "ST1-7::PRIORITY=1,TYPE=CSU,WKMOD=WK,ST=IS" "ST1-8::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" "ST1-9::PRIORITY=1,TYPE=CSU,WKMOD=WK,ST=OOS" "ST1-10::PRIORITY=1,TYPE=DSX,WKMOD=WK,ST=IS" ; The command gives the entire card settings for the device . This data is used for creating the card objects in the discovery filter. Retrieve Card Settings For A Particular Card RTRV-EQPT::ST1-1:; FACTORY 2001-05-12 02:46:11 M COMPLD "ST1-1::PRIORITY=1,TYPE=DSX,WKMOD=WK,PST=IS" ; (Similarly RTRV-EQPT command responds for the requests for any specific card defined in the inventory list) The command gives the card settings for a particular card . The data (value of PST i.e the primary status) is used for setting the status of the card. Delete Card Command DLT-EQPT::ST1-4:; FACTORY 2001-05-12 02:49:38 M COMPLD ; (Similar responses for other possible access id's to DLT-EQPT command) The command is to delete previously provisioned parameters and settings of a specific logic card in the device. In this tutorial the result from this command is used in the post provisioning filter class for the provisioning example explained later. Create Equipment Command ENT-EQPT::ST1-4::::TYPE=DSX; FACTORY 2001-05-12 02:48:20 M COMPLD ; (Similar responses for other possible access id's to ENT-EQPT command)

AdventNet Inc. 135

TL1 Tutorial

The command is to provision a logic card with parameters and settings for any of the logic cards of the device. In this tutorial the result from this command is used in the post provisioning filter class for the provisioning example explained later. Edit Card Settings Command ED-EQPT::ST1-4::::TYPE=CSU; FACTORY 2001-05-12 03:23:59 M COMPLD The command is to edit previously-provisioned parameters and settings of a specific logic card in the device. The command is used in the provisioning example explained later in this tutorial. Retrieve Facity Data Command RTRV-FAC::ST1-8-1:; FACTORY 2001-05-12 04:27:02 M COMPLD "ST1-8-1::LINECDE=B8ZS,LINELEN=0-133,FRM=D4,FDL=OFF:PST=OOS, SST=FLT&IDLE,IPSTATE=OFF"" ; The command is to retrieve facility data ( port data). The command is used in this tutorial to get the status of the port by checking for the PST value. This has been implemented in the check status method of the AcmeMSUPort class. Retrieve (View) Alarms Command For A Specific Card RTRV-ALM::ST1-8:; FACTORY 2001-05-12 04:28:59 M COMPLD "ST1-8-1,T1:MJ,LOS,SA,2001-05-12,01-51-14,,:" "ST1-8-1,T1:MJ,LOF,SA,2001-05-12,01-51-18,,MASK:" "ST1-8-1,T1:MJ,CGA-RED,SA,2001-05-12,01-51-15,,:" ; The command is to retrieve the system alarms for a specific card of the device. The command is sent as an autonomous message from the simulator. Retrieve (View) Alarms Command For All Cards RTRV-ALM::ALL:; FACTORY 2001-05-12 04:30:03 M COMPLD "ST1-7-1,T1:MJ,LOS,SA,2001-05-12,01-47-28,,:" "ST1-7-1,T1:MJ,LOF,SA,2001-05-12,01-47-32,,MASK:" "ST1-7-1,T1:MJ,CGA-RED,SA,2001-05-12,01-47-28,,:" "ST1-8-1,T1:MJ,LOS,SA,2001-05-12,01-51-14,,:" "ST1-8-1,T1:MJ,LOF,SA,2001-05-12,01-51-18,,MASK:" "ST1-8-1,T1:MJ,CGA-RED,SA,2001-05-12,01-51-15,,:" "ST1-10,EQPT:MJ,IO_CARD_MISSING,SA,2001-05-12,01-51-43,,:" "ST1-10-1,T1:MJ,LOS,SA,2001-05-12,01-51-43,,MASK:" "ST1-10-1,T1:MJ,LOF,SA,2001-05-12,01-51-45,,MASK:" "ST1-10-1,T1:MJ,CGA-RED,SA,2001-05-12,01-51-43,,MASK:" "SYS,SYS:MN,POWER_A_FAIL,NSA,2001-05-12,01-04-12,,:" ; The command gives the alarms for all the cards.

AdventNet Inc. 136

TL1 Tutorial

Retrieve performance Counts Command RTRV-PM::ST1-8-1:::,,,,15-MIN,,0; FACTORY 2001-05-12 04:35:08 M COMPLD "ST1-8-1,T1:ESL,305,NA,NEND,RX,15-MIN,0" "ST1-8-1,T1:SESL,306,NA,NEND,RX,15-MIN,0" "ST1-8-1,T1:LOSSL,306,NA,NEND,RX,15-MIN,0" "ST1-8-1,T1:ESP,11,NA,NEND,RX,15-MIN,0" "ST1-8-1,T1:CSSP,11,NA,NEND,RX,15-MIN,0" ; The command is to retrieve performance monitoring data on a particular port. AUTONOMOUS MESSAGES FACTORY 2001-05-12 04:39:42 ** 230 REPT ALM T1 "ST1-8-1:MJ,LOS,SA,2001-05-12,04-39-42,,:\"SLT LOSS OF SIGNAL\"" ; This Autonomous Message is received when a card is faulty with Loss of Signal. FACTORY 2001-05-12 04:39:05 ** 228 REPT ALM EQPT "ST1-8:MJ,CRDRMVD,SA,2001-05-12,04-39-04,,:\"ST1 CARD MISSING\"" ; This Autonomous Message is received when a card is missing. FACTORY 2001-05-12 04:13:07 AA 0 REPT EVT SESSION "SYS:LOGON,CL,2001-05-12,04-13-07,,,,:\"PRIVATE SYSTEM UNAUTHORIZED USERS MAY BE PROSECUTED\"" ; This Autonomous Message is received when an unauthorized Login is attempted.

AdventNet Inc. 137

TL1 Tutorial

11.2 TL1 Basics Transaction Language1 (TL1) is a network management protocol used for managing Telecommunication networks. TL1 facilitates communication between a managed device (a device with TL1 agent), and a TL1 manager. The TL1 agent on the managed device serves to provide access to data stored on the managed device. The TL1 manager uses this access to monitor and control the managed device. TL1 protocol communicates via TCP. Data (TL1 Messages) are sent and received in the form of byte stream. Types of Messages

TL1 specifies four types of messages as follows.

• Input Command Messages • Acknowledgements • Output Response Messages • Autonomous Messages

An Input command message is a message from an OS or other source (i.e. manager) to an Network Element.(NE). (i.e. agent). The message requests the NE to perform some action. An acknowledgement is a short reply from the NE indicating that an input command message is being acted upon or has been immediately rejected. The essential purpose of an acknowledgement is to reassure a human user that a command that takes a long time to execute has been received by the NE. An output response message is a detailed reply (or set of replies) to an input command message. It contains information indicating whether the command was executed successfully and any data that needs to be returned to the OS/user. An autonomous message is one generated by the NE either on a periodic timed basis or to report some unusual occurrence.

AdventNet Inc. 138

TL1 Tutorial

11.2.1 Message Structure This section explains the format and structure of different types of TL1 messages (Input, Output, Acknowledge, Autonomous) as defined by the BellCore specifications. This section is very important for those users who would like to understand and analyze the TL1 messages exchanged between the TL1 Manager and the Agent. On a broader level, TL1 Messages can be logically categorized into two types, namely Input and Output messages. The output message can be either Response, Autonomous or Acknowledgement messages. All messages have their own format and structure.

AdventNet Inc. 139

TL1 Tutorial

11.2.2 Input Message General Format The general structure of a TL1 input message is of the form <command_code>:<staging_parameter_blocks>:<message_payload_block>; Command Code

It determines the action to be taken at the NE as a result of receiving the input message. Each command must begin with a command code consisting of a mandatory verb followed by up to two optional identifiers,each separated by hyphen. <command code> ::= <verb>[-<modifier>[-<modifiers>]] Verb identifies the action to be taken at the NE as a result of receiving a TL1 message from an OS. The command code modifiers are optional depending upon the specific command and application domain. The first modifier identifies where the action is to be applied in the NE. The second modifier may be used to further define the identity of the object upon which the action is to be taken. For example, a <verb>-EQPT can be used to indicate that an action, specified by the value of the verb, is to be taken on an equipment object. A <verb>-T0 indicates an action is being taken on DS0 circuit. As another example, for switching NE's, the command <verb>-<administrative view> indicates an action is to be taken on an object entity within the specific administrative view of the switching NE database. Another example is shown to illustrate how the second modifier is used. The command DLT-CRS-T0 will disconnect (DLT) one or more cross connected (CRS) DS0 object entities (T0).The modifier CRS is further defined to identify T0 object entities. Staging Parameter Block

These are a series of four data blocks following the command code that provide information to establish and uniquely identify an object entity within an NE to be managed by a remote OS and to specify certain options as to how the input command is to be executed in the NE. The structure of the staging parameter blocks consists of the following series: :[<targetidentifier>]:<accessidentifier(s)>:<correlationtag>:[<general block>]: Each block may have one or more specifically defined parameters. The parameters within each staging block may either be position-defined or name-defined.

• Target Identifier Block

An input message associated with the management of a particular object may be directly addressed to an NE or it may be routed to or through one or more intermediate NE's. The Target IDentification code (TID ) parameter block provides the capability within the TL1 message format to perform network routing tasks. The presence of the TID in all input commands is a requirement,but its value may be null (represented by two successive colons).

The TID block contains a single position-defined parameter that identifies the end-target NE to which the input command is directed. The value of TID may be any valid simple or compound TL1 identifier or text string limited to 20 characters.

AdventNet Inc. 140

TL1 Tutorial

• Access Identifier Block

The Access IDentifier (AID) block normally contains one or more parameters that uniquely identifies the entity within the target NE to be acted upon by the input message. Typical examples of entities addressed by the AID parameter values are:

o Circuits and common equipment modules having hierarchical relationships. o Record entities within the context of an administrative view of the NE database. o Test session and Test Access Point aliases.

• Correlation Tag (CTAG)

It contains one position defined parameter to serve as a means of correlating an input command with its associated output response. The OS assigns an arbitrary non-zero CTAG value and it is the responsibility of the NE to copy this value into the output response associated with that input command. The value of CTAG must either be a TL1 identifier or a non-zero decimal number consisting of not more than six characters.

• General Block (GB): It includes support parameters whose values affect the way in which

the input command is to be executed in the NE. The presence of GB in all input commands is a requirement but its value may be null (represented by two successive colons). The form of the General Block is : :[[<delay activation parameters>],[<contingency flag>],[<indirect data retrieval identifier>]]:

Delay Activation is a function whereby an input message may be stored in a message pending buffer at the NE for final execution at some later time. The Delay Activation function is provided by a set of parameters within the GB of the form : [ON=]<order no.>,[DATE=]<date>,[TIME]<time> Contingency Flag parameter is a boolean data type within the GB that indicates,when set true,a dependent relationship among the several records specified in the AID data block of a multi-unit command. If CF is false, partial installation of the records in a multi unit message may be completed with a report sent to the OS listing the records that were not successfully installed in a database. Indirect Data Retrieval Indicator is a functional capability by which information may be retrieved from more than one linked administrative view by a single RTRV command. Message Payload Block

This block indicates the subject matter of the message. This section may consists of zero or more data blocks in the form. (:<Px>(,<Px>)*)*; where Px represents a data item. Each data block is delimited by colons (:) and the last terminated by a semicolon (;). Each data block may have an unlimited number of data items,each delimited by commas (,). The data items within a data block may be either name-defined (<keyword>=<value>) or position-defined where values are specified and the keyword is implied by its position in the data block.

AdventNet Inc. 141

TL1 Tutorial

11.2.3 Output Response Message General Format

A TL1 output response message is the response to a TL1 Input Command message. The general structure of a TL1 output response message is of the form : <header> <response identification> [<text block>] <termination> which consists of a optional text block and all the other blocks are essential. Header

The Header represents information common to all output response. <cr><lf><lf>^^^<sid>^<year>-<month>-<day>^<hour>:<minute>:<second> It contains System identifier <sid>, date and time stamps.<sid> is restricted to 20 characters maximum and identifies the NE generating the message. The syntax of <sid> is any TL1 identifier or text string. The <year><month><day> construct represent the day in which the output response is generated. The <hour><minute><second> construct represent the time at which the output response is generated. Response Identification

The form of the response identification is : <cr><lf>M^^<ctag>^<completion code> This construct consists of three components namely the character M, a correlation Tag and a completion code. The character M signifies that the message is the response to the input command. The ctag must be the same as that of the input message in order to associate the response with the proper input command. The various completion codes are described below. COMPLD Total successful execution of the input command. DENY Total denial of the input command. PRTL Partial successful execution of the input command. This response code is valid when the ctag in the general block is FALSE. DELAY Successful queuing of the input command submitted for delayed activation. RTRV Output response of a input retrieve command that retrieves extensive amount of information from the NE and uses more time for processing. Text Block

The optional [<text block>] is used to represent information specific to the particular autonomous message. The format of the text block is as follows: ((<cr><lf>^^^<unquoted line>) | (<cr><lf>^^^<quoted line>) | (<cr><lf>^^^<comment>))

AdventNet Inc. 142

TL1 Tutorial

It consists of three components namely unquoted line,quoted line and comment. Both quoted and unquoted lines consists of text that is parsable, while comment is not. The most popular usage of unquoted line is for representing error codes in some response messages. The quoted line consists of parsable text and shall be preceded and followed by double quotes. The comment line is used to allow free format text. It should be preceded by (/*) and followed by (*/). Terminator

The form of the terminator is : <cr><lf>( ; | > ) The semicolon (;) character indicates the termination of the output message and greater than (>) character indicates more output associated with this response will follow under another header. Since the size of the output message should not exceed 4096 bytes, it is important to split the response into blocks with the same Ctag. Example Assume that the input command RTRV-NETYPE:Source::100; was issued, a typical NE output message will look like the following: <cr><lf><lf> ^^^Source^04-04-04^05:05:05<cr><lf> M^^100^COMPLD<cr><lf> ^^^"NORTEL,OPTera Metro 3000 MSP Series NP,ABC,REL0900"<cr><lf> ; where '^' indicates space character.

AdventNet Inc. 143

TL1 Tutorial

11.2.4 Acknowledgement Message General Format An acknowledgement is a brief output message generated in response to an input command message. An NE may optionally have the ability to turn on or off acknowledgements via a Standard input command, Custom command, or message from a local terminal. In general, an acknowledgement is later followed by an output response message to the command. However, in some circumstances,an acknowledgement is the only output message triggered by a command. An acknowledgement should be used if an output response message to the command cannot be transmitted within two seconds of its receipt. The format of an acknowledgement is as follows: <acknowledgement code> ^ <ctag> <cr> <lf> < The acknowledgement code identifies the reason for the acknowledgement. The CTAG identifies the associated input command. The less than (<) character is the acknowledgement terminator. Acknowledgement Codes

The valid values for acknowledgment codes and their meanings are given below.

• IP - In Progress and PF - Printout Follows The request has been initiated. These acknowledgements should produce output messages that give a termination report or results of the command along with termination report. They are used often for test and access messages requiring a long execution time. These acknowledgements are often followed by either Completed or Denied response messages.

• OK - All Right

The command was received and the requested action was initiated and completed. In addition, OK is used in response to a command that has been cancelled by inclusion of the CAN (Cancel) character.

• NA - No Acknowledgement

This command is sent if initiation or execution of the requested command is not possible. Under abnormal conditions, NA is sent when command has been accepted but control of the processing has been lost. It can also be used to respond in circumstances if the command is garbled during transmission. If the CTAG value of the command could not be determined, then Zero (0) should be used as a CTAG value for the acknowledgement.

• NG - No Good (Not Used)

The command is valid but the requested action conflicts with current system or equipment status. For inadequate system resources use RL instead of NG. This acknowledgement code is seldom used because specific error codes in output response messages can be employed to signify the same information. It can be used if desired.

• RL - Repeat Later

The requested action cannot be executed due to unavailable system resources caused by system overload, excessive queue lengths, busy programs etc. The command can be sent at later times for any response.

Example IP 25 < where IP indicates request is in progress and 25 indicates CTAG value as that of the input message.

AdventNet Inc. 144

TL1 Tutorial

11.2.5 Autonomous Message An Autonomous message is a message that is sent from the NE to the appropriate OS without having an explicit input message associated with it. Typical scenarios where autonomous messages are used include :

• Reporting of alarmed or non-alarmed trouble events. • Reporting of scheduled diagnostic tests in the NE. • Reporting of Performance Monitoring data. • Reporting of a change in the NE's database. • Periodic reporting of selected NE conditions.

General Format

The general structure of a TL1 Autonomous message is: <header> <auto id> [ <text block> ] <terminator> Here the text block is the optional field and all other fields are essential.

Header The Header represents information common to all output response and autonomous messages. It contains System identifier <sid>, date and time stamps. <cr><lf><lf>^^^<sid>^<year>-<month>-<day>^<hour>:<minute>:<second> It contains System identifier <sid>, date and time stamps.<sid> is restricted to 20 characters maximum and identifies the NE generating the message. The syntax of <sid> is any TL1 identifier or text string. The <year><month><day> construct represent the day in which the output response is generated. The <hour><minute> <second> construct represent the time at which the output response is generated. AutoID It indicates the severity and the nature of the Autonomous message. The <Auto id> entry for an autonomous message is of the form <cr><lf> <almcde>^<atag>^<verb>[^<modifier>[^<modifier>]] Where <almcde> is the alarm code. It can be any of the following based on the severity of the autonomous message. Alarm code and Description

*C : Critical Alarm ** : Major Alarm *^ : Minor Alarm A^ : Non-Alarm Message

If Multiple Alarms are reported in the same message, the alarm code is the highest severity of those being reported. <atag> is the Autonomously Generated Correlation Tag. It is assigned by the NE, must be sequential and must be included in all autonomously generated messages. It allows an OS to

AdventNet Inc. 145

TL1 Tutorial

correlate spontaneous outputs triggered by a common problem and also to identify whether the OS has failed to receive any output. <verb>[^<modifier>[^<modifier>]] entry identifies the nature of the spontaneous output. The first identifier is a required entry and indicates the message verb. The autonomous message can have two optional modifiers separated by space character.

Text Block

The optional [<text block>] is used to represent information specific to the particular autonomous message. The format of the text block is as follows : (<cr><lf>^^^<unquoted line>)|(<cr><lf>^^^<quoted line>)|(<cr><lf>^^^<comment>) It consists of three components namely unquoted line, quoted line and comment. Both quoted and unquoted lines consists of text that is parsable, while comment is not. Terminator

The terminator block has the form <cr><lf> ( ; | >) This is required for all TL1 message types. Example <cr> <lf> <lf> ^^^SPFGX507 99-01-01 06:06:06 <CR><lf> A^^123^REPT^ALM^COM <cr><lf> ^^^"SP:MJ,INT,NSA,01-01,06-06-06,NEND,NA:\"Disk Full\"" <cr><lf> ; where '^' symbol indicates Space

AdventNet Inc. 146

TL1 Tutorial

12.0 Other tutorials AdventNet Web NMS is vast in its capability to serve its different class of users. It would be hard for anyone to understand all of its features at one time. We strongly recommend you to go through some of our other tutorials to get of feel of what could be done on our Web NMS. Building an Element Management System This tutorial provides working illustrative examples to guide the developer through designing an EMS. Design aspects and the usage of Web NMS tools to simplify the development of an EMS are elaborated here. Building an EMS with CORBA as Southbound Interface This tutorial explains how developer can build Element Management Systems, which support CORBA as the southbound interface. In this tutorial, we have used TR-005 and TR-035 standards specified by the ANSI T1M1 forum. It explains, how developer can implement the Working Text, WT-046 Version 3.0 as specified in the DSL forum. CORBA Northbound tutorial This CORBA Northbound Tutorial shows how easily AdventNet Web Network Management System (NMS) can be used for distributed NMS applications by providing CORBA northbound support to interact with other Northbound Operational Support Systems (OSS). XML Southbound tutorial This tutorial builds an EMS with the information got from an XML enabled device. From the responses received the EMS chassis is built and some other functions are included.

AdventNet Inc. 147