Electronic Bonding with ILEC

Electronic Bonding Architecture Document

v1.1.2

Revision History
Date 09/12/03 09/19/03 09/25/03 09/30/03 10/03/03 10/29/03 11/13/03 Revision Number 0.5 0.9 0.91 0.92 1.0 1.1 1.1.1 Author Covad Architecture Covad Architecture Covad Architecture Covad Architecture Covad Architecture Covad Architecture Covad Architecture Comment Initial Draft Add more details More Details for OSS/J Implementation Address the MTTR issue Changes according to design review More Details on the schema design section Changes on local entity bean description 1. Change message acknowledge mode 2. For ILEC trouble ticket creation, creates a record in TT_ILECINFO with Covad related information before sends message

12/10/03

1.1.2

Covad Architecture

v1.1.2

Table of Contents
1INTRODUCTION............................................................................................................5 2INDUSTRY STANDARDS............................................................................................. 6 2.1T1M1 STANDARD........................................................................................................... 6 2.2OSS/J........................................................................................................................... 7 2.3OSS/J VS T1M1 STANDARD............................................................................................7 3THE EXISITING COVAD TROUBLE TICKET SYSTEM.......................................9 4THE NEW COVAD TROUBLE TICKET SYSTEM................................................ 10 4.1DEPLOYMENT VIEW: THE BIG PICTURE............................................................................. 10 4.2NOTES ON THE DEPLOYMENT VIEW.................................................................................. 11 4.3DESIGN RATIONALE........................................................................................................11 4.4EMPHASIS ON COVAD MTTR......................................................................................... 11 4.5OVERVIEW OF NEW EJB COMPONENTS............................................................................ 12 4.6OVERVIEW OF JMS QUEUE/TOPIC COMPONENTS............................................................... 13 4.7OVERVIEW OF THE TIMER SERVICE................................................................................... 13 4.8OVERVIEW OF ILEC TROUBLE TICKET GATEWAY.............................................................. 13 4.9SECURITY......................................................................................................................14 4.10SCALABILITY................................................................................................................14 4.11PERFORMANCE............................................................................................................. 14 4.12MANAGEABILITY.......................................................................................................... 15 4.13TRANSACTION..............................................................................................................16 5DATA MODEL.............................................................................................................. 17 5.1THREE MAIN TABLES..................................................................................................... 17 5.2SUPPORTING TABLES.......................................................................................................18 6OSS/J IMPLEMENTATION........................................................................................23 6.1THE JVTTROUBLETICKETSESSION INTERFACE................................................................... 23 6.2EXTENDING OSS/J: THE QUERYTROUBLETICKETHISTORYVALUE INTERFACE......................... 25 6.3THE XMLSERIALIZER INTERFACE...................................................................................... 25 6.4THE TROUBLETICKETKEY INTERFACE............................................................................... 26 6.5OTHER SUPPORTING INTERFACES...................................................................................... 26 6.6THE REQUIRED FIELD PROPERTY FILE...............................................................................27 6.7OSS/J ATTRIBUTES TO DATABASE FIELD/TABLE MAPPING................................................. 28 6.8JVTTROUBLETICKETSESSIONBEAN IMPLEMENTATION......................................................... 30 6.9XVTREPLYMDB IMPLEMENTATION................................................................................ 31 6.10JVTEVENTMDB IMPLEMENTATION............................................................................... 32 6.11TROUBLETICKETTIMERSERVICE IMPLEMENTATION.............................................................32 6.11.1Configuration File for the Timer Service.........................................................33 6.11.2The Procedures for the Timer Service............................................................. 33 v1.1.2 3

7ILEC TROUBLE TICKET GATEWAY IMPLEMENTATION............................. 35 7.1STANDARD T1M1 TO OSS/J MAPPING........................................................................... 35 7.2ILEC SPECIFIC PROPERTY.............................................................................................. 36 7.3ILEC SPECIFIC MAPPING FILE........................................................................................ 36 7.4ILEC SPECIFIC COMMUNICATION PROPERTY..................................................................... 36 7.5CONSUME MESSAGES FROM COVAD TROUBLE TICKET SYSTEM............................................ 37 7.6RECEIVE RESPONSES FROM ILEC TROUBLE TICKET SYSTEM............................................... 37 7.7RECEIVE EVENT NOTIFICATIONS FROM ILEC TROUBLE TICKET SYSTEM................................41 8USE CASE REALIZATION.........................................................................................43 8.1CREATE A TROUBLE TICKET............................................................................................ 43 8.1.1Technicians Interactions with TT-Application................................................. 43 8.1.2Sequence Diagram............................................................................................. 43 8.1.3What Happens behind the Scene........................................................................44 8.2QUERY A TROUBLE TICKET STATUS/INFORMATION..............................................................45 8.2.1Technicians Interaction with TT-Application...................................................45 8.2.2Sequence Diagram............................................................................................. 45 8.3CANCEL A TROUBLE TICKET............................................................................................ 46 8.3.1Technicians Interaction with TT-Application...................................................46 8.3.2Sequence Diagram............................................................................................. 46 8.3.3What Happens behind the Scene........................................................................47 8.4VIEW A TROUBLE TICKET HISTORY.................................................................................. 48 8.4.1Technicians Interaction with TT-Application...................................................48 8.4.2Sequence Diagram............................................................................................. 48 8.5ESCALATE A TROUBLE TICKET......................................................................................... 49 8.5.1Technicians Interactions with TT-Application................................................. 49 8.5.2Sequence Diagram............................................................................................. 49 8.5.3What Happens behind the Scene........................................................................50 8.6MODIFY A TROUBLE TICKET............................................................................................51 8.6.1Technicians Interaction with TT-Application...................................................51 8.6.2Sequence Diagram............................................................................................. 52 8.6.3What Happens behind the Scene........................................................................52 8.7VERIFY REPAIR COMPLETION/CLOSE A TROUBLE TICKET.....................................................53 8.7.1Technicians Interaction with TT-Application...................................................53 8.7.2Sequence Diagram............................................................................................. 54 8.7.3What Happens behind the Scene........................................................................54 9IMPACTS ON EXISTING SYSTEM.......................................................................... 56

v1.1.2

INTRODUCTION

This architecture document addresses the issues regarding electronically bonding Covad with various ILECs for trouble ticket creation, status query, escalation, cancellation, modification in ILEC trouble ticket systems. Problems with the existing way to interact with ILECs regarding trouble ticket include: 1. It is a manual process. So it is time-consuming, error prone, and very inefficient. 2. No unified tools or interfaces to work with for different ILECs. 3. Highly depended on ILEC trouble ticket system. When ILEC trouble ticket system is taken down for maintenance, no action towards ILEC trouble ticket system is possible. This design addresses all these problems. Reference Document 1. Use case document: Electronic bonding use case document: http://docushare/View/Collection-2386 by Alex Leong 2. T1M1 Standards: http://docushare/View/Collection-2528 3. OSS/J Specification: http://jcp.org/en/jsr/detail?id=91

v1.1.2

2
2.1

INDUSTRY STANDARDS
T1M1 Standard

The Standard Committee T1-Telecommunications has a series of standards that specify interface requirements between Operation Systems across jurisdictional boundaries. One of the standards is regarding trouble administration. This trouble administration standard defines trouble administration functions between two TMNs (Telecommunication Management Network), trouble ticket attributes, and object classes. The underlying communication protocol is CMIP/CMISE. The functions are: 1. Enter trouble report 2. Request trouble report status 3. Request trouble report format 4. Trouble history event 5. Review trouble history 6. Add trouble information 7. Trouble report status update 8. Trouble report commitment time update 9. Trouble report attribute value change 10. Enroll trouble report 11. De-enroll trouble report 12. Verify repair completion 13. Modify other trouble report attributes 14. Enroll trouble report format definition 15. De-enroll trouble report format definition 16. Attribute value change trouble report format definition 17. Trouble report progress update 18. Cancel trouble report There are 95 attributes defined for trouble ticket administration. The attribute definitions are described using ASN.1. The object classes are defined in GDMO (Guidelines for the Definition of Managed Objects). For more information, please refer the standard documents.

v1.1.2

2.2

OSS/J

OSS/J stands for OSS through Java Initiative, an initiative started by a working group of industry leaders including Sun Microsystems, BEA, IBM Business Consulting Services, MetaSolv, Nokia, Motorola, Nortel, NEC, etc to define and implement an open standard set of APIs using Java technology for Operations Support Systems (OSS) and Business Support Systems (BSS). OSS/J covers many OSS areas including: trouble ticket, customer management, order management, workforce management, billing, etc. For trouble ticket, OSS/J defines: 1. Trouble Ticket EJB Session Interface: JVTTroubleTicketSession. 2. XML based request/response messages. 3. Java object based events and XML string based events. 4. A XVTMessageQueue for XML message, and two topics: XVTEventTopic for XML event, JVTEventTopic for Java Event Object. The OSS/J trouble ticket API is finalized in February, 2002. For more information regarding OSS/J, go to: http://jcp.org/en/jsr/detail?id=91 2.3 OSS/J vs T1M1 Standard

There has been a slow acceptance of the use T1M1 standards as an implementation technology for managing equipment and networks because of the following reasons: 1. CMIP and its underlying OSI stack are heavyweight. 2. The syntax used by ASN.1 and GDMO bears little relationship to OO programming languages. The object-oriented information models defined by CMIP, GDMO, and ASN.1 do not map easily into object-oriented programming languages either. 3. All the definitions provided by T1M1 standards are very complicated. OSS/J does not have these shortcomings, but on the other hand, it has its own limitations: 1. It is not defined as rigid as T1M1 is for trouble administration. For example, T1M1 clearly defines what attributes are required, what attributes are provided by manager, what attributes are provided by agent. OSS/J trouble ticket API specification does not address this issue at all. 2. Although it captures the most important part of T1M1, there are some mandatory information missing from OSS/J specification, like the following two attributes: a. TroubleReportFormatObjectPtr b. TroubleReportStatusWindow These two attributes are required for the trouble administration communication with ILECs. 3. It does not address history/log issue.

v1.1.2

Even with these limitations, it is still the best technology we can have given our Java environment. Furthermore these OSS/J limitations can be overcome using other means.

v1.1.2

THE EXISITING COVAD TROUBLE TICKET SYSTEM

Covad Trouble Ticket System
t3 t3 TT-System

TT-Application (GUI)
TT-Application (GUI)

OSSO : Database CFI

CFI t3/GLUE TT-CFI TT-WFM JDBC TT

FMS
FMS

t3/GLUE

Current Covad trouble ticket system allows its users to create, view, update, and track trouble ticket within Covad systems. When a trouble ticket involves ILECs, manual process is needed to resolve issues with ILECs.

v1.1.2

4
4.1

THE NEW COVAD TROUBLE TICKET SYSTEM

Deployment View: the Big Picture

CFI
CFI t3/GLUE

TT-CFI

Covad Trouble Ticket System

TT-WFM t3/GLUE TT-System

FMS
FMS JVTTroubleTicketSessionBean ILEC Trouble Ticket TroubleTicketTimerService TroubleTicketLocalEntityBean

t3

TT-Application (GUI)
TT-Application (GUI) t3/Glue

SbcXVTReplyMDB

SbcJVTEventMDB

VerizonJVTEventMDB JMS

VerizonXVTReplyMDB

SbcXVTMessageQueue

Weblogic JMS Server

VerizonXVTMessageQueue

OSSO : Database
TT ILEC_TT

SbcXVTMessageReplyQueue

VerizonXVTMessageReplyQueue

SbcJVTEventTopic

VerizonJVTEventTopic

ILEC_TT_MSG

Firewall

JMS

JMS

SBC Trouble Ticket Gateway

Verizon Trouble Ticket Gateway

MessageReceiver MessagePublisher MessageSender

MessageReceiver

MessageSender

MessagePublisher

Ossj2SbcConverter

Sbc2OssjConverter

Ossj2VerizonConverter

Verizon2OssjConverter

Monfox.MOHandle

Monfox.MOHandle

CMIP

CMIP

SBC Trouble Ticket System

SBC

Verizon Trouble Ticket System

Verizon

v1.1.2

10

4.2

Notes on the Deployment View

The ILEC Trouble Ticket component contains one session bean, two message driven beans, and several local entity beans (only the trouble ticket local entity bean shown in the deployment view). When we use Weblogic Application server, the Weblogic JMS server is part of the Application server. So these beans and the queues, one topic will be running in one JVM. Although different nodes are shown for different gateway for ILECs, these gateways can run on the same machine. 4.3 Design Rationale

The current design is based on the following rationales. 1. OSS/J, instead of T1M1 standard, is the right technology to go with. Since ILECs are using T1M1 standards, we will use both OSS/J and T1M1 standard, but T1M1 is used behind OSS/J. 2. We will not fully implement OSS/J specification. We only implement the part necessary for this project. 3. To avoid tightly coupled with ILEC trouble ticket system, we introduce a JMS server in the middle. This JMS server also shields Covad trouble ticket system from the ILEC trouble ticket maintenance schedule. 4. To achieve isolation for ILEC (such as changes for one ILEC should not affect communication with other ILEC), each gateway runs on its on JVM, i.e. different gateways run on different JVMs. The other benefits are that gateway is more scalable and robust. 5. Only TAC can create ILEC trouble ticket through TT GUI. 4.4 Emphasis on Covad MTTR

Currently Covad creates total around 320 trouble tickets for all ILECs per day, one JMS server with two queues and one topic should be able to handle this load. To minimize Covad MTTR, 1. We introduce one message queue, one message reply queue, and one event topic for each master ILEC (like SBC, Verizon, etc., not for baby ILEC like AmeriTech). This not only increases the processing speed, but prevents messages designated for the ILEC, which is not on line, from blocking messages designated for other ILECs. 2. The trouble ticket creation request message will be have higher priority than other request messages. Although Message-driven beans can have instance pools provided by EJB container, theoretically, one message reply queue and one event topic for all ILECs should be enough. Based on the following reasons, we decide separate the message reply queue and event topic for different ILECs.

v1.1.2

11

1. To maintain the event order, we need to set the message driven bean instance pool size to 1. Event order sometimes is important, considering two update messages/events, we want the database updates in right order. 2. Because the pool size is 1, we cannot take advantage of instance pool. The MDBs could be the trouble ticket processing bottleneck. 4.5 Overview of New EJB Components 1. Session Bean JVTTroubleTicketSessionBean: The bean implements all the business functions defined in JVTTroubleTicketSession interface of OSS/J trouble ticket API. It is also the single entry point to the new trouble ticket system. We have much more to say about this bean in later sections. 2. Message-Driven Bean XVTReplyMDB: this message-driven bean consumes all messages (XML messages) from XVTMessageReplyQueue. Messages are either the Response or Exception types of messages defined by OSS/J. They are: a. createTroubleTicketByValueResponse b. createTroubleTicketByValueException c. setTroubleTicketByValueResponse d. setTroubleTicketByValueException e. cancelTroubleTicketsByTemplateResponse f. cancelTroubleTicketsByTemplateException g. escalateTroubleTicketsByTemplateResponse h. escalateTroubleTicketsByTemplateException i. closeTroubleTicketsByTemplateResponse j. closeTroubleTicketsByTemplateException It will call local entity beans to update database. 3. Message-Driven Bean JVTEventMDB: this message-driven bean consumes all messages (Java Object messages) from JVTEventTopic. Messages are those notification events defined by OSS/J. They are a. TroubleTicketCreateEvent b. TroubleTicketCloseOutEvent c. TroubleTicketAttributeValueChangeEvent d. TroubleTicketCancellationEvent e. TroubleTicketStatusChangeEvent This component will call local entity beans to update database. 4. Local Entity Beans: we need local entity beans for those tables specified in the data model section. CMP together with cmr fields should be used for these entity beans. v1.1.2 12

4.6

Overview of JMS Queue/Topic Components

In the JMS server, we will have one message queue per ILEC, and one message reply queue, one topic for all ILECs. 1. XVTMessageQueue: this queue is for all XML request messages to ILEC trouble ticket System. 2. XVTMessageReplyQueue: this queue is for XML response/exception messages from ILEC trouble ticket system. 3. JVTEventTopic: this is for Java notification message from ILEC trouble ticket system. All the messages sent to the queues are mandatory to set the following properties: 1. OSS_MESSAGE_TYPE: REQUEST, RESPONSE, or EXCEPTION. 2. OSS_MESSAGE_NAME: The name of the operation, like createTroubleTicketByValueRequest. 3. OSS_APPLICATION_TYPE: we can use Trouble Ticket 4. OSS_REQUEST_SENDER_ID: we can use Covad 5. OSS_REPLY_SENDER_ID: use ILEC name 6. OSS_REPLYTO_DESTINATION_TYPE: use value QUEUE Beside these properties, for our application, we need to define one more property: 7. ILEC_TROUBLETICKET_NUMBER All the events published to the topic are mandatory by OSS/J to set the following properties: 1. OSS_EVENT_TYPE: the fully qualified event name 2. OSS_APPLICATION_DN: ILEC name Beside these properties, we also need to define the following property for the event: 3. ILEC_TROUBLETICKET_NUMBER Also the JMSDeliveryMode for both messages and events are PERSISTENT. 4.7 Overview of the Timer Service

The timer service is a Weblogic startup object. At its startup time, it will create a timer. On pre-configured interval, this timer will keep sending out XML request message to XVTMessageQueue to query ILEC trouble ticket systems for the latest trouble ticket information. The returned information is used to update the Covad database. By using this timer service, Covad database has almost real time information about ILEC trouble tickets created by Covad. More details in the later section. 4.8 Overview of ILEC Trouble Ticket Gateway

The gateway process accomplishes the following: v1.1.2 13

1. Receive XML messages from XVTMessageQueue. 2. Convert between OSS/J XML message and ILEC required values. 3. Use 3rd party library to send and receive CMIP data. 4. Generate TroubleTicketKey for successful creation request. 5. Publish XML messages to XVTMessageReplyQueue and Java Event to JVTEventTopic. 6. Receive ILEC event notifications. In the deployment diagram, we use MessageReceiver, MessageSender, MessagePublisher, Ossj2IlecConverter, Ilec2OssjConverter, and MOHandle class to illustrate the steps needed in the gateway. In the actual implementation, you may not have exactly the same classes. The ILEC trouble ticket gateway system is an independent Java process. 4.9 Security 1. The security for accessing the session bean. 2. The security for accessing queues and topic 3. The security for communicating with ILECs. The first two will be handled in role based EJB way. The last one will follow the T1M1 standard, using encryption. We only need to configure the 3rd party product (Monfox), store the encryption key in proper location, Monfoxs library will handle the secure handshaking with ILECs. 4.10 Scalability Current design should be more than enough for the current load, and even modest increase of the load. If load increases dramatically, we can scale beans, queues, and topics side by clustering Weblogic server. On the gateway size, we can bring up more instances, and divide the loads among these instances, like one instance only dealing with trouble ticket creation, etc. This can be easily done through JMSs message selector mechanism. 4.11 Performance OSS/J defines queues for XML message, topics for both XML messages and Java object message, but does not define Java message for queues. To confirm with this standard, we need to serialize the Java object into XML message, and later on need to parse this XML message to retrieve data out, which essentially is to deserialize the XML message. Although all these operations are performed in memory, it does have performance penalty. However we do not believe the penalty is high.

There are three security aspects for this system.

v1.1.2

14

If the performance is an issue, we could use Java object message instead of XML message, use a new queue for Java object message to replace the current XML message queue. Current design to use Java object message rather than XML message for the notification is mainly due to performance consideration. 4.12 Manageability The ILEC Trouble Ticket Gateway is implemented as a standalone Java process. There are concerns regarding these gateways: 1. How do we monitor them? 2. These gateways are not built on top on some type of platform. Examples of platforms are: J2EE, CORBA, etc. These are good concerns. But the key functionality of the gateway is to communicate ILEC trouble ticket system through CMIP protocol, which makes the gateway impossible to be built on top of the popular platforms like J2EE and CORBA. There are ways to address these concerns: One way is to use another Java technology called JMX: 1. Wrap each gateway into a MBean, and expose functions like: start, stop, statistic info, and notification support. 2. Write a simple console as the management application, for example, a simple Web client. By doing this, you can achieve the following. 1. All the gateways are built on JMXs Distributed/Agent/Instrumentation layer framework. 2. Gateway can be easily plugged into the framework. 3. Gateway can be monitored. One downside of this approach is more development work needed. Beside the MBean implementation, the protocol adapter in the distributed layer is also needed to be implemented although Sun Microsystem does have a reference implementation which provides a HTML adapter. The other way is to use J2EE connector architecture. The new JCA 1.5 defines a new set of system-level contracts between an application server and enterprise information system. They include: lifecycle management contract, work management contract, etc. These new contracts make the resource adapters manageable through application administration console. The current JCA 1.5 is in proposed final draft 2 stage. The implementation of the resource adapter will be more complicated in this case. For the phase 1, the standalone process should be good enough. JMX approach or JCA approach could be taken for the future enhancements.

v1.1.2

15

4.13 Transaction Whenever a persist JMS message is involved in a transaction, this transaction will almost involves multiple database writes. These writes are across different schemas, but in our case, these schemas reside in the same database. Even with this situation, there are concerns about the transaction being a distributed transaction. Based on the following reasons, we still make JVTTroubleTicketSessionBean and message-driven beans transactional: 1. We dont want to introduce our own mechanism to handle multiple database writes and enforce data integrity. 2. There are no multiple application server instances involved. 3. The scenarios we deal with here are relatively simple comparing with other distributed transactions we have seen in the past. It is not truly distributed as all the database writes occur in the same database (but different schemas). Weblogic server should be able to handle these simple cases. However, for the sessions used in the ILEC trouble ticket Gateway systems, they are nontransactional because the actual communications with ILEC could be time-consuming. We may need some manual processes to resolve some data issues.

v1.1.2

16

DATA MODEL

We need to store ILEC trouble ticket information in Covad database and keep the activity history around a trouble ticket. Although currently we do model ILEC trouble ticket information in our database, the current one is not good enough. Note: the following table structure does not show the primary key field, nor the audit fields. 5.1 Three Main Tables

TT_ILECINFO: this is an existing table. New attributes are added into this table to store eBonding information about ILEC trouble tickets. TT_ILECINFO_HISTORY: this table stores all information about ILEC trouble tickets, including all the activities associated with trouble tickets. EBOND_TT_COVAD_WORKLOG: this table stores all the actions taken by Covad. In addition to the existing attributes, both TT_ILECINFO and TT_ILECINFO_HISTORY should contain the following eBonding attributes: Field Name Using Ebonding Flag Troubled Object Identifier Trouble Type ID Additional Trouble Info Covad Trouble Ticket Num Covad Contact Person ID ILEC Name ILEC Trouble Ticket Num ILEC Received Time Trouble State ID Trouble Status ID Trouble Status Time Additional Trouble Status Info Trouble Found ID ILEC Contact Person ID Cancel Requested By Covad Flag Close Out Narrative Close Out Verification ID Maintain Service Charge Covad TT Clearance Person Id Commitment Time Type Varchar2(1) Varchar2(40) Notes Y/N Can be carrier circuit number or telephone number Number Enum Varchar2(512) Standard requires minimum 256 Number Number FK Varchar2(30) Already exists (ILEC_NAME) Varchar2(40) Already exists (ILEC_TICKET_NUM) Date Already exists (ILEC_CONTACTED_AT) Number Enum Number Enum Date Varchar2(512) Number Enum Number FK Varchar2(1) Varchar2(256) Number Enum Varchar2(1) Number FK Date Already exists (ILEC_COMMIT_TIME) 17

v1.1.2

Outage Years Outage Months Outage Days Outage Hours Outage Minutes Outage Seconds Commitment Time Requested Initiating Mode ID Trouble Detection Time Perceived Trouble Severity ID Preferred Priority ID Repeat Report ID Date Created Created By Date Modified Modified By

Number Number Number Number Number Number Date Number Date Number Number Number Date Varchar2(30) Date Varchar2(30)

Enum Enum Enum Enum Audit Column Audit Column Audit Column Audit Column

EBOND_TT_COVAD_WORKLOG should contain the following fields: Field Name Ebond TT Covad Worklog ID ILEC_INCIDENT_ID Covad Trouble Ticket Num ILEC Trouble Ticket Num Operation Name Operation Attribute Value Operation Status Operation Error Message Date Created Created By Date Modified Modified By 5.2 Supporting Tables Type Varchar2(30) Number(10) Varchar2(50) Varchar2(8) Date Varchar2(30) Notes PK PK ACTIVE/INACTIVE Audit Column Audit Column Type Number(10) Number Number Varchar2(40) Varchar2(30) Varchar2 (2048) Varchar2(1) Varchar2 (256) Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. FK to TT_ILECINFO table.

Success/Fail/Queued Audit Column Audit Column Audit Column Audit Column

EBOND_LOOKUP: this ENUM table stores all the eBonding enum lookup values: Fields Type Ebond Lookup ID Value Status Date Created Created By

v1.1.2

18

Date Modified Modified By

Date Varchar2(30)

Audit Column Audit Column

EBOND_ILEC_PERSON_REACH: this table stores the ILEC persons contact information. It should contain the following fields: Fields Ebond Ilec Person Reach ID Email Name Organization Name Fax Phone Area Code Phone Prefix Phone Suffix Phone Extension Responsible Street Address City State Zip Date Created Created By Date Modified Modified By Type Number(10) Varchar2(40) Varchar2(40) Varchar2(20) Varchar2(30) Varchar2(3) Varchar2(3) Varchar2(4) Varchar2(5) Varchar2(64) Varchar2(64) Varchar2(30) Varchar2(30) Varchar2(10) Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. Email+Name Business Key Email+Name Business Key

Audit Column Audit Column Audit Column Audit Column

EBOND_COVAD_SUPPORT_CONTACT: this table stores the COVAD support contact information. It should contain the following fields: Fields Ebond Covad Support Contact ID Parent Carrier ID Covad Support Email Dist List Covad Support Phone Number Date Created Created By Date Modified Modified By Type Number(10) Varchar2(100) Varchar2(20) Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. FK Audit Column Audit Column Audit Column Audit Column

EBOND_COVAD_PERSON_REACH: this table stores the COVAD persons contact information. It should contain the following fields: Fields Ebond Covad Person Reach ID Ebond Covad Support Contact ID Covad OSS TT Login Name v1.1.2 Type Number(10) Varchar2(32) Varchar2(40) Notes PK. Oracle Sequence. FK

19

Date Created Created By Date Modified Modified By

Date Varchar2(30) Date Varchar2(30)

Audit Column Audit Column Audit Column Audit Column

EBOND_TT_AUTHORIZATION: this table stores whether authorization is requested by ILEC and granted by Covad. It should contain the following fields: Fields Ebond TT Authorization ID ILEC_INCIDENT_ID Activity Type id Covad Authorization Person ID Authorization Time Request State ID Date Created Created By Date Modified Modified By Type Number(10) Number Number(10) Number Date Number Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. FK enum FK enum (requested, provided, denied) Audit Column Audit Column Audit Column Audit Column

EBOND_TT_ESCALATION: this table stores what escalation has happened to one trouble ticket. It should contain the following fields: Fields Ebond TT Escalation ID ILEC_INCIDENT_ID ILEC Escalation Person ID Escalation Time Escalation Level ID Covad Request Person ID Request State ID Date Created Created By Date Modified Modified By Type Number(10) Number Number Date Number Number Number Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. FK FK enum FK enum Audit Column Audit Column Audit Column Audit Column

EBOND_TT_ACTIVITY_DURATION: this table stores duration for all the activities associated with a trouble ticket. It should contain the following fields. Fields Ebond TT Activity Duration ID ILEC_INCIDENT_ID Activity Type ID Billable Flag Duration In Years v1.1.2 Type Number(10) Number Number Varchar2(1) Number Notes PK. Oracle Sequence. FK enum Y/N

20

Duration In Months Duration In Days Duration In Hours Duration In Minutes Duration In Seconds Date Created Created By Date Modified Modified By

Number Number Number Number Number Date Varchar2(30) Date Varchar2(30)

Audit Column Audit Column Audit Column Audit Column

EBOND_TT_ACCESS_HOUR: this table stores the access hours for the troubled object and for the troubled location. It should contain the following fields: Fields Ebond TT Access Hour ID ILEC_INCIDENT_ID Day of Week Begin Hour Begin Minute Begin Second End Hour End Minute End Second Troubled Type ID Date Created Created By Date Modified Modified By Type Number (10) Number Number Number Number Number Number Number Number Number Date Varchar2(30) Date Varchar2(30) Notes PK. Oracle Sequence. FK Look up value (Sunday,, Saturday)

enum (Location or Object) Audit Column Audit Column Audit Column Audit Column

Note for a given day of week, you can have a list of begin time and end time. We could break the above table into two for database normalization. EBOND_TT_ACCESS_LOCATION: this table stores the trouble location information. It should contain the following fields. Fields Ebond TT Access Loaction ID ILEC_INCIDENT_ID Premise Name Premise Street Address Premise City Premise State Premise Zip Location Type Date Created Type Number(10) Number Varchar2(64) Varchar2(64) Varchar2(30) Varchar2(30) Varchar2(10) Varchar2(1) Date Notes PK. Oracle Sequence. FK

A or Z Audit Column

v1.1.2

21

Created By Date Modified Modified By

Varchar2(30) Date Varchar2(30)

Audit Column Audit Column Audit Column

v1.1.2

22

OSS/J IMPLEMENTATION

OSS/J trouble ticket API is just a specification. This specification defines everything in terms of interfaces. We need to have our own implementation. Fortunately we only need to implement part of the OSS/j, and there is a reference implementation available for free download. We could use this reference implementation as our guideline. Here is a list (not complete) of interfaces we need to implement. 6.1 The JVTTroubleTicketSession Interface

OSS/J defines the following operations in the JVTTroubleTicketSession interface: 1. Get a single trouble ticket 2. Get multiple trouble tickets 3. Set a single trouble ticket 4. Set multiple trouble tickets 5. Create a single trouble ticket 6. Create multiple trouble tickets 7. Close a single trouble ticket 8. Close multiple trouble tickets 9. Cancel a single trouble ticket 10. Cancel multiple trouble tickets 11. Escalate a single trouble ticket 12. Escalate multiple trouble tickets For operations involving multiple trouble tickets, OSS/J defines two bulk types: Best Effect and Atomic Bulk. Precisely, the JVTTroubleTicketSession interface is:

v1.1.2

23

JVTTroubleTicketSession +cancelTroubleTicketByKey( troubleticketkey : TroubleTicketKey, i : int, s : String ) : void +cancelTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], i : int, s : String ) : void +cancelTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, i : int, s : String ) : void +cancelTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], i : int, s : String ) : void +closeTroubleTicketByKey( troubleticketkey : TroubleTicketKey, i : int, s : String ) : void +closeTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], i : int, s : String ) : void +closeTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, i : int, s : String ) : void +closeTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], i : int, s : String ) : void +createTroubleTicketByValue( troubleticketvalue : TroubleTicketValue ) : TroubleTicketKey +createTroubleTicketsByValues( atroubleticketvalue : TroubleTicketValue[] ) : TroubleTicketKey[] +escalateTroubleTicketByKey( troubleticketkey : TroubleTicketKey, escalationlist : EscalationList ) : void +escalateTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], escalationlist : EscalationList ) : void +escalateTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, escalationlist : EscalationList ) : void +escalateTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], escalationlist : EscalationList ) : void +getTroubleTicketByKey( troubleticketkey : TroubleTicketKey, as : String[] ) : TroubleTicketValue +getTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], as : String[] ) : TroubleTicketValue[] +getTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, as : String[] ) : TroubleTicketValueIterator +getTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], as : String[] ) : TroubleTicketValueIterator +makeTroubleTicketValue( s : String ) : TroubleTicketValue +queryTroubleTickets( queryvalue : QueryValue, as : String[] ) : TroubleTicketValueIterator +setTroubleTicketByValue( troubleticketvalue : TroubleTicketValue, flag : boolean ) : void +setTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], troubleticketvalue : TroubleTicketValue ) : void +setTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, troubleticketvalue1 : TroubleTicketValue ) : void +setTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], troubleticketvalue : TroubleTicketValue ) : void +setTroubleTicketsByValues( atroubleticketvalue : TroubleTicketValue[], flag : boolean ) : void +tryCancelTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], i : int, s : String ) : TroubleTicketKeyResult[] +tryCancelTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, i : int, s : String, flag : boolean ) : TroubleTicketKeyResultIterator +tryCancelTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], i : int, s : String, flag : boolean ) : TroubleTicketKeyResultIterator +tryCloseTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], i : int, s : String ) : TroubleTicketKeyResult[] +tryCloseTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, i : int, s : String, flag : boolean ) : TroubleTicketKeyResultIterator +tryCloseTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], i : int, s : String, flag : boolean ) : TroubleTicketKeyResultIterator +tryCreateTroubleTicketsByValues( atroubleticketvalue : TroubleTicketValue[] ) : TroubleTicketKeyResult[] +tryEscalateTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], escalationlist : EscalationList ) : TroubleTicketKeyResult[] +tryEscalateTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, escalationlist : EscalationList, flag : boolean ) : TroubleTicketKeyResultIterator +tryEscalateTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], escalationlist : EscalationList, flag : boolean ) : TroubleTicketKeyResultIterator +trySetTroubleTicketsByKeys( atroubleticketkey : TroubleTicketKey[], troubleticketvalue : TroubleTicketValue ) : TroubleTicketKeyResult[] +trySetTroubleTicketsByTemplate( troubleticketvalue : TroubleTicketValue, troubleticketvalue1 : TroubleTicketValue, flag : boolean ) : TroubleTicketKeyResultIterator +trySetTroubleTicketsByTemplates( atroubleticketvalue : TroubleTicketValue[], troubleticketvalue : TroubleTicketValue, flag : boolean ) : TroubleTicketKeyResultIterator +trySetTroubleTicketsByValues( atroubleticketvalue : TroubleTicketValue[], flag : boolean ) : TroubleTicketKeyResult[]

Based on the use case document, we need only to support operations on a single trouble ticket. Here is the list of operations we need to implement. For the rest operations, we can just put empty function body.
JVTTroubleTicketSessionBean +cancelTroubleTicketsByTemplate( troubleTicketValue : TroubleTicketValue, statue : int, closeOutNarr : String ) : void +closeTroubleTicketsByTemplate( troubleTicketValue : TroubleTicketValue, status : int, closeOutNarr : String ) : void +createTroubleTicketByValue( troubleTicketValue : TroubleTicketValue ) : TroubleTicketKey +escalateTroubleTicketsByTemplate( troubleTicketValue : TroubleTicketValue, escalationlist : EscalationList ) : void +getTroubleTicketsByTemplate( troubleTicketValue : TroubleTicketValue, attrNames : String[] ) : TroubleTicketValueIterator +queryTroubleTickets( queryValue : QueryValue, attrNames : String[] ) : TroubleTicketValueIterator +setTroubleTicketByValue( troubleTicketValue : TroubleTicketValue, resyncRequired : boolean ) : void

Note: The following operations were designated by OSS/J for multiple trouble tickets: 1. cancelTroubleTicketsByTemplate 2. closeTroubleTickesByTemplate 3. escalateTroubleTicketsByTemplate 4. getTroubleTicketsByTemplate We choose these operations instead of the following operations designated by OSS/J for single trouble ticket: 1. cancelTroubleTicketByKey 2. closeTroubleTicketByKey 3. escalateTroubleTicketByKey v1.1.2 24

4. getTroubleTicketByKey The reason is that these ByKey operations parameters are too restrictive to prevent us to pass necessary information. For example, for the cancel trouble ticket case, the cancelTroubleTicketByKey does not have place for us to pass the trouble clearance person information, but with cancelTroubleTicketsByTemplate, we can pass this piece information in troubleTicketValue parameter. We need to make sure that the troubleTicketValue input parameter contains troubleTicketKey for cancelTroubleTicketsByTemplate, closeTroubleTicketsByTemplate and escalateTroubleTicketsByTemplate. So effectively, we still deal with single trouble ticket. 6.2 Extending OSS/J: the QueryTroubleTicketHistoryValue Interface

OSS/J defines a base interface QueryValue for generic attribute accessor. OSS/J also defines QueryAllOpenTroubleTicketsValue, QueryByEscalationValue sub-interfaces. None of the existing interfaces can satisfy the need to query the history value for a trouble ticket. We define QueryTroubleTicketHistoryValue interface for this purpose.
QueryValue

QueryTroubleTicketHistoryValue +getCovadTroubleTicketNumber() : int +getTroubleTicketKey() : TroubleTicketKey +setCovadTroubleTicketNumber( int ) : void +setTroubleTicketKey( troubleTicketKey : TroubleTicketKey ) : void

We will only support this interface in the queryTroubleTickets operation. 6.3 The XmlSerializer Interface

This interface marshals and un-marshals a Java object to and from XML.
XmlSerializer +fromXml(element : org.w3c.dom.Element) : Object +toXml( object : Object, elementName : String ) : String

This interface is relevant to us because we need to generate XML message from a trouble ticket value (Java object), and also the other way around. Both marshalling and unmarshalling should be done in conform to the XML schema defined by OSS/J.

v1.1.2

25

6.4

The TroubleTicketKey Interface

ManagedEntityKey

+getApplicationContext() : ApplicationContext +getApplicationDN() : String +getPrimaryKey() : Object

...

TroubleTicketKey +getTroubleTicketPrimaryKey() : String +setTroubleTicketPrimaryKey( s : String ) : void

For a trouble ticket key, it basically contains three pieces of information: 1. A primary key 2. An application DN 3. An application context The primary key will be the ILEC trouble ticket number. The application DN is the DN of the application JNDI naming context. The application context is used to locate the application components in charge of the managed entity. Both application DN and application context are only interested to the calling application (like the TT-Application GUI). These two pieces of information should be specified in the ejb-jar.xml file. When we generate a TroubleTicketKey, we only need to set its primaryKey, the other two can be set to null. 6.5 Other Supporting Interfaces

There are many other interfaces we need to implement. Here are some examples.
TroubleTicketValue +getAccountOwner() : PersonReach +getActivityDurationList() : ActivityDurationList +getAdditionalTroubleInfoList() : String[] +makeAlarmValueList() : AlarmValueList +makeAuthorization() : Authorization +makeCustomerRoleAssignment() : CustomerRoleAssignment +makeEscalation() : Escalation +setCloseOutVerification( i : int ) : void +setCommitmentTime( date : Date ) : void +setCommitmentTimeRequested( date : Date ) : void
...

v1.1.2

26

TroubleTicketValueIterator +getNextTroubleTickets( i : int ) : TroubleTicketValue[]

Escalation +clone() : Object +getEscalationPerson() : PersonReach +getEscalationTime() : Date +getLevel() : int +getRequestPerson() : PersonReach +getRequestState() : int +setEscalationPerson( personreach : PersonReach ) : void +setEscalationTime( date : Date ) : void +setLevel( i : int ) : void +setRequestPerson( personreach : PersonReach ) : void +setRequestState( i : int ) : void

EscalationList +add( aescalation : Escalation[] ) : void +get() : Escalation[] +make( i : int ) : Escalation[] +remove( aescalation : Escalation[] ) : void +set( aescalation : Escalation[] ) : void

6.6

The Required Field Property File

This required.xml file is to specify what attributes are required for a given operation. It takes the following format: <Operation_Required_Info> <Operation> <Operation_Name></Operation_Name> <Required_Fields> <Required_Field></Required_Field> </Required_Fields> </Operation> </Operation_Required_Info> This xml file will be parsed once when the session bean is created. Here is just a potion of the file: <Operation> <Operation_Name>createTroubleTicketByValue</Operation_Name> v1.1.2 27

<Required_Parameters> <Required_Parameter>TroubledObject</Required_Parameter> <Required_Parameter>TroubledType</Required_Parameter> <Required_Parameter>AdditionalTroubleInfoList</Required_Parameter> <Required_Parameter>TroubleSystemDN</Required_Parameter> <Required_Parameter>CustomerTroubleNum</Required_Parameter> <Required_Parameter>AuthorizationList</Required_Parameter> <Required_Parameter>TroubleLocationInfoList</Required_Parameter> <Required_Parameter>TroubledObjectAccessHoursList</Required_Parameter> <Required_Parameter>CustomerRoleAssignmentList</Required_Parameter> </Required_Parameters> </Operation> This file is for basic nullity checking. The parameter name is conformed to OSS/J TroubleTicketValue interface. Some of the parameters are composite. We could extend this xml file to the level that what fields in the composite attribute are required. For example, Authorization contains request state, activity type, authorization time, authorization person fields, but only the first two are required. We can express this requirement as follows: <Composite_Required_Parameter> <Composite_Parameter_Name>AuthroizationList</Composite_Parameter_Name> <Required_Parameter>RequestState</Required_Parameter> <Required_Parameter>ActivityType</Required_Parameter> </Composite_Required_Parameter> If we use this composite required parameter tag, the original tag name for AuthorizationList needs to be changed to Composite_Required_Parameter. 6.7 OSS/J Attributes to Database Field/Table Mapping

Not every attribute defined in OSS/J are used. Not every attribute defined in OSS/J has one-to-one mapping to database table field. Here is the mapping from OSS/J attribute to database field/table mapping. OSS/J Attribute accountOwner activityDurationList additionalTroubleInfoList afterHoursRepairAuthority Database Field/Table EBOND_TT_ ACTIVITY_DURATION Additional Trouble Info Not used Note Not used

v1.1.2

28

authorizationList cancelRequestedByCustomer clearancePerson closeOutNarr closeOutVerification commitmentTime commitmentTimeRequested customer customerRoleAssignmentList customerTroubleNum dialog escalationList initiatingMode lastUpdateTime maintServiceCharge originator outageDuration

EBOND_TT_ AUTHORIZATION Cancel Requested By Covad Covad Trouble Clearance Person Id Close Out Narr Close Out Verification Commitment Time Commitment Time Requested Not used Related to Covad Contact Person Id Covad Trouble Ticket Num Not used EBOND_TT_ ESCALATION Initiating mode Not used Maintenance service charge Not used Outage years/months/days/hours/ minutes/seconds Perceived Trouble Severity Preferred Prority ILEC Received Time Not used Not used Not used Repeat Report Restored Time Not used Not used Related to ILEC contact person id Not used Additional trouble status info Trouble Detection Time Trouble Found Not used EBOND_TT_ ACCESS_LOCATION

perceivedTroubleSeverity preferredPriority receivedTime relatedAlarmList relatedTroubleTicketKeyList repairActivityList repeatReport restoredTime serviceUnavailableBeginTime serviceUnavailableEndTime spRoleAssignmentList suspectObjectList troubleDescription troubleDetectionTime troubleFound troubleLocation troubleLocationInfoList

v1.1.2

29

troubleNumList troubledObject troubledObjectAccessFromTime troubledObjectAccessHoursList troubledObjectAccessToTime troubleState troubleStatus troubleStatusTime troubleSystemDN troubleTicketKey

Not used Trouble Object Identifier Not used EBOND_TT_ ACCESS_HOUR Not used Trouble State Trouble Status Trouble Status Time ILEC Name No corresponding table/field, but is used. Related to ILEC trouble ticket num. Trouble Type

troubleType

Notes on CustomerRoleAssignmentList: CustomerRoleAssignmentList is basically an array of CustomerRoleAssignment. CustomerRoleAssignment basically contains two pieces of information: 1. Contact Person Information 2. Role The contact person information will be mapped to Covad contact person. We can hardcoded the Role as Manager. Notes on SPRoleAssignmentList: SPRoleAssignmentList is basically an array of SPRoleAssignment. SPRoleAssignment contains two pieces of information: 1. Contact Person Information 2. Role The contact person information will be mapped to ILEC contact person. We can hardcoded the Role as Agent. 6.8 JVTTroubleTicketSessionBean Implementation

As we mentioned in previous section, JVTTroubleTicketSessionBean needs to implement the following functions: 1. createTroubleTicketByValue: TroubleTicketKey 2. cancelTroubleTicketsByTemplate 3. closeTroubleTicketsByTemplate 4. escalateTroubleTicketsByTemplate 5. setTroubleTicketByValue v1.1.2 30

6. getTroubleTicketsByTemplate 7. queryTroubleTickets The implementation of Functions 1-5 follows the same steps: 1. Generate XML message using XmlSerializer 2. Send the XML message to XVTMessageQueue 3. Persist information to EBOND_TT_COVAD_WORKLOG table For createTroubleTicketByValue function, before it executes the steps above, it creates a record in TT_IECLINFO table with Covad related information. The following table specifies the mapping from the operations to the XML Message. Operation Name createTroubleTicketByValue cancelTroubleTicketsByTemplate closeTroubleTicketsByTemplate escalateTroubleTicketsByTemplate setTroubleTicketByValue XML Message Element createTroubleTicketByValueRequest cancelTroubleTicketsByTemplateRequest closeTroubleTicketsByTemplateRequest escalateTroubleTicketsByTemplateRequest setTroubleTicketByValueRequest

The return value for createTroubleTicketByValue is TroubleTicketKey. Since the ILEC trouble ticket number is unknown at this moment, this function should always return null. For the persistence of EBOND_TT_COVAD_WORKLOG, store the actual XML message element (or attributes name and value pairs) into the Operation Attribute Value field, and set the operation status to Queued. For functions 6-7, we just query our local database. For 7, the Covad trouble ticket number or ILEC trouble ticket number needs to be provided. For 8, only QueryTroubleTicketHistoryValue is required to support. 6.9 XVTReplyMDB Implementation

XVTReplyMDB consumes all the messages from XVTMessageReplyQueue. The following is the complete list of XML messages it needs to handle. 1. createTroubleTicketByValueResponse 2. createTroubleTicketByValueException 3. cancelTroubleTicketsByTemplateResponse 4. cancelTroubleTicketsByTemplateException 5. closeTroubleTicketsByTemplateResponse 6. closeTroubleTicketsByTemplateException 7. escalateTroubleTicketsByTemplateResponse 8. escalateTroubleTicketsByTemplateException 9. setTroubleTicketByValueResponse

v1.1.2

31

10. setTroubleTicketByValueException For all these messages, just update the EBOND_TT_COVAD_WORKLOG table according to whether it is a response message or response message based on Covad trouble ticket number, ILEC trouble ticket number (if it is not null) and operation name. 1. For response messages, set the operation status to success 2. For exception messages, set the operation status to failure, and operation error message from the exception. In the case of createTroubleTicketByValueException, an email should be sent to the Covad contact person to notify the trouble ticket creation failed. 6.10 JVTEventMDB Implementation JVTEventMDB subscribes to JVTEventTopic, and consumes all the messages in JVTEventTopic. All the messages are Java object messages. Here is the complete list of Java object messages it needs to handle. 1. TroubleTicketAttributeValueChangeEvent 2. TroubleTicketCancellationEvent 3. TroubleTicketCloseOutEvent 4. TroubleTicketStatusChangeEvent 5. TroubleTicketCreateEvent The handling of these events is as follows: 1. Retrieve all the attribute values from the event 2. For all these events except the creation event, compare all the not-null values with database values, if they are same, ignore the event; otherwise create a history record in TT_ILECINFO_HISTORY table, and update TT_ILECINFO table. 3. For creation event, update the record in TT_ILECINFO table. 6.11 TroubleTicketTimerService Implementation This timer service is not customer facing service, but a background one. Its purpose is to query ILECs database constantly on some pre-configured time interval to get the latest trouble ticket information. Theoretically T1M1 standard requires ILEC send Covad the following notification: 1. Attribute Value Change Notification 2. Object Creation Notification 3. Object Deletion Notification 4. Trouble Report Status/Commitment Time Update Notification 5. Trouble History Event Notification

v1.1.2

32

But event notification is not queued at ILEC side, it is only sent once. If it is lost, there is no way to get the same notification again. In real world, there are many reasons that notification may be lost. So we cannot rely on these notifications to synchronize with ILEC database information. This timer service is the way to synchronize our local database with ILEC database.
6.11.1 Configuration File for the Timer Service

This configuration file should contain two pieces of information: 1. The time interval: it determines how often the query messages will be generated, like every 4 hours. 2. The set of attributes we want to query against ILEC systems. Basically we should include all the common attributes which could be supplied or updated by ILEC. The Join Integration Agreement specifies this information.
6.11.2 The Procedures for the Timer Service

The implementation of this timer service can use the weblogic proprietary interfaces like T3StartupDef and NotificationListener. This service performs the following steps regularly on pre-configured time interval: 1. Query Covad database to find out all the trouble tickets which satisfy the following criteria. a. The state is open b. The commitment time has passed or the trouble ticket has not been updated for a pre-configured time period. 2. If there are trouble tickets returned from step 1, browse XVTMessageQueue to find all the query messages already in the message queue. 3. For each trouble ticket returned from step 1, based on the following message properties to determine if the corresponding message has already in the queue: a. OSS_MESSAGE_TYPE b. OSS_MESSAGE_NAME c. ILEC_TROUBLETICKET_NUMBER 4. If a trouble ticket already has its corresponding query message in the XVTMessageQueue, ignore it. Otherwise, construct a getTroubleTicketByKeyRequest message with pre-defined attribute set and send it to the XVTMessageQueue. When the request gets into the XVTMessageQueue, it queries the ILEC system, and wait for return. When return comes, it updates our local database. The work after the message gets into the queue will be carried out by the ILEC gateway system, JVTEventMDB message-driven bean.

v1.1.2

33

With this timer service, all information in Covad database are synchronized with ILEC database regularly, so subsequent queries can just read Covad database, and have almost up to date information.

v1.1.2

34

ILEC TROUBLE TICKET GATEWAY IMPLEMENTATION

The ILEC Trouble Ticket Gateway interacts with both Covad trouble ticket system and ILEC trouble ticket system. The interactions with Covad trouble ticket system are through JMS for the message consuming and producing. The interactions with ILEC trouble ticket system are through CMIP. Beside the normal CMIP request/response with ILEC systems, the gateway will also receive event notifications initiated by ILEC trouble ticket systems. 7.1 Standard T1M1 to OSS/J Mapping

OSS/J defines 49 attributes, while T1M1 defines 95 attributes for trouble ticket. Here is the mapping between the fields defined by these two standards. Not all attributes defined by T1M1 will be used here. Not all the attributes have the natural mapping here either. We use bold and italic fields to highlight the name difference: T1M1 activityDuration alarmRecordPtrList additionalTroubleInfoList closeOutNarr receivedTime repairActivityList restoredTime troubleClearancePerson troubleFound troubleLocation troubleReportNumberList ManagedObjectInstance troubleType troubleReportState troubleReportStatus troubleReportStatusTime afterHrsRepairAuth authorizationList cancelRequestByManager closeOutVerification commitmentTime commitmentTimeRequest custTroubleTickNum Dialog escalationList initiatingMode lastUpdateTime maintServiceCharge outageDuration perceivedTroubleSeverity v1.1.2 OSS/J activityDurationList relatedAlarmList additionalTroubleInfoList closeOutNarr receivedTime repairActivityList restoredTime clearancePerson troubleFound troubleLocation troubleNumList troubledObject troubleType troubleState troubleStatus troubleStatusTime afterHoursRepairAuthority authorizationList cancelRequestedByCustomer closeOutVerification commitmentTime commitmentTimeRequested customerTroubleNum dialog escalationList initiatingMode lastUpdateTime maintServiceCharge outageDuration perceivedTroubleSeverity 35

preferredPriority repeatReport suspectObjectList troubleDetectionTime managedObjectAcessFromTime managedObjectAccessHours managedObjectAccessToTime

preferredPriority repeatReport suspectObjectList troubleDetectionTime troubledObjectAccessFromTime troubledObjectAccessHoursList troubledObjectAccessToTime

This mapping should be used in two ways. It tells where to find value for CMIP attributes when we construct a CMIP message, it also indicates where to find value when constructing OSS/J objects from CMIP messages. 7.2 ILEC Specific Property 1. TroubleReportFormatObjectPtr 2. TroubleReportStatusWindow 3. ILEC networkId 4. Covads account name under ILEC 5. Covads service Id under ILEC 7.3 ILEC Specific Mapping File

Here is the list of attribute values we need to specify for each ILEC:

T1M1 Standard defines the sets of values for trouble status, trouble found, trouble type and trouble state, but ILEC may have its own set of values (SBC is an example). We can only store values for these fields according to the standard. When we receive messages from ILEC systems, these values will be ILEC proprietary values. We need to map them to the standard values before pass them to the queue or topic. The mapping can be obtained from the Joint Integration Agreement document with ILECs. 7.4 ILEC Specific Communication Property

The communication piece with ILEC is implemented through 3rd party product: Monfoxs Dynamic TMN. There are two properties files used by the Dynamic TMN. 1. The naming service property file: this file specifies the protocol initiation parameters, which includes the pointer to the actual protocol property file, the selectors for the presentation layer, session layer, and application layer of the OSI protocol stack. 2. The protocol property file: this file specifies the CMIP user information, functional unit information, and a file pointer to the security key file. 3. The security key file.

v1.1.2

36

7.5

Consume Messages from Covad Trouble Ticket System 1. It will asynchronously receive the XML message from XVTMessageQueue. 2. The session to the queue is non-transactional. 3. The acknowledge mode is AUTO_ACKNOWLEDGE

Gateway needs to create a message receiver. This receiver has the following properties:

The following is the complete list of message types it needs to handle: 1. createTroubleTicketByValueRequest 2. cancelTroubleTicketsByTemplateRequest 3. closeTroubleTicketsByTemplateRequest 4. escalateTroubleTicketsByTemplateRequest 5. setTroubleTicketByValueRequest 6. getTroubleTicketByKeyRequest Upon receiving these messages, we need to de-serialize them into Java objects such that all the attribute values can be easily retrieved, and then construct the CMIP message, and use Monfoxs MOHandle to send out the message. 7.6 Receive Responses from ILEC Trouble Ticket System

Gateway needs to have one sender for XVTMessageReplyQueue, one subscriber for JVTEventTopic. The following is the complete list of what it will receive and how to deal with it. Request Response Action

v1.1.2

37

createTroubleTicket ByValueRequest

CreateConfirmation

1. Construct createTroubleTicketByValueRespons e XML message. Using the return value of TroubleReportID as the primary key for the troubleTicketKey to return. 2. Construct TroubleTicketCreateEvent. 3. Send createTroubleTicketByValueRespons e message to XVTMessageReplyQueue 4. Publish the TroubleTicketCreateEvent to JVTEvnetTopic From the error code, determine if it is a system error. If it is an application error, do the same as ValueException, otherwise, just log the exception, and throw the exception This is application error. Do the following: 1. Construct createTroubleTicketByValueExceptio n XML message. 2. Log the exception. 3. Send the constructed message to XVTMessageReplyQueue

PerformException

ValueException

v1.1.2

38

cancelTroubleTickets ByTemplateRequest

SetConfirmation

1. Construct cancelTroubleTicketsByTemplateRes ponse XML message. 2. Construct TroubleTicketCancellationEvent. 3. Send cancelTroubleTicketsByTemplateRes ponse to XVTMessageReplyQueue 4. Publish TroubleTicketCancellationEvent to JVTEventTopic From the error code, determine if it is a system error. If it is an application error, do the same as ValueException, otherwise, just log the exception and throw the exception This is application error. Do the following: 1. Construct cancelTroubleTicketsByTemplateExc eption XML message. 2. Log the exception. 3. Send the constructed message to XVTMessageReplyQueue 1. Construct closeTroubleTicketsByTemplateResp onse XML message. 2. Construct TroubleTicketCloseOutEvent. 3. Send the constructed message to XVTMessageReplyQueue 4. Publish TroubleTicketCloseOutEvent to JVTEventTopic. From the error code, determine if it is a system error. If it is an application error, do the same as ValueException, otherwise, just log the exception, and throw the exception This is application error. Do the following: 1. Construct closeTroubleTicketsByTemplateExce ption XML message. 2. Log the exception 3. Send the constructed message to XVTMessageReplyQueue

PerformException

ValueException

closeTroubleTickets ByTemplateRequest

SetConfirmation

PerformException

ValueException

v1.1.2

39

escalateTroubleTickets SetConfirmation ByTemplateRequest

1. Construct escalateTroubleTicketsByTemplateRe sponse XML message. 2. Construct troubleTicketAttributeValueChangeE vent. 3. Send escalateTroubleTicketsByTemplateRe sonse to XVTMessageReplyQueue 4. Publish troubleTicketAttributeValueChangeE vent to JVTEventTopic. From the error code, determine if it is a system error. If it is an application error, do the same as ValueException, otherwise, just log the exception and throw the exception This is application error. Do the following: 1. Construct escalateTroubleTicketsByTemplateEx ception XML message. 2. Log the exception 3. Send the constructed message to XVTMessageReplyQueue

PerformException

ValueException

v1.1.2

40

setTroubleTicket ByValueRequest

SetConfirmation

1. Construct setTroubleTicketByValueResponse XML message. 2. Construct troubleTicketAttributeValueChangeE vent. 3. Send setTroubleTicketByValueResponse message to XVTMessageReplyQueue 4. Publish troubleTicketAttributeValueChangeE vent to JVTEventTopic. From the error code, determine if it is a system error. If it is an application error, do the same as ValueException, otherwise, just log the exception and throw the exception This is application error. Do the following: 1. Construct setTroubleTicketsByTemplateExcepti on XML message. 2. Log the exception 3. Send the constructed message to XVTMessageReplyQueue 1. Construct getTroubleTicketByKeyResponse XML message. 2. Send the constructed message to XVTMessageReplyQueue Just log the exception. Just log the exception

PerformException

ValueException

getTroubleTicket ByKeyRequest

GetConfirmation

PerformException ValueException

7.7

Receive Event Notifications from ILEC Trouble Ticket System

We need to create a new publisher for publishing events to JVTEventTopic. Monfoxs Dynamic TMN reports event notification as MOHandleEvent. Based on this event object, we can obtain the event type, and all the relevant attribute names and values. Two steps need to be performed here: 1. Sent confirmation back to ILEC system for the notification. 2. Based on the event type, and attribute name and value, construct one of the Event object, and publish to JVTEventTopic. a. TroubleTicketAttributeValueChangeEvent

v1.1.2

41

b. TroubleTicketCloseOutEvent c. TroubleTicketCancellationEvent d. TroubleTicketCreateEvent e. TroubleTicketStatusChangeEvent f. TroubleTicketAttributeValueChangeEvent When we construct these event, we need to apply the ILEC specific trouble type, trouble status, trouble found, trouble state mapping. 3. Publish the event to JVTEventTopic.

v1.1.2

42

USE CASE REALIZATION

With all the preparation we had, the use case realization is simple. 8.1
8.1.1

Create a Trouble Ticket

Technicians Interactions with TT-Application

1. Technician interacts with TT-Application prepare the following information: 1) Trouble Object Identifier 2) Trouble Type 3) Additional Trouble Info 4) Covad Trouble Ticket Number 5) Covad Contact Person Information 6) Trouble Location Information 7) Trouble Ticket Authorization Information 8) ILEC Name 9) Trouble Ticket Escalation Information 10) Commitment Time Requested 11) Repeat Report 12) Trouble Detection Time 13) Perceived Trouble Severity 14) Preferred Priority 2. Technician submits the trouble ticket creation request using TT-Application. 3. Technician is informed that the request has been forwarded to ILEC for processing.
8.1.2 Sequence Diagram

The following sequence diagram illustrates the technicians interaction with TTApplication.

v1.1.2

43

: Technician

TT-Application (GUI)

JVTTroubleTicketSessionBean

XVTMessageQueue

1: prepare trouble ticket value

2: send request 3: createTroubleTicketByValue( troubleTicketValue ) 4: input parameter validation

5: xmlSerialize.toXml( troubleTicketValue )

6: send createTroubleTicketByValueRequest 7: return null 8: return

8.1.3

What Happens behind the Scene

The following sequence diagram illustrates what happens behind the scene for a successful trouble ticket creation.

v1.1.2

44

XVTMessageQueue

ILEC Trouble Ticket Gateway

ILEC Trouble Ticket System

XVTMessageReplyQueue

JVTEventTopic

XVTReplyMDB

JVTEventMDB

Database

1: onMessage( createTroubleTicketByValueRequest ) 2: xmlSerializer.fromXml( createTroubleTicketByValueRequest )

3: setStage

4: CreateConfirmation = performCreate(): send CMIP message

5: send( createTroubleTicketByValueResponse )

6: publish( troubleTicketCreateEvent )

7: onMessage( createTroubleTicketByValueResponse )

8: onMessage( troubleTicketCreateEvent )

9: persist data

10: persist data

8.2
8.2.1

Query a Trouble Ticket Status/Information

Technicians Interaction with TT-Application

1. Technician enters either Covad trouble ticket number or ILEC trouble ticket number for querying a trouble ticket information. 2. Technician submits the request. 3. Information regarding this trouble ticket is presented to the Technician.
8.2.2 Sequence Diagram

The following sequence diagram illustrates the interaction:

v1.1.2

45

: Technician

TT-APP (GUI)

JVTTroubleTicketSessionBean

Database

1: search trouble ticket 2: getTroubleTicketsByTemplate( troubleTicketValue, attrNames )

3: retrieve data 4: return data 5: display data

8.3
8.3.1

Cancel a Trouble Ticket

Technicians Interaction with TT-Application

1. The Technician prepares the following information: a. ILEC Trouble Ticket Number b. Trouble Clearance Person Information c. Close out Narratives 2. Technician submits the trouble ticket cancellation request using TT-Application. 3. Technician is informed that the request has been forwarded to ILEC for processing.
8.3.2 Sequence Diagram

The following sequence diagram illustrates technicians interaction with TT-Application.

v1.1.2

46

: Technician

TT-Application (GUI)

JVTTroubleTicketSessionBean

XVTMessageQueue

1: prepare trouble ticket cancellation 2: send request 3: cancelTroubleTicketsByTemplate( troubleTicketValue, ... ) 4: xmlSerialize.toXml( troubleTicketValue )

5: send cancelTroubleTicketsByTemplateRequest

8.3.3

What Happens behind the Scene

The following sequence diagram illustrates what happens behind the scene for a successful trouble ticket cancellation.

v1.1.2

47

XVTMessageQueue

ILEC Troble Ticket Gateway

ILEC Trouble Ticket System

XVTMessageReplyQueue

JVTEventTopic

XVTReplyMDB

JVTEventMDB

Database

1: onMessage( cancelTroubleTicketsByTemplateRequest ) 2: xmlSerializer.fromXml( cancelTroubleTicketsByTemplateRequest )

3: setStage

4: setConfirmation = performSet(): send CMIP message

5: send ( cancelTroubleTicketsByTemplateResponse )

6: publish ( troubleTicketCancellationEvent )

7: onMessage( cancelTroubleTicketsByTemplateResponse )

8: onMessage( troubleTicketCancellationEvent )

9: persist data

10: persist data

8.4
8.4.1

View a Trouble Ticket History

Technicians Interaction with TT-Application

1. Technician enters ILCE trouble ticket number for viewing a trouble ticket history. 2. Technician submits the request. 3. TT-Application displays the history.
8.4.2 Sequence Diagram

The following sequence diagram illustrates the successful execution scenario:

v1.1.2

48

: Technician

TT-APP (GUI)

JVTTroubleTicketSessionBean

Database

1: view trouble ticket history based on ILEC trouble ticket number 2: queryTroubleTickets( QueryTroubleTicketHistoryValue, attrNames )

3: retrieve data

4: return 5: return

8.5
8.5.1

Escalate a Trouble Ticket

Technicians Interactions with TT-Application

1. Technician prepares the following information: a. Escalation Level b. Escalation Person Id c. Request State d. Request Person Id e. Additional Trouble Info for the Escalation Reason 2. Technician submits the escalation request using TT-Application. 3. Technician is informed that the request has been forwarded to ILEC for processing.
8.5.2 Sequence Diagram

The following sequence diagram illustrates the interaction.

v1.1.2

49

: Technician

TT-Application (GUI)

JVTTroubleTicketSessionBean

XVTMessageQueue

1: prepare escalation info 2: send request 3: escalateTroubleTicketsByTemplate( troubleTicketValue, escalationList )

4: xmlSerialize.toXml( troubleTicketValue, escalationList )

5: send escalationTroubleTicketsByTemplateRequest 6: return

7: return

8.5.3

What Happens behind the Scene

The following sequence diagram illustrates what happens behind the scene for a successful trouble ticket escalation.

v1.1.2

50

XVTMessageQueue

ILEC Trouble Ticket Gateway

ILEC Trouble Ticket System

XVTMessageReplyQueue

JVTEventTopic

XVTReplyMDB

JVTEventMDB

Database

1: onMessage( escalateTroubleTicketsByTemplateRequest ) 2: xmlSerializer.fromXml( escalateTroubleTicketsByTemplateRequest )

3: setStage

4: setConfirmation=performSet(): send CMIP message

5: send ( escalateTroubleTicketsByTemplateResponse )

6: publish ( troubleTicketAttributeValueChangeEvent )

7: onMessage( escalateTroubleTicketsByTemplateResponse )

8: onMessage( troubleTicketAttributeValueChangeEvent )

9: persist data

10: persist data

8.6
8.6.1

Modify a Trouble Ticket

Technicians Interaction with TT-Application

1. Technician enters new values to the following attributes: a. Trouble Location Information b. Trouble Authorization Information c. Trouble Object Access Hour Information d. Covad Contact Person e. Commitment Time Requested f. Perceived Trouble Severity g. Preferred Priority 2. Technician submits the change.

v1.1.2

51

3. Technician is informed that the change request has been forwarded to ILEC for processing.
8.6.2 Sequence Diagram

The following sequence diagram illustrates the interaction.

: Technician TT-Application (GUI) JVTTroubleTicketSessionBean XVTMessageQueue

1: prepare trouble ticket value

2: send request 3: setTroubleTicketByValue( troubleTicketValue ) 4: xmlSerialize.toXml( troubleTicketValue ) 5: send setTroubleTicketByValueRequest 6: return

7: return

8.6.3

What Happens behind the Scene

The following sequence diagram illustrates what happens behind the scene for a successful trouble ticket modification.

v1.1.2

52

XVTMessageQueue

ILEC Trouble Ticket Gateway

ILEC Trouble Ticket System

XVTMessageReplyQueue

JVTEventTopic

XVTReplyMDB

JVTEventMDB

Database

1: onMessage( setTroubleTicketByValueRequest ) 2: xmlSerializer.fromXml( setTroubleTicketByValueRequest )

3: setStage

4: SetConfirmation = performSet() : send CMIP message

5: send setTroubleTicketByValueResponse

6: publish TroubleTicketAttributeValueChangeEvent

7: onMessage( setTroubleTicketByValueResponse )

8: onMessage( TroubleTicketAttributeValueChangeEvent )

9: persist data

10: persist data

8.7

Verify Repair Completion/Close a Trouble Ticket

This use case only applies after an ILEC has repaired the trouble and changes the trouble report status attribute value to clearedAwaitingCustVerification.
8.7.1 Technicians Interaction with TT-Application

1. Technician reviews the Trouble Found field, and close out narrative field provided by ILEC. 2. Technician set the Trouble Clearance Person Information. 3. Technician determines if the trouble has been fixed. If it is fixed, set the close out verification to verified, otherwise set the close out verification to denied. 4. Technician submits the request. 5. Technician is informed that the request has been forwarded to ILEC for processing.

v1.1.2

53

8.7.2

Sequence Diagram

The following sequence diagram illustrates the close a trouble ticket scenario.
: Technician TT-Application (GUI) JVTTroubleTicketSessionBean XVTMessageQueue

1: prepare trouble ticket value 2: send request 3: closeTroubleTicketsByTemplate( troubleTicketValue, status, closeOutNarr )

4: xmlSerialize.toXml( troubleTicketValue )

5: send closeTroubleTicketsByTemplateRequest 6: return

7: return

8.7.3

What Happens behind the Scene

The following sequence diagram illustrates what happens behind the scene for a successful trouble ticket close out.

v1.1.2

54

XVTMessageQueue

ILEC Trouble Ticket Gateway

ILEC Trouble Ticket System

XVTMessageReplyQueue

JVTEventTopic

XVTReplyMDB

JVTEventMDB

Database

1: onMessage( closeTroubleTicketsByTemplateRequest ) 2: xmlSerializer.fromXml( closeTroubleTicketsByTemplateRequest )

3: setStage

4: SetConfirmation = performSet() : send CMIP message

5: send closeTroubleTicketsByTemplateResponse

6: publish TroubleTicketCloseOutEvent

7: onMessage( setTroubleTicketsByTemplateResponse )

8: onMessage( TroubleTicketCloseOutEvent )

9: persist data

10: persist data

v1.1.2

55

IMPACTS ON EXISTING SYSTEM

1. TT-Application (GUI): we need to add screens for ILEC trouble ticket interactions. The screens should cover all the use cases. 2. TT-Browser: changes are corresponding to the changes in the TT-Application. 3. The Timer Task used for closing a Covad trouble ticket needs to be modified to check ILEC trouble ticket state stored in the TT_ILECINFO table. If the state is closed, the corresponding Covad trouble ticket may need to change its state/status too.

Impacts occur in two places:

v1.1.2

56