JavaAPI for Tellabs® 8000 Network Manager Northbound Interface

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 70182_01 30.09.09

Document Information

© 2009 Tellabs. All rights reserved. This Tellabs manual is owned by Tellabs or its licensors and protected by U.S. and international copyright laws, conventions and treaties. Your right to use this manual is subject to limitations and restrictions imposed by applicable licenses and copyright laws. Unauthorized reproduction, modification, distribution, display or other use of this manual may result in criminal and civil penalties. The following trademarks and service marks are owned by Tellabs Operations, Inc. or its affiliates in the United States and/or other countries: TELLABS ®, TELLABS ® logo, TELLABS and T symbol ®, and T symbol ®. Any other company or product names may be trademarks of their respective companies. The specifications and information regarding the products in this manual are subject to change without notice. All statements, information, and recommendations in this manual are believed to be accurate but are presented without warranty of any kind, express or implied. Users must take full responsibility for their application of any products. Adobe ® Reader ® are registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 2

70182_01 © 2009 Tellabs.

Document Information

Terms and Conventions

70182_01 © 2009 Tellabs.

Term

Explanation

API

Application Programming Interface

DB

Database

GPT

General Problem Type

NBI

Northbound Interface

NE

Network Element

OSS

Operations Support System. Includes e.g. EMS, NMS and SMS functionalities.

SPT

Specific Problem Type

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 3

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 4

70182_01 © 2009 Tellabs.

Table of Contents

Table of Contents

About the Manual .............................................................................................................. 11 Objectives........................................................................................................................................................................11 Audience..........................................................................................................................................................................11 Related Documentation ...................................................................................................................................................11 Document Conventions ...................................................................................................................................................11 Documentation Feedback............................................................................................................................................... 12

1

Introduction to JavaAPI .............................................................................................. 13

2

Downward Compatibility of JavaAPI ......................................................................... 16

3

Clear Text Descriptions and Capacity Vectors of Attribute Values ........................ 17

4

Problem Type Descriptions and Probable Cause of Network Element Alarms..... 18

5

How to Use JavaAPI.................................................................................................... 19 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8

70182_01 © 2009 Tellabs.

Java Runtime Environment ................................................................................................................................. 19 Create an Object of TolService Class ................................................................................................................. 19 Decide if You Want to See the Clear Text Descriptions of DB Values ............................................................... 19 5.3.1 Create an Object of NbifAttributeValueService Class ....................................................................... 19 Decide if You Want to See the Problem Type Descriptions and Probable Cause of NE Alarms........................ 20 5.4.1 Create an Object of NbifAttributeAlarmValueService Class .............................................................. 20 Decide the Datetime Format of JavaAPI............................................................................................................. 20 Open Communication (Socket) ........................................................................................................................... 21 Open Session ....................................................................................................................................................... 21 Running a Get Command .................................................................................................................................... 22 5.8.1 Creating Object TolResultSet .............................................................................................................. 22 5.8.2 Getting Inventory and Performance data............................................................................................. 22 5.8.3 Getting Alarm Data ............................................................................................................................. 23 5.8.4 Managing the Input Parameters of the Get Commands....................................................................... 23

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 5

Table of Contents

5.9 5.10

5.11 5.12 5.13 5.14 5.15

6

5.8.5 Retrieve the Result Data ...................................................................................................................... 26 5.8.6 Retrieve the Clear Text Descriptions for the Attribute Values ............................................................ 29 5.8.7 Retrieve the Problem Type Descriptions and Probable Cause of NE Alarms..................................... 29 5.8.8 Retrieve the Capacity Vector ............................................................................................................... 29 Provisioning with Macros.................................................................................................................................... 30 Subscribing to the Tellabs 8000 Manager NBI Inventory and NBI Alarm Notifications ................................... 31 5.10.1 Implement TolEventObserver Interface .............................................................................................. 32 5.10.2 Register as an Observer with addChangeListener Method ................................................................. 33 5.10.3 Check if Notifications Are Supported for the Entity ........................................................................... 33 5.10.4 Subscribe Commands for Subscribing to Inventory Entities............................................................... 33 5.10.5 Subscribe Commands for Subscribing to Alarm Entities and System Notifications........................... 34 5.10.6 Handle the Received Inventory Notifications...................................................................................... 34 5.10.7 Handle the Received Alarm Notifications ........................................................................................... 36 5.10.8 Handle the Received System Notifications ......................................................................................... 36 Acknowledging Alarms....................................................................................................................................... 37 Pinging the NBI Server to Verify that It Is Alive ................................................................................................ 37 Command Names and Codes............................................................................................................................... 37 Close Session....................................................................................................................................................... 38 Close Communication (Socket)........................................................................................................................... 38

TolService Class.......................................................................................................... 39 6.1

6.2

6.3

6.4 6.5 6.6

6.7

Establishing Connections to the Tellabs 8000 Manager NBI.............................................................................. 40 6.1.1 Method openCommunication for Opening Socket.............................................................................. 40 6.1.2 Method closeCommunication for Closing Socket............................................................................... 40 6.1.3 Method openSession............................................................................................................................ 40 6.1.4 Method closeSession ........................................................................................................................... 41 Requesting Inventory or Performance Data from the Tellabs 8000 Manager NBI ............................................. 41 6.2.1 Method getAllData .............................................................................................................................. 41 6.2.2 Method getFilteredAllData................................................................................................................. 42 6.2.3 Method getOneData............................................................................................................................. 44 6.2.4 Method getIntervalData (Deprecated) ................................................................................................. 45 6.2.5 Method pingNima................................................................................................................................ 46 6.2.6 Method pingNsa .................................................................................................................................. 46 Requesting Alarm Data from the Tellabs 8000 Manager NBI ............................................................................ 47 6.3.1 Method getActiveAlarmData .............................................................................................................. 47 6.3.2 Method getAllData for Getting Alarms............................................................................................... 47 Acknowledging Alarms....................................................................................................................................... 48 6.4.1 Method acknowledgeAlarm ................................................................................................................ 48 Executing the Tellabs 8000 Manager NBI Configuration Changes (Macros)..................................................... 49 Subscribing to the Tellabs 8000 Manager NBI Inventory and NBI Alarm Notifications ................................... 49 6.6.1 Method addChangeListener................................................................................................................. 50 6.6.2 Method removeChangeListener .......................................................................................................... 50 6.6.3 Method subscribeNotification.............................................................................................................. 50 6.6.4 Method unsubscribeNotification.......................................................................................................... 51 6.6.5 Method subscribeSystemNotification.................................................................................................. 51 6.6.6 Method unsubscribeSystemNotification.............................................................................................. 51 Settings of TolService.......................................................................................................................................... 52 6.7.1 Trace Level of JavaAPI ....................................................................................................................... 52 6.7.2 Datetime Pattern of JavaAPI ............................................................................................................... 53

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 6

70182_01 © 2009 Tellabs.

Table of Contents

7

TolResultSet Class ...................................................................................................... 54 7.1 7.2

7.3

8

Scanning the Tellabs 8000 Manager NBI Response Records ............................................................................. 54 Extracting Attributes from a Record ................................................................................................................... 55 7.2.1 Method getValueAsString.................................................................................................................... 55 7.2.2 Method getValueByte .......................................................................................................................... 56 7.2.3 Method getValueShort ......................................................................................................................... 56 7.2.4 Method getValueInt ............................................................................................................................. 56 7.2.5 Method getValueDouble ...................................................................................................................... 56 7.2.6 Method getValueLong64 ..................................................................................................................... 57 7.2.7 Method getValueDate .......................................................................................................................... 57 7.2.8 Method getValueString ........................................................................................................................ 57 7.2.9 Method getValueBytes......................................................................................................................... 57 Datetime Pattern of TolResultSet ........................................................................................................................ 58

NbifAttributeInfo and NbifAttributeService Classes ................................................ 59 8.1 8.2 8.3

8.4

8.5

70182_01 © 2009 Tellabs.

Entity IDs and Names.......................................................................................................................................... 59 Attribute IDs and Names ..................................................................................................................................... 59 Methods for Handling Entities ............................................................................................................................ 60 8.3.1 Methods that Return All Entities ......................................................................................................... 60 8.3.2 Methods that Return Inventory and Performance Entities .................................................................. 60 8.3.3 Methods that Return Alarm Entities.................................................................................................... 61 8.3.4 Method getEntityName........................................................................................................................ 62 8.3.5 Method getEntityIdForEntityName..................................................................................................... 62 8.3.6 Method getEntityObject ...................................................................................................................... 62 8.3.7 Method isAlarmEntity ......................................................................................................................... 62 8.3.8 Method isEclEntity .............................................................................................................................. 63 8.3.9 Method getEntityNotificationSupport ................................................................................................. 63 Methods for Handling Attributes......................................................................................................................... 63 8.4.1 Methods that Return Attributes ........................................................................................................... 63 8.4.2 Method getAttributeNamesInArrayList .............................................................................................. 64 8.4.3 Method getNumberOfKeyAttributes................................................................................................... 64 8.4.4 Methods that Return Key Attributes.................................................................................................... 64 8.4.5 Method getAttributeObject.................................................................................................................. 65 8.4.6 Method getAttributeIdForAttributeName............................................................................................ 66 8.4.7 Method getAttributeEntityId ............................................................................................................... 66 8.4.8 Method getAttributeName................................................................................................................... 66 8.4.9 Method getAttributeDataTypeCode .................................................................................................... 66 8.4.10 Method getAttributeDataTypeDesc ..................................................................................................... 67 8.4.11 Method getAttributeDataLength.......................................................................................................... 67 8.4.12 Method getAttributeIsKey................................................................................................................... 67 Methods for Parsing Strings ................................................................................................................................ 67 8.5.1 Method parseEntities ........................................................................................................................... 68 8.5.2 Method parseOneEntity....................................................................................................................... 68 8.5.3 Method parseAttributes ....................................................................................................................... 68 8.5.4 Method parseOneAttribute .................................................................................................................. 69 8.5.5 Method parseFilters ............................................................................................................................. 69 8.5.6 Method parseAttributeValueList.......................................................................................................... 70 8.5.7 Method parseOneValue........................................................................................................................ 70 8.5.8 Method parseIntegerParameterList...................................................................................................... 71 8.5.9 Method parseOneInteger ..................................................................................................................... 71 Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 7

Table of Contents

8.6

8.7 8.8

9

8.5.10 Method parseOneLong ........................................................................................................................ 71 Methods for Getting Capacity Vectors ................................................................................................................ 72 8.6.1 Method convertBytesToCapacityVectorString .................................................................................... 72 8.6.2 Method convertBytesToCapacityVectorArrayList .............................................................................. 73 Attribute Data Type Definition ............................................................................................................................ 75 Methods for Getting Example Value Format for Attributes ................................................................................ 75 8.8.1 Method getExampleValueString.......................................................................................................... 75 8.8.2 Method getExampleTolDateTimeString.............................................................................................. 76

NbifAttributeValueService Class................................................................................ 77 9.1

Methods for Handling the Attribute Value Descriptions ..................................................................................... 77 9.1.1 Method NbifAttributeValueService..................................................................................................... 77 9.1.2 Method getService_data_is_ok............................................................................................................ 78 9.1.3 Method getDescriptionOfAttributeValue ............................................................................................ 78 9.1.4 Method getValueOfAttributeDescription ............................................................................................ 78 9.1.5 Method getAttributeValueObjectsOfAttribute .................................................................................... 79

10 NbifAttributeAlarmValueService Class ..................................................................... 80 10.1 NE Alarm Types .................................................................................................................................................. 80 10.2 Methods for Handling the Alarm Values............................................................................................................. 80 10.2.1 Method NbifAttributeAlarmValueService........................................................................................... 80 10.2.2 Method getService_data_is_ok............................................................................................................ 81 10.2.3 Method getGptText.............................................................................................................................. 81 10.2.4 Method getSptText .............................................................................................................................. 81 10.2.5 Method getAlarmtypetext.................................................................................................................... 82

11 NbifAttributeSptValue Class....................................................................................... 83 11.1 Methods for Handling the Specific Problem Type Descriptions of an NE Alarm .............................................. 83 11.1.1 Method getSpttext................................................................................................................................ 83 11.1.2 Method getProbablecause.................................................................................................................... 83 11.1.3 Method getSourcehw........................................................................................................................... 83 11.1.4 Method getSptCode ............................................................................................................................. 84 11.1.5 Method getAlarmtype.......................................................................................................................... 84 11.1.6 Method getHwtype .............................................................................................................................. 84

12 TolType and TolTypeService Classes ........................................................................ 85 12.1 Values in TolType Class....................................................................................................................................... 85 12.1.1 Codes of Commands for Accessing Data from NBI Server................................................................ 85 12.1.2 Codes for Received Notifications ........................................................................................................ 85 12.1.3 Status Stored in the Header of the Reply Message.............................................................................. 85 12.1.4 Error Codes Set in Case of Problems in Reading Reply Data............................................................. 85 12.1.5 Codes and Names of Supported Capacity Vector Types ..................................................................... 86 12.1.6 Codes of Supported Trunk Allocation Types ...................................................................................... 86

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 8

70182_01 © 2009 Tellabs.

Table of Contents

12.2

12.3

12.4

12.5

12.1.7 Trace Level .......................................................................................................................................... 87 12.1.8 Filter Types Available for GetFilteredAllData Command................................................................... 87 TolTypeService Methods for Handling Commands ............................................................................................ 87 12.2.1 Method getCommandName................................................................................................................. 87 12.2.2 Method getCommandCode.................................................................................................................. 88 12.2.3 Methods that Return Commands for Managing Inventory and Performance Data............................. 88 12.2.4 Methods that Return Commands for Managing Alarms ..................................................................... 88 TolTypeService Methods for Capacity Vector Types .......................................................................................... 89 12.3.1 Method getCapacityVectorAlloctypeForTrunkAllocType .................................................................. 89 12.3.2 Method getCapacityVectorTypeCode................................................................................................. 89 12.3.3 Method getCapacityVectorTypeName................................................................................................. 90 12.3.4 Method getCapacityVectorTypeCodes ................................................................................................ 90 12.3.5 Method getCapacityVectorTypeNames ............................................................................................... 90 TolTypeService Methods for Handling Trace Log Levels .................................................................................. 91 12.4.1 Methods getTraceLevelCodes and getTraceLevelNames ................................................................... 91 12.4.2 Method getTraceLevelName ............................................................................................................... 91 12.4.3 Method getTraceLevelCode ................................................................................................................ 91 TolTypeService Methods for Handling Filter Types of Command GetFilteredAllData ..................................... 92

13 OpenResultSet Class .................................................................................................. 93 13.1 Extracting the Tellabs 8000 Manager NBI Session’s Handle ID ....................................................................... 93

14 TolEventObserver Class ............................................................................................. 94 14.1 Processing the Tellabs 8000 Manager NBI Inventory Notifications ................................................................... 94 14.1.1 Create Notifications ............................................................................................................................. 94 14.1.2 Attribute Value Change Notifications.................................................................................................. 95 14.1.3 Delete Notifications ............................................................................................................................. 95 14.2 Processing the Tellabs 8000 Manager NBI Alarm Notifications ........................................................................ 96 14.2.1 TolAlarmEvent Methods ..................................................................................................................... 96 14.3 Processing the Tellabs 8000 Manager NBI System Notifications ....................................................................... 96 14.3.1 TolSystemEvent Methods.................................................................................................................... 97

15 OSS Client Development and JavaAPI Use .............................................................. 98 15.1 15.2 15.3 15.4 15.5

Using JavaAPI to Simultaneously Integrate Inventory Data and Alarm Data ................................................... 98 Entity IDs and Attribute IDs ............................................................................................................................... 98 Required Setting at NIMA.INI ........................................................................................................................... 99 Providing Key Attribute Values in getOneData and getIntervalData Requests ................................................. 99 Other JavaAPI Specific Data Types..................................................................................................................... 99 15.5.1 TolDateTime Class .............................................................................................................................. 99 15.6 JavaAPI Exceptions........................................................................................................................................... 102 15.6.1 TolCommunicationException ............................................................................................................ 102 15.6.2 TolAttributeException ....................................................................................................................... 104 15.7 Using the openCommunication() and openSession() Methods ........................................................................ 104

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 9

Table of Contents

16 Using NBI Test Client ................................................................................................ 105 16.1 Installing Java Runtime Environment ............................................................................................................... 105 16.2 Files of the NBI Test Client ............................................................................................................................... 105 16.2.1 jar-files NBITestClient.jar and tol.jar ................................................................................................ 105 16.2.2 Clear Text Description File................................................................................................................ 105 16.2.3 Ini File for the Test Client.................................................................................................................. 106 16.3 Launching the Test Client.................................................................................................................................. 107 16.4 NBI Inventory and Performance Services (Target NIMA)................................................................................ 108 16.4.1 Commands for Subscribing to Notifications ......................................................................................110 16.4.2 Command GetAll...............................................................................................................................111 16.4.3 Command GetFilteredAll ...................................................................................................................112 16.4.4 Command GetOne ..............................................................................................................................114 16.5 NBI Fault and Provisioning Services (Target NSA)...........................................................................................115 16.5.1 Commands for Subscribing to Notifications ......................................................................................117 16.5.2 Command GetAll................................................................................................................................117 16.5.3 Command Execute Macro ..................................................................................................................118

Appendix: JavaAPI Examples ....................................................................................... 119

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 10

70182_01 © 2009 Tellabs.

About the Manual

About the Manual Objectives This manual gives information on JavaAPI, a Java based library that provides a high-level programming interface for developers of third party OSS Client applications.

Audience This information is aimed at the developers of third party OSS Client applications. With the help of JavaAPI library, the developers do not need to know details about the underlying protocols used in the Tellabs 8000 Network Manager Northbound Interface (Tellabs 8000 network manager NBI). The developers of third party OSS Client applications must use the Java programming language to be able to benefit from the JavaAPI library and must implement an adapter module at the OSS System that uses JavaAPI classes to integrate with the Tellabs 8000 network manager NBI.

Related Documentation Document No

Document Name

Tellabs ® 8000 Network Manager R17A Installation and Configuration Guide for Northbound Interface (70173_XX)

Provides instructions on installing and configuring the Northbound Interface service of Management Server of theTellabs 8000 network manager.

Information on general Java classes, for example information on the Java class SimpleDateFormat, is available at SUN’s web pages:

Document Conventions This is a note symbol. It emphasizes or supplements information in the document.

This is a caution symbol. It indicates that damage to equipment is possible if the instructions are not followed.

This is a warning symbol. It indicates that bodily injury is possible if the instructions are not followed.

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 11

About the Manual

Documentation Feedback Please contact us to suggest improvements or to report errors in our documentation: Email: [email protected] Fax: +358.9.4131.2430

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 12

70182_01 © 2009 Tellabs.

1 Introduction to JavaAPI

1 Introduction to JavaAPI The figure below shows an overview of how JavaAPI and the Tellabs 8000 manager NBI are used when integrated to a third party OSS system.

Fig. 1 JavaAPI and Tellabs 8000 Network Manager NBI Integrated to a Third Party OSS System

JavaAPI is composed of more than 20 Java classes and one interface, but only a selection of the classes and methods are public for OSS Client development. For processing notifications messages sent by the Tellabs 8000 manager NBI, the OSS Client needs to implement one JavaAPI Interface. The main public classes are:

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 13

1 Introduction to JavaAPI

• TolService containing the Tellabs 8000 manager NBI communication methods • openCommunication • openSession • getAllData • getOneData • getFilteredData • getActiveAlarmData • acknowledgeAlarm • getIntervalData • subscribeNotification and others. • OpenResultSet containing a method to obtain the HandleId that identifies a session to the Tellabs 8000 manager NBI. • TolResultSet containing methods to read and parse data sent by Tellabs NBI in response to getAllData, getOneData and getIntervalData calls. Notification data is also handled by TolResultSet. • NbifAttributeService containing methods to handle data entities and attributes. • NbifAttributeValueService containing methods to get descriptions for the attribute values. To process the notifications sent by the Tellabs 8000 manager NBI, the OSS Client application must implement the TolEventObserver interface. JavaAPI is provided as a set of Java class files that should be installed at the computer/server running the OSS Client application. JavaAPI requires J2SE release 1.5 or newer. The figure below shows an example of the OSS Client application being implemented in the TellabsClient.java file and installed under directory \OSSApp. JavaAPI files should then be installed in the \OSSApp\ directory.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 14

70182_01 © 2009 Tellabs.

1 Introduction to JavaAPI

Fig. 2 An Example of JavaAPI Files Implemented

The JavaAPI can be used for two purposes: 1.

NBI Inventory and Performance Services

2.

NBI Fault and Provisioning Services

These services are provided in different ports of the NBI Server. The JavaAPI programmer must create the connection to the wanted port to have access to the services. For GET operations, there is a list of supported entities. Each entity supports a list of attributes. An entity can be a physical object (for example a node or a unit), a logical object (for example a circuit, an mplsvpn), a performance object (for example G821 performance data), an alarm object (network element alarm or service alarm), etc.

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 15

2 Downward Compatibility of JavaAPI

2 Downward Compatibility of JavaAPI JavaAPI is downward compatible with previous releases of Tellabs 8000 network manager. OSS application can implement the most recent methods and performance enhancements of the latest JavaAPI even when it is integrating with an older release of Tellabs 8000 manager. OSS application can start using the new commands and getting data for the new entities and attributes as soon as Tellabs 8000 network manager is upgraded to a release which supports them.

JavaAPI is not compatible upward. When upgrading to a new release of Tellabs 8000 manager, the newest JavaAPI must be taken into use.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 16

70182_01 © 2009 Tellabs.

3 Clear Text Descriptions and Capacity Vectors of Attribute Values

3 Clear Text Descriptions and Capacity Vectors of Attribute Values JavaAPI provides Clear Text description texts for the attribute values (since R15A) and Capacity Vectors (since R16). For example, you can easily view the node’s hardware type. After you have received the data from the NBI Server to your client, you can pass the values over to Clear Text Description methods of JavaAPI to get the Clear Text description, e.g. string “8630” in case of a Tellabs 8630 access switch node (whose code value is 10017). For more information on using the Clear Text descriptions, see the information below. The trunk capacity usage can also be clearly seen. After receiving the data from the NBI Server to your client, you can pass the capacity data over to Capacity Vector methods of JavaAPI to get the Capacity usage in a clear format, e.g. the used capacity of a STM-1 trunk can been seen as a clear text “TU:100,211,212,310,370”, which shows which TU-12’s, TU-2’s and TU-3’s are used.

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 17

4 Problem Type Descriptions and Probable Cause of Network Element Alarms

4 Problem Type Descriptions and Probable Cause of Network Element Alarms JavaAPI provides descriptions for alarms which is a useful feature for NBI alarm integration. It provides the following: • description of the Generic Problem Type (GPT) code • description of the Specific Problem Type (SPT) code • probable cause for alarms • the type of the alarm (NODE Alarm, NTU Alarm or NMS Alarm) • the hardware type of the faulty unit or the faulty NTU After you have received the alarms from the NBI Server to your client, you can pass the alarm data to Alarm Description methods of JavaAPI to get the SPT and GPT problem type descriptions, the probable cause of the alarm, the type of the alarm and the hardware type of the faulty unit or NTU. E.g. for an alarm from Interface unit for Tellabs 8660 edge switch, the alarm might have GPT code 10004 and SPT code 1769474. The Alarm Description methods of JavaAPI provide the following descriptions: • GPT: "Alarm received from the Tellabs 8600 equipment" • SPT: "Tx circuit down" • probable cause: "Circuit is down in transmit direction. The reason may be that the LDP signalling is not successfully executed." • type of the alarm: "NODE Alarm" • hardware type of the unit: "8605 Interface Unit" For more information on using the Alarm Description methods of JavaAPI, see the information below.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 18

70182_01 © 2009 Tellabs.

5 How to Use JavaAPI

5 How to Use JavaAPI 5.1

Java Runtime Environment Use JavaAPI with Java Runtime Environment 5.0 or newer.

5.2

Create an Object of TolService Class The class TolService provides methods for handling the commands of JavaAPI. The default constructor is TolService Srv = new TolService(); An alternative constructor of TolService takes the trace level as a parameter. TolService prints only those messages to JavaAPI trace which have a higher importance than the selected (or default) trace level. For more information on the constructors and the trace level settings, see 6 TolService Class.

5.3

Decide if You Want to See the Clear Text Descriptions of DB Values If you want to use the Clear Text descriptions, create an object of class NbifAttributeValueService. With the methods of NbifAttributeValueService you can either get all Clear Text descriptions or convert an attribute value to its description. You can use NbifAttributeValueService to give the Clear Text descriptions for the result data of Get commands or when you receive notifications.

There should be only one instance of NbifAttributeValueService since creating such an object is a reasonably heavy task.

5.3.1

Create an Object of NbifAttributeValueService Class Class NbifAttributeValueService provides methods for getting Clear Text descriptions for the attribute values. When an instance of class NbifAttributeValueService is created, it loads the Clear Text descriptions from files and maps them to those attributes which support the descriptions.

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 19

5 How to Use JavaAPI

You can check that the NbifAttributeValueService was loaded properly by getting the status with method getService_data_is_ok(). This status contains the boolean value True if the Clear Text descriptions exist. For more information on NbifAttributeValueService, see 9 NbifAttributeValueService Class.

5.4

Decide if You Want to See the Problem Type Descriptions and Probable Cause of NE Alarms If you are integrating to NBI Alarms and want to get the Problem type descriptions and probable cause of NE alarms, create an object of class NbifAttributeAlarmValueService. With the methods of NbifAttributeAlarmValueService you can get the GPT and SPT descriptions, the probable cause of the alarm, the type of the alarm and the hardware type of the faulty unit or NTU. You can use NbifAttributeAlarmValueService to get the descriptions for the result data when getting all existing active alarms or when you receive alarm notifications. There should be only one instance of NbifAttributeAlarmValueService since creating such an object is a reasonably heavy task.

Starting up the JavaAPI takes longer, when you use the feature to get the Problem type descriptions and probable cause of alarms since the JavaAPI loads the problem type description and probable cause texts at startup.

5.4.1

Create an Object of NbifAttributeAlarmValueService Class Class NbifAttributeAlarmValueService provides methods for getting the GPT and SPT descriptions, the probable cause of the alarm, the type of the alarm and the hardware type of the faulty unit or NTU. When an instance of class NbifAttributeAlarmValueService is created, it loads the problem type descriptions and probable cause texts from files. You can check that the NbifAttributeAlarmValueService was loaded properly by getting the status with method getService_data_is_ok(). This status contains the boolean value True if the descriptions exist. For more information on NbifAttributeAlarmValueService, see 10 NbifAttributeAlarmValueService Class.

5.5

Decide the Datetime Format of JavaAPI JavaAPI prints out datetimes and requires the datetimes to be inserted in a certain pattern. The pattern is common (static) in JavaAPI. The default datetime pattern is " dd.MM.yyyy HH:mm:ss:SSS". For example: “10.03.2005 19:30:25:55”. If you want to change the default datetime pattern, you can do it either

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 20

70182_01 © 2009 Tellabs.

5 How to Use JavaAPI

1.

with set-methods of TolService (see 6.7.2 Datetime Pattern of JavaAPI) or

2.

with set-methods of a TolDateTime object (see 15.5.1 TolDateTime Class).

Changing the pattern affects all the places where datetimes are used. 1.

The datetime pattern is used when printing out results containing datetime attributes with methods of TolResultSet class.

2.

The datetime pattern is needed in class TolService when giving datetime values as input to commands GetFilteredAllData (or GetIntervalData).

NBI Server applications return the TolDateTime values by default in the local normal time. There is an option to return the TolDateTime values in UTC time by adding the parameter USE_UTC_TIME=YES to the nsa.ini and nima.ini files in the NBI Server.

5.6

Open Communication (Socket) Define the hostname or the IP address of the Northbound Interface. Define the port where the Northbound Interface provides the requested services: Requested Services

Service Name

Service Port (Server Default)

NBI Inventory and Performance services

NIMA

2462

NBI Fault and Provisioning services

NSA

2461

Open the socket using the method openCommunication of TolService class public void openCommunication(String hostAddress, int portNumber) throws IOException When using JavaAPI to communicate with NBI Fault and Provisioning services, the following configuration changes have to be made: in %DXXDIR%\dat\nsa.ini, set the parameter BYTE_CONVERSION=OFF.

5.7

Open Session Define an object of the class OpenResultSet: OpenResultSet resultSet = new OpenResultSet(); Define the username and the password. Open the session using the method openSession of TolService class:

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 21

5 How to Use JavaAPI

public void openSession(String userName, String passWord, OpenResultSet openResultSet) throws IOException, TolCommunicationException Get the handleId using the method getHandleId of OpenResultSet class: public long getHandleId() Store the handleId. You need it every time you send commands to the Northbound Interface: long handleId = openResultSet.getHandleId();

5.8

Running a Get Command The available commands depend on the port you have opened. However, there are common features in the different Get commands: • All Get commands return the data in TolResultSet. You can use the same methods of the class TolResultSet to evaluate the results. • All Get commands require the entityId as an input parameter. • Most Get commands require an ArrayList of selected attributes as an input parameter. • Some Get commands require specific input parameters.

5.8.1

Creating Object TolResultSet First, define an instance of class TolResultSet to let the Get command fill it with data. TolResultSet resultSet = new TolResultSet();

5.8.2

Getting Inventory and Performance data The following methods are available for getting Inventory and Performance data (NIMA in port 2462): Method or TolService

Description

Parameters

getAllData

Method to retrieve the selected attributes for all existing rows of the selected entity.

long handleId int entityId ArrayList selectedAttributes TolResultSet resultSet (Output)

getFilteredAllData

Method to retrieve the selected attributes for those rows of the selected entity which match the given filters.

long handleId int entityId ArrayList selectedAttributes ArrayList filterAttributes ArrayList filterAttrValues ArrayList filterTypes TolResultSet resultSet (Output)

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 22

70182_01 © 2009 Tellabs.

5 How to Use JavaAPI

5.8.3

Method or TolService

Description

Parameters

getOneData

Method to retrieve the selected attributes for a single row of the selected entity, which matches the given key attribute values.

long handleId int entityId ArrayList selectedAttributes ArrayList keyAttributes ArrayList keyAttrValues TolResultSet resultSet (Output)

getIntervalData

Note: A deprecated method which works only for some performance entities. Method to retrieve the selected attributes for those rows of the selected entity which are in the given time interval and, for some of the entities, match the given Circuit ID/ NTU ID. It is recommended to use the method getFilteredAllData instead!

Deprecated method Parameters are as in case of getOneData. However, the order of the keyIds does matter. Since this command is deprecated, the details are not described here.

Getting Alarm Data The following method are available for getting alarm data (NSA in port 2461):

5.8.4

Command

Description

Parameters

getActiveAlarmData

Returns all attributes for all existing rows of the selected (alarm) entity. The method getActiveAlarmData does not require giving any attributes as an input parameter but it always returns all the attributes.

long handleId int entityId TolResultSet resultSet (Output)

getAllData

Returns all attributes for all existing rows of the selected (alarm) entity. The method getAllData requires giving all existing attributes of the select (alarm) entity in the prespecified order.

long handleId int entityId ArrayList selectedAttributes TolResultSet resultSet (Output)

Managing the Input Parameters of the Get Commands Commands require giving the supported entities, attributes, filter types etc. as input parameters. Commands allow giving ArrayLists containing either IDs/codes or names/symbols. OSS client applications dealing with predefined supported entities and attributes can directly use them from the NbifAttributeInfo class and in the TolType class.

70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 23

5 How to Use JavaAPI

A GUI application is more likely to play around with lists of supported entities, attribute, values etc. There are several methods available which format the parameters to the format expected by the Get command. 1.

You can get a list of all possible supported entities.

2.

You can get a list of all possible attributes of an entity.

3.

You can get a list of possible values for an attribute.

4.

You can convert the names into IDs and vice versa.

See also Appendix: JavaAPI Examples The handleId Is Needed for Any Get Command Input parameter handleId is the handle ID which you received from the OpenSession command. The entityId is Needed for Any Get Command The entityIds can be taken directly from the NbifAttributeInfo class (see 8.1 Entity IDs and Names). There are also methods in NbifAttributeService, which return (see 8.3 Methods for Handling Entities): 1.

All supported entities (either Inventory and Performance or Alarm entities).

2.

Entity name for an entity ID and vice versa.

3.

Information if the entity is the Tellabs 8000 manager Provisioning related entity (ECL entity). And methods which can be used for parsing the entity from a string (see 8.5 Methods for Parsing Strings).

4.

Methods for parsing entity IDs or NAMEs from a string.

Selected Attributes for Get Commands The input parameter selectedAttributes is an ArrayList of attributes, which you want to get. ArrayList is allowed to contain either attribute IDs (as Integers) or attribute names (as Strings). The attribute IDs and names can be taken directly from the NbifAttributeInfo class (see 8.1 Entity IDs and Names). For Inventory and Performance entities you can select, that is, add to the ArrayList, as many attributes as you like in any order. However, to make the getting of the data faster, it a recommended to select only those attributes which are of importance to your OSS Client application. For Alarm entities ALL attributes must be selected in the predefined order. So, instead of selecting the attributes, it is recommended either to • use the command getActiveAlarmData(), where you do not have to give the selected attributes or • use the method ArrayList getAttrIdArrayList(int entityId) of NbifAttributeService to create the ArrayList. Give that ArrayList directly as an input parameter selectedAttributes to GetAllData()command.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 24

70182_01 © 2009 Tellabs.

5 How to Use JavaAPI

For Get commands of Alarm entities, all attributes must be included in the selected attributes and they must be included in the order of the attribute IDs.

There are also methods in NbifAttributeService which return (see 8.4 Methods for Handling Attributes): 1.

All attributes of the given entity.

2.

A number of key attributes and all key attributes of the given entity.

3.

Properties of the given attribute (entity, data type, data length, if it is key).

4.

Attribute name for an attribute ID and vice versa. And methods which can be used for parsing the attributes from a string (see 8.5 Methods for Parsing Strings):

5.

Methods for parsing attribute IDs or NAMEs from a string.

Key Attributes and Key Values for GetOneData Command For the GetOneData command you must give the key attributes of the entity in one ArrayList and the key values in another ArrayList. ArrayList of key attributes is allowed to contain either attribute IDs (as Integers) or attribute names (as Strings). ArrayList of key values must contain a value for each key attribute in its own data type. To be able to use the command GetOneData(), you must know which of the attributes are key attributes and you must know their data types to give the key value in its own data type format. Note that there are methods available in NbifAttributeService to find out which attributes are key attributes and the methods to get the key attributes. The key attributes can be added to the ArrayList in any order. However, you must insert the key attribute values to their ArrayList in the same order as you inserted the key attributes. The key attributes can be managed as the selected attributes (described above). Additionally, there are methods in NbifAttributeService for parsing the values from a string (see 8.5 Methods for Parsing Strings): • Methods for parsing attribute value(s) from a string to the data type(s) of the attribute. Filter Attributes, Filter Types and Filter Values for GetFilteredAllData Command For the GetFilteredAllData command you can give a filter which consists of one or more logical conditions. The logical condition is a condition on the values of one attribute. For example, you can have a filter for the NODE entity where the logical condition is that the node hardware type attribute has value 10017: NODE_HWTYPE = 10017 If you give more logical conditions in a filter, the logical conditions are joint with “AND”. 70182_01 © 2009 Tellabs.

Tellabs ® 8000 Network Manager R17A JavaAPI for Tellabs ® 8000 Network Manager Northbound Interface 25

5 How to Use JavaAPI

(Attribute1 operator1 value1) AND (Attribute2 operator2 value2) AND ... AND (AttributeN operatorN valueN) where

AttributeX

means attribute (ID or name)

operatorX

means filter type ( =, < , > , = , LIKE)

valueX

means value used in filtering

The maximum of ten logical conditions (AttributeX operatorX valueX) can be applied in a filter. For example, you can have a filter for the NODE entity where the logical condition is that the node hardware type attribute has value 10017 and the node ID is in the range of 100 and 199: ( NODE_NHWTYPE = 10017 ) AND ( NODE_NID >= 100 ) AND ( NODE_NID , = , LIKE)

valueX

means value used in filtering

The maximum of ten logical conditions (AttributeX operatorX valueX) can be applied in a filter. For example, you can have a filter for the NODE entity where the logical condition is that the node hardware type attribute has value 10017 and the node ID is in the range of 100 and 199: ( NODE_NHWTYPE = 10017 ) AND ( NODE_NID >= 100 ) AND ( NODE_NID , = , LIKE)

valueX

means value used in filtering

For example, you can have a filter for the NODE entity where the logical condition is that the node hardware type attribute has value 10017 and the node ID is in the range of 100 and 199: NHWTYPE = 10017;NID >= 100;NODE_NID = 100;NODE_NID