JSR 91 - Trouble Ticket API Final Overview

Transcription

1 JSR 91 - Trouble Ticket API Final Overview OSS through Java Initiative JSR91 Expert Group TT-API-SPEC_PART1_OVERVIEW.1.2.doc Copyright , The Members of the OSS through Java(TM) Initiative. All rights reserved. Use is subject to license terms. Final JSR 91 - Trouble Ticket API page 1 / 65

2 Executive Summary This document is part of the specification of JSR 91, the OSS Trouble Ticket API. The Trouble Ticket API is one of the APIs specified within the OSS through Java Initiative (OSS/J). It has been designed to provide standard client interfaces to Trouble Ticket Management Systems. These interfaces foster the integration and interoperability of systems, which are involved in trouble resolution processes. This API defines the minimum requirements for Trouble Ticket Management System providing interfaces, as specified by the OSS/J Design Guideline, for creating, tracking, and deleting trouble tickets. The Trouble Ticketing API enables creation and tracking of trouble tickets. It receives trouble ticket information either from the customer, or from service and network management applications such as Service Impact Analysis, and Root-Cause Alarm Analysis/Fault Monitoring. It enables tracking of the problem until resolution, and notification of clients when the problem has been resolved and the trouble ticket cleared. The Trouble Ticket API provides interfaces that allow clients to: create, remove and cancel Trouble Tickets change the values of Trouble Tickets be informed of Trouble Ticket Changes via notifications Final JSR 91 - Trouble Ticket API page 2 / 65

3 Acknowledgements This version (1.2) of the specification is based on the work of Pierre Gauthier (Metasolv) who lead the specification of version 1.0, and Axel Terfloth (IP-Value) who completed the maintenance release version 1.1. The maintenance release version 1.2 of JSR91 was led by Roman Schlegel (FROX communication), with great support from other OSS/J Spec leaders. Special thanks to: Vincent Perrot (Sun Microsystems) who provided valuable advice Richard Craddock (Tigerstripe) who indirectly contributed And also thanks to the engineers involved in former versions of this API: Amit Kumar Varshney (Wipro) and his collegues, Ramin Roham-Pour (IP VALUE) and Traugott Dittmann (IP VALUE). Final JSR 91 - Trouble Ticket API page 3 / 65

4 Table of Contents Executive Summary... 2 Acknowledgements... 3 Table of Contents... 4 Table of Figures Preface Objectives Audience Approval and Distribution Related Information Revision History Introduction API Goals API Scope OSS Overview Architecture Integration Profiles JVT Integration Profile XVT Integration Profile Data Model Data Model Perspectives The Content Perspective The Type Perspective The Extension Perspective Trouble Ticket Model Trouble Ticket State Model Meaning of Base States State Transitions Implementing and Extending the State Model Relations between Trouble Tickets and Trouble Ticket Items Trouble Ticket Item Model Key Types Implementing and Extending the Data Model Final JSR 91 - Trouble Ticket API page 4 / 65

5 5 Features/requirements Session Façade Operations Meta Data Operations Managing Entities Template Search Bulk Operations without Templates Bulk Operations with Template(s) Naming Mode Reading Trouble Tickets Reading Trouble Ticket Items Creating Trouble Tickets Creating Trouble Ticket Items Updating Trouble Tickets Updating Trouble Ticket Items Stale Values in Updates Closing and Canceling Trouble Tickets Removing Trouble Ticket Items Executing Named Queries Executing Update Procedures Named Queries Update Procedures Iterators Implementing and Extending Operations Events Trouble Ticket Events Trouble Ticket Item Events Implementing and Extending Events Relationship to other OSS/J APIs Standards Telemanagement Forum (TMF) etom Process Areas Shared Information/Data Model (SID) Domains NGOSS Lifecycle and Methodology Business Process Execution Language (BPEL) Similar Standards Appendix A Glossary and References...61 A.1. Glossary A.2. References Final JSR 91 - Trouble Ticket API page 5 / 65

6 Appendix B Specification Summary Final JSR 91 - Trouble Ticket API page 6 / 65

7 Table of Figures Figure 1: Trouble Ticket API Contextual Overview, Examples Figure 2: High-level basic architecture of a J2EE application based on [JSR 144].. 15 Figure 3: OSS/J Trouble Ticket API Interaction Profiles...16 Figure 4: Resources of the JVT Integration Profile...18 Figure 5: Resources of the XVT Integration Profile...19 Figure 6: Overview of CBE data types relevant for the TT API...20 Figure 7: Data Model Extension Perspective Figure 8: The TroubleTicketValue attributes...23 Figure 9: Base trouble ticket state model...26 Figure 10: Enumerations for Trouble Ticket States...26 Figure 11: TroubleTicketItem Inheritance...30 Figure 12: Example of different flavors for an operation Figure 13: Trouble Ticket Event Types Figure 14: Trouble Ticket Item Event Types Figure 15: Relationship to other OSSJ APIs...57 Figure 16: SID Domains Final JSR 91 - Trouble Ticket API page 7 / 65

8 1 Preface This document is part of the specification of JSR 91, the OSS Trouble Ticket API. 1.1 Objectives The OSS/J Trouble Ticket API specified by this document provides a service for creating, reading, updating and querying trouble tickets and related items. Also clients can track new tickets as well as the whole resolution process. The purpose of the API is to facilitate the development and integration of OSS components with trouble ticket systems. This specification defines an API towards a Trouble Ticket Management System but not this system itself. 1.2 Audience The intended audiences of this document are Software and Solution Architects, Software Developers and Testers which are involved in: Developing and certification of server components implementing the OSS Trouble Ticket API Developing client components which use the OSS Trouble Ticket API Designing, Deployment and Testing of components based on the OSS Trouble Ticket API It is assumed that the reader of this document has sufficient knowledge of OSS and J2EE. 1.3 Approval and Distribution This document was approved by the expert group of JSR 91. Further revisions, which follow the stages of the Java Community Process, will also be created and approved by the expert group. All documents can be found either on the websites of the OSS through Java Initiative [OSSJ], the public project on java.net [JSR091-public] or the Java Community Process [JSR91]. Final JSR 91 - Trouble Ticket API page 8 / 65

9 1.4 Related Information The OSS Trouble Ticket API is part of a group of OSS APIs specified by the OSS through Java Initiative. All these APIs are built upon the OSS Common API definitions and follow the Common Design Guidelines. The foundation for this API is: JSR 144 OSS Common API [JSR 144] OSS/J J2EE Design Guidelines [OSSJ DG] The OSS Common API defines a set of technical interfaces, which are used by the API defined by this specification. The OSS Common API also includes a definition of SID compliant Core Business Entities (CBE). The OSS/J Design Guidelines define general patterns and rules for the design of functional OSS/J APIs like this one. These guidelines must also be applied for implementation specific extensions of this API. If not specified different by this specification JSR 144 and OSS/J Design Guidelines, in the versions mentioned above, also apply to this specification. General information about the work of the OSS/J can be found on the OSS/J websites. General OSS/J documents and presentations from 1.5 Revision History Date Version Author State Comments 2001-Apr 0.1 Pierre Gauthier Draft Pierre Gauthier Final Release Axel Terfloth, Traugott Dittmann Maintenance Release Roman Schlegel Maintenance Release Final JSR 91 - Trouble Ticket API page 9 / 65

10 2 Introduction This document specifies the OSS/J Trouble Ticket Application Programming Interface (API) version 1.2 as defined in the OSS/J API Roadmap document [OSSJ Roadmap]. This API has been defined within the scope of Java Specification Request 91 [JSR91]. 2.1 API Goals The API follows the OSS/J Design Guidelines [OSSJ DG] and is based on and uses the OSS Common API [JSR 144]. It is structured similar to other OSS/J APIs, thus significantly reducing learning effort for this API. This implies: 1. The API is NGOSS compliant. 2. The API structure supports related etom process areas, NGOSS Views and lifecycle 3. The SID model is realized through the Core Business Entities in the Common API and other entities within this API 4. The same functionality will be exposed via three integration profiles: a. JVT: Java Value Type API, synchronous interface supporting the best of J2EE technologies b. XML/JMS: An asynchronous API, XML message exchange via JMS c. WSDL: A Web Services interface 5. The API is not tied to any specific approach, product or scenario 6. There is a reference implementation of the API for the Profiles JVT and XML/JMS, allowing for immediate implementation. The reference implementation will be updated later with WS capabilities as well 7. Support for basic as well as targeted, more complex operations 8. Extensible interface to support more complex features and allow vendor differentiation 9. This specification is organization, process, service and network agnostic; no information model is defined beyond the SID and CBE. Final JSR 91 - Trouble Ticket API page 10 / 65

11 2.2 API Scope Table 1 shows, which main uses cases have been identified for each scenario, in which an implementation of the Trouble Ticket API can be used. Table 1: Main Use-Cases based on etom 921D release 7.1 Implementation Use-Cases as defined in etom TroubleTicketSession Customer Problem Handling ( ) Create Customer Problem Report Report Customer Problem Track & Manage Customer Problem Close Customer Problem Report Service Problem Management ( ) Create Service Trouble Report Report Service Problem Track & Manage Service Problem Close Service Trouble Report Resource Trouble Management ( ) Create Resource Trouble Report Report Resource Trouble Survey & Analyse Resource Trouble Track & Manage Resource Trouble Close Resource Trouble Report S/P Problem Reporting & Management ( ) Initiate S/P Problem Report Receive S/P Problem Report Track & Manage S/P Problem Resolution Report S/P Problem Resolution Close S/P Problem Report The API mandates the minimum interface between an Trouble Ticket Client and the related Implementation. Furthermore, the specified interface is not expected nor desired to expose all implementation functionality. It is up to the implementation to expose the remaining details if required and it can be achieved by extending this API at the defined extension points where appropriate. Additionally, the Trouble Ticket API may not be the only interface that a particular implementation provides. Different roles may access the same implementation using other interfaces, which either offer the same functionality as the Trouble Ticket API or something supplemental or even completely different. Final JSR 91 - Trouble Ticket API page 11 / 65

12 The Trouble Ticket API supports J2EE/EJB, XML/JMS and WSDL interfaces, including "bulk" methods, capable of managing several managed entities (i.e. orders) at a time. This document includes scenarios and examples of Trouble Ticket interactions. Final JSR 91 - Trouble Ticket API page 12 / 65

13 3 OSS Overview The Trouble Ticket API provides interfaces for creating, querying, updating, closing and canceling trouble tickets and attaching related trouble ticket items to them. Interfaces and mechanisms are also provided for trouble ticket notification management. The set of components implementing the Trouble Ticket interfaces are designed to be used as an integration point for the applications requiring access to trouble ticket systems. Typical examples of clients of the API are: a process running inside an integration hub or workflow engine a CRM application issuing trouble tickets a network management system automatically generating trouble tickets a fault management system allowing operators to merge several alerts into a ticket other trouble ticket management systems forwarding tickets (e.g. B2B) Figure 1: Trouble Ticket API Contextual Overview, Examples The picture illustrates how OSS/J clients may interact with the server side. Final JSR 91 - Trouble Ticket API page 13 / 65

14 The CRM creates a ticket on behalf of a customer. It also subscribes to the notifications. When the trouble is solved it will receive a notification and thus be able to inform its customer. The ticketing hub decides which ticketing system is in charge of dealing with a specific ticket. It then delegates that ticket to our depicted system by calling create trouble ticket. In this example, the trouble ticket is later on cancelled by an operator of our ticketing system and the hub receives a notification about the cancellation. The fault management system issues a ticket for a set of alerts. This can happen automatically or manually by an operator. The alerts are attached to the ticket. During the trouble resolution process one of the alarms is ceased. So the FM updates the ticketing system on the new development. Final JSR 91 - Trouble Ticket API page 14 / 65

15 4 Architecture The following diagram presents the high-level basic architecture of a J2EE application based on the Common API components. The OSS Common API defines the core JVT session façade and the XMLbased messaging façade for access to the application components. J2EE client XML/JMS client WS client JMS Event Topic XML Event Topic Request Queue Reply Queue Event XML Req/Resp Message Driven Bean WS EndPoint JVT Session Facade JVT Home Entity Bean Entity Home Application In Container Connector (JCA) System Figure 2: High-level basic architecture of a J2EE application based on [JSR 144] The architecture of the OSS Trouble Ticket API follows the architecture defined by the OSS/J Design Guidelines [OSSJ DG] and OSS Common API [JSR 144]. Take a look at these documents for more detail. This specification defines an API, which clients can use to access a trouble ticket management system. Thus this specification defines a communication contract between trouble ticketing client and a trouble ticketing server. This includes definition of API structure and behavior. It is basically everything what is visible at the interface between client and server. It explicitly does not cover anything, which should be invisible to the client. So any possible implementation strategies including best practices for implementations are out of scope. Final JSR 91 - Trouble Ticket API page 15 / 65

16 4.1 Integration Profiles Technology-wise the Trouble Ticket API is based on J2EE and XML technologies. The same functionality and granularity is available using different communication profiles. The respective technology s way to implement service discovery, service invocation and asynchronous notifications has been used. E.g. for the JVT communication profile (Java Value Type; RMI based) JNDI, Session Beans and JMS Object Messages are used. A number of design patterns have been leveraged. This includes Session Façade pattern, the Value Object pattern and various concepts to minimize the number of network invocations and the net load in general. The TT API specification follows the integration profiles as defined by the OSS/J Initiative and described in the OSS/J Design Guidelines [OSSJ DG]. Java Value Type (JVT) XML Value Type (XVT) Web Services (WS) For WS profile, there is no RI and TCK included in this specification, but will be implemented soon. Figure 3: OSS/J Trouble Ticket API Interaction Profiles The functionality and granularity is the same for the different communication profiles. The differences in technology are listed in the following table. Final JSR 91 - Trouble Ticket API page 16 / 65

17 JVT XVT WS The specification consists of Java interfaces and Javadocs The XML schema files (.xsd) A WSDL file referencing XML schema files Trouble ticket data and other information is represented by Java objects XML XML For sending requests and receiving responses the client uses Java objects sent over RMI XML sent to a JMS queue; response is sent to a reply destination defined in the client request XML sent to a URL - supposedly over HTTP(S) Notifications are represented by Java objects contained in JMS object messages XML in JMS text messages XML - supposedly sent over HTTP(S) to the client side s WS endpoint Clients can subscribe to notifications by Subscribing to a dedicated JMS topic (JVT Event Topic) Subscribing to a dedicated JMS topic (XVT Event Topic) Sending a subscription message to the server s WS Notification service URL Clients can discover, locate the available resources Via JNDI: JVT Trouble Ticket Session Bean JVT Event Topic Topic Connection Factory Via JNDI: XVT Message Queue XVT Event Topic Topic Connection Factory Queue Connection Factory Via UDDI URL of ticketing service URL of WS Notification Final JSR 91 - Trouble Ticket API page 17 / 65

18 It is important to understand that changes to entities managed by the trouble ticket management system do not just happen in response to OSS/J client request. It is likely that there are alternative e.g. system specific mechanisms to alter the state of a trouble ticket management system. Also changes due to these mechanisms require a consistent behavior of the API implementation. If as an example a trouble ticket is created using a proprietary TTMS client the OSS/J API must publish create-events for all supported integration profiles JVT Integration Profile Figure 4: Resources of the JVT Integration Profile The JVT integration profile is EJB based. The JVT implementation (the server) provides resources, which clients can use to interact with the server. All data is passed as serialized java objects (Java Value Types JVT) between client and server. These resources are: A JNDI naming context (not depicted above) which will be used by a client to access the other resources A JVT Home interface, which client use to create a JVTTroubleTicketSession. A JVTTroubleTicketSession, which is a stateless session bean and acts as a session façade and provides all API operations to clients. The JVT Event Topic, which is a JMS topic. Clients can subscribe to that topic and will be notified about events. The concrete trouble ticket management system and the way how the JVT interface is implemented must be invisible to clients. Final JSR 91 - Trouble Ticket API page 18 / 65

19 4.1.2 XVT Integration Profile Figure 5: Resources of the XVT Integration Profile The XVT integration profile is JMS and XML based. So all requests, responses and data is passed as XML document to and from the server. The XVT implementation (the server) provides resources, which clients can use to interact with the server. These resources are: A JNDI naming context (not depicted above) which will be used by a client to access the other resources An XVT Request Queue, which clients use, to send operation requests to. The XVT Event Topic, which is a JMS topic. Clients can subscribe to that topic and will be notified about events. Clients must specify the response queue within requests. So managing the response queue is the responsibility of the clients and thus is no resource, which must be provided by the XVT implementation. The concrete trouble ticket management system and the way how the XVT interface is implemented must be invisible to clients. 4.2 Data Model This section gives a description of the data model relevant for the Trouble Ticket API. The description of this data model is independent of a concrete representation required for one of the integration profiles. The Java and XML data models are defined by the java interfaces [JSR091 Part 3] and Final JSR 91 - Trouble Ticket API page 19 / 65

20 XML-Schema definitions [JSR091 Part 4], and are described in more detail in the User Guide [JSR91 Part 2] of this specification. Figure 6: Overview of CBE data types relevant for the TT API The CBE data types defined in the OSS Common API are grouped into several packages each covering a specific functional domain. The figure shows the main CBE types relevant for the TT API 1. The TT API provides lifecycle operations like create, update etc. for the managed entity value types TroubleTicketValue and TroubleTicketItemValue. These types are located in the CBE-Trouble package of the OSS Trouble Ticket API (JSR091). This package also contains the complex data type TroubleTicketRoleAssignment. Its intended use is to associate information about the role of parties (PartyValue) involved in the trouble resolution process. The TroubleTicketItemValue type represents items, which may be associated with a trouble ticket and are relevant for the trouble resolution process. The TT or Common API defines no specific trouble ticket item value type. Concrete implementations of the TT API may provide concrete subtypes. An example for applying is associating alarm information or alarm resolution actions 2. 1 The figure does not show all data types. E.g. key and enumeration types were left away. 2 The JSR91 Reference Implementation implements a concrete TroubleTicketItemValue subtype. Final JSR 91 - Trouble Ticket API page 20 / 65

21 TroubleTicketValue inherits from type BusinessInteractionValue and TroubleTicketItemValue inherits from BusinessInteractionItemValue. Both super types are located in the CBE-BusinessInteraction package Data Model Perspectives Next to resources, which are relevant for the client server interaction the API defines the model of the data passed between clients and API implementations The Content Perspective This data model covers basically three areas: 1. Data model which is used to represent the data of managed entities 2. Data model which is used to describe named query values and responses 3. Data model which is used to describe update procedure values and responses The Type Perspective There are two types of data model definitions. A data model definition may be defined in terms of a set of Java interfaces and as a set of XML Schema Definitions. The one used for the JVT integration profile and the other for the XML based integration profiles. Both types of data models for a OSS/J API must be equivalent regarding their semantics. The OSS/J Design Guidelines define constraints on how OSS/J data models must be defined in both model types. Further they define a mapping between the constructs of the different model types. So when an Java interface based OSS/J data model description is provided then a XML-Schema based model can be defined and vice versa. Final JSR 91 - Trouble Ticket API page 21 / 65

22 The Extension Perspective The data model is inherently extendable. The rules for extending data models are defined by the OSS/J Design Guidelines [OSSJ DG]. These rules are not only defined for system specific extensions of the OSS/J APIs but also are applied to the OSS/J API definitions itself. Figure 7: Data Model Extension Perspective The extensibility of the data model is not just a feature. Implementations of this API must provide a system specific extension of the data model. Part 2 of this specification covers the extension of the data model for the different integration profiles. Final JSR 91 - Trouble Ticket API page 22 / 65

23 4.2.2 Trouble Ticket Model Figure 8: The TroubleTicketValue attributes An instance of TroubleTicketValue represents a business interaction between a party who initiates the creation of a trouble ticket and the party who is responsible for the trouble resolution typically the service provider. Some of the domain specific attributes of a trouble ticket value are defined in the type TroubleTicketValue and the type BusinessInteractionValue defines some. The following table provides an overview of trouble ticket value attributes. Table 2: Description of Trouble Ticket Attributes Attribute Description troubleticketkey The key of type TroubleTicketKey. The inherited key attributes which hold the key of this managed entity must hold the equal key value. So this attribute is a strongly typed alias attribute for businesssinteractionkey, entitykey, CBEManagedEntityKey and managedentitykey attributes. Final JSR 91 - Trouble Ticket API page 23 / 65

24 Attribute interactiondate interactiondatecomplete businessinteractionstate businessinteractionitemkeys description troubleticketstate troubledescription roleassignments troubledetectiontime servicerestoredtime troubleticketitemkeys Description The point of time when the trouble report was received. It is not necessarily the creation time of the trouble ticket. The point of time when the trouble resolution process was finished. This is typically the time when the trouble ticket enters the state CLOSED. This attribute may be ignored in the context of this API. There is no relation to the troubleticketstate attribute. This attribute value equals the value of the troubleticketitemkeys attribute. The description of the interaction. The state of a trouble ticket of type TroubleTicketState. The description of the trouble. Contains a list of involved parties and their roles. The point of time when the trouble was detected. This time is typically before the time the trouble was reported (interactiondate). The point of time when the affected service was or will be restored. A list of the keys of trouble ticket items which are associated with this trouble ticket. The assignment of roles to involved parties is described by the value of the attribute roleassignments. A role assignment is an instance of type TroubleTicketRoleAssignment. It contains two attributes. Final JSR 91 - Trouble Ticket API page 24 / 65

25 Table 3: Description of TroubleTicketRoleAssignment Attributes Attribute Description rolename assignedparty The name of the role. The possible values must be defined by enumerations. The enumeration TroubleTicketRole defines a single enumeration value ORIGINATOR. The value represents the assigned party Trouble Ticket State Model Typically the trouble resolution process follows a workflow. During this workflow the ticket will be assigned certain states indicating the progress made so far. The OSS/J TT API s state model is based on the NMF601 standard 3. The state of a trouble ticket is maintained in the attribute troubleticketstate. 3 Please note that the base state DISABLED has been removed from the specification. It was designed for situations when the actual trouble ticket state cannot be retrieved due to technical reasons. So this state value does not describe technical situation rather than a domain specific value. This is not applicable to OSS/J Trouble Ticket State model. Final JSR 91 - Trouble Ticket API page 25 / 65

26 Figure 9: Base trouble ticket state model The state names are defined by the enumeration TroubleTicketState as defined in the CBE package of the Trouble Ticket API (JSR091). Figure 10: Enumerations for Trouble Ticket States Meaning of Base States The following table explains the meaning of the base states. Table 4: Meaning of Base States State Meaning QUEUED Trouble resolution has not yet been initiated. Final JSR 91 - Trouble Ticket API page 26 / 65

27 OPENACTIVATE DEFERRED CLEARED CLOSED CLOSED.CANCELED Appropriate actions to resolve the reported trouble are being carried out. The corrective action has been postponed. Trouble has been corrected, awaiting verification. Trouble resolution process is finished. The trouble was solved and resolution verified. Trouble resolution process is finished due to a cancellation of the trouble ticket State Transitions State transitions can be invoked by clients by using either the set methods (e.g. settroubleticketbyvalue) or the explicit transition methods for close and cancel. State transitions may also occur within the Trouble Ticket Management System without using operations of the TT API. This is the matrix of valid and invalid state transitions. All sub states are always included if not explicitly described (as for CLOSED.CANCELED). Table 5: State Transitions To CLOSED. CANCELED To CLOSED To CLEARED To DEFERRED To OPENACTIVE To QUEUED From not existing (initial states) From QUEUED From OPENACTIVE From DEFERRED From CLEARED From CLOSED From CLOSED. CANCELED yes Yes no no no no (yes) yes no no no yes No (yes) yes yes no yes no yes (yes) no no yes no yes no (yes) yes yes no no no no (yes) no no no no no no (yes) Final JSR 91 - Trouble Ticket API page 27 / 65

28 Implementing and Extending the State Model Spec 4-1: Implementations must not allow invalid state transitions. Spec 4-2: Spec 4-3: Spec 4-4: Spec 4-5: Implementations must not disallow valid state transitions, if the destination state is supported by the implementation. Implementations may use only a subset of base states. Implementations may extend the state model. The defined constraints on state transitions must not be violated. An enumeration must be used to define the names of the additional states of an extended state model. The given base model may be extended by implementers by their own sub states. So the trouble ticket state consists of one base level and an arbitrary number of sublevels. A dot (.) is used as delimiter. Two states are considered as direct sub states of the same state if the part of the name which begins with the first character and ends with the character before the last delimiter is equal for both states. A state may have any number of direct sub states and any number of indirect sub states. The name of each state must be defined by an enumeration Examples of valid states: Examples for invalid states: (Because FINISHED is not in the list of valid base states) (Because of the wrong delimiter) Readers who know the previous version (1.0) of this specification will recall the X.790 specific set of sub states. Using the terms of this specification version these sub states have been the level two in the state hierarchy. This level two was called troublestatus, while level one was called troublestate. Each level was maintained in an attribute of its own. You can still find the second level state values for the X.790 ticket model in the OSS/J s open source eco system. Implementers of an X.790 based trouble ticketing data Final JSR 91 - Trouble Ticket API page 28 / 65

29 model are recommended to use these values in combination with the new troubleticketstate attribute Relations between Trouble Tickets and Trouble Ticket Items The relationship between trouble tickets and trouble ticket items is of type n : m (TT : TT-Item). So a ticket can be related to multiple trouble ticket items. At the same time a trouble ticket item can be related to multiple trouble tickets. An implementer might want to restrict the relationship from n : m to 1 : m or even to 1 : 1. In that case the client s efforts to add another relationship must be answered with an exception: When creating trouble tickets: CreateException When updating trouble tickets: OssSetException In the context of executing update procedures: OssIllegalArgumentException The attribute troubleticketitemkeys of TroubleTicketValue is used for the trouble ticket items related to a trouble ticket. Other ways to retrieve the ticket items related to a ticket are these query types: AllTroubleTicketItemsRelatedToTroubleTicketQuery TroubleTicketItemsRelatedToTroubleTicketQuery The first allows you to search by a ticket key. The latter combines that with a template search. You can also search the other way round and find the tickets related to a ticket item: AllTroubleTicketsRelatedToTroubleTicketItemQuery TroubleTicketsRelatedToTroubleTicketItemQuery If you want to add a relation between a ticket and a ticket item you can either update the trouble ticket and set the new value for troubleticketitemkeys or run the update procedure type AssociateTroubleTicketItemsUpdateProcedure. If you want to remove a relation between a ticket and ticket item you can either update the trouble ticket and set the new value for troubleticketitemkeys or run the update procedure type DisassociateTroubleTicketItemsUpdateProcedure. Final JSR 91 - Trouble Ticket API page 29 / 65

30 4.2.5 Trouble Ticket Item Model Trouble ticket items are managed entities, which are relevant within the trouble resolution process and therefore are associated with a trouble ticket. A trouble ticket item is a concretization of a business interaction item. The TroubleTicketItemValue type, as defined in the CBE package does not define any domain specific attributes. It extends the BusinessInteractionItemValue type. Figure 11: TroubleTicketItem Inheritance A TroubleTicketItemValue type defines some very general attributes, which may be used by concrete implementations. There are no attributes specific to the trouble ticket domain. Table 6: Description of Trouble Ticket Item Attributes Attribute Description troubleticketitemkey The key of type TroubleTicketItemKey. The inherited key attributes, which hold the key of this managed entity, must hold the equal key value. So this attribute is a strongly typed alias attribute for businesssinteractionitemkey, entitykey, CBEManagedEntityKey and managedentitykey attributes. Final JSR 91 - Trouble Ticket API page 30 / 65

31 Attribute action quantity Description A business interaction item and so trouble ticket item may represent an action. In this case the attribute value is the name of the action. There may be a need to quantify in trouble ticket items. In this case the value of this attribute holds the quantity Key Types In the data model for each managed entity value type a managed entity key type is defined. For this API the key typed TroubleTicketKey and TroubleTicketItemKey are relevant. These key types are defined by the CBE part. These key type definitions are unspecific regarding the definition of the primarykey attribute. This implies that these key types are abstract and implementations must provide concrete subtypes, which define the type for the primary key attribute. The OSS/J Design Guidelines advise the definition of a managed entity key type for each managed entity value type. From a functional point of view it is sufficient to use a concrete managed entity key type Implementing and Extending the Data Model The trouble ticket data model as defined by the CBE package is an abstract core data model. Thus the types TroubleTicketValue and TroubleTicketItemValue cannot be used directly by implementations. This implies that concrete implementations of the TT API must extend the data model. Spec 4-6: Spec 4-7: Spec 4-8: Spec 4-9: Implementations of the TT API must extend the core trouble ticket data model. Implementations must define and provide at least one concrete trouble ticket type, which extends the type TroubleTicketValue. Implementations must define and provide at least one concrete trouble ticket key type, which extends the type TroubleTicketKey. Implementations may use trouble ticket item values. If implementations want to use trouble ticket items then they Final JSR 91 - Trouble Ticket API page 31 / 65

32 must define and provide at least one concrete trouble ticket item type, which extends the type TroubleTicketItemValue. Spec 4-10: If an implementation uses trouble ticket item values then it must define and provide at least one concrete trouble ticket item key type, which extends the type TroubleTicketItemKey. The reference implementation of this API [OSSJ TT RI] provides an extended data model including concrete definitions of TroubleTicketValue and TroubleTicketItemValue types. Spec 4-11: All extensions of the data model must follow the rules defined in the OSS/J Design Guidelines [OSSJ DG]. This requirement does not only address the extension of managed entity value types but also all other data model related constructs like extensions of enumerations (e.g. TroubleTicketRole, TroubleTicketState). The type PartyValue is used in the data model relevant for this API. PartyValue is a ManagedEntityValue and thus may contain a key. This API offers no operations to manage parties 4. So within this API party values may or may not contain keys depending on the implementation. Spec 4-12: Implementations may support keys in ManagedEntityValue types, which are used in the data model or its extensions, but are not managed by the TT API. 4 Typical CRUD operations like createpartybyvalue. Final JSR 91 - Trouble Ticket API page 32 / 65

33 5 Features/requirements This API provides operations to manage and retrieve trouble tickets and trouble ticket items. This chapter gives an overview of these operations. The description does not address integration profile (JVT, XVT) specifics. This is covered by the following parts of this specification: Part 2 - User Guide [JSR 91-2] contains a more detailed JVT and XVT specific description. Part 3 JVT API [JSR 91-3] a formal description of the operations for the JVT profile Part 4 XVT API [JSR 91-4] a formal description of the operations for the XVT profile Part 5 WS API [JSR 91-5] a formal description of the operations for the Web Service profile Each described operation exists in each integration profile and owns the equivalent semantics in each integration profile. 5.1 Session Façade Operations There are different groups of operations defined by the session façade. meta data operations reading trouble tickets creating trouble tickets updating trouble tickets closing trouble tickets canceling trouble tickets reading trouble ticket items creating trouble ticket items updating trouble ticket items removing trouble ticket items executing named queries executing update procedures Final JSR 91 - Trouble Ticket API page 33 / 65

34 5.1.1 Meta Data Operations Clients can request the capabilities of the OSS/J interface in terms of supported data model and supported operations. Table 7: List of meta data operations Operation getsupportedoptionaloperations getmanagedentitytypes gettroubletickettypes gettroubleticketitemtypes getnamedquerytypes getupdateproceduretypes geteventtypes geteventdescriptor Meaning Get the names of the optional operations supported. Get the managed entity types supported by the implementation. This will return all trouble ticket types and all trouble ticket item types. Since the TT data model is abstract TroubleTicketValue and TroubleTicketItemValue must not be part of the result. Get the trouble ticket types supported by the implementation. Since the TT data model is abstract TroubleTicketValue must not be part of the result. Get the trouble ticket item types supported by the implementation. Since the TT data model is abstract TroubleTicketItemValue must not be part of the result. Get the named query types supported by the implementation. Get the named update procedure types supported by the implementation Get the event types supported by the implementation. Get the event descriptors for a given event type. All meta data operations are mandatory for implementations. Additionally for each trouble ticket, trouble ticket item, query, update procedure and potentially other objects inheriting from AttributeAccess (OSSJ Common API) the model can be explored in more detail. Please have Final JSR 91 - Trouble Ticket API page 34 / 65

35 a look at the OSS/J Common API [JSR 144] and the OSS/J Design Guidelines [OSSJ DG] Managing Entities The TT API provides a set of operations to manage entities of type TroubleTicketValue and TroubleTicketItemValue. These operations cover the functionality to read, create and modify trouble tickets and trouble ticket items. This API additionally defines operations to close and cancel trouble tickets and to remove trouble ticket items. All these operations come in different flavors, which are defined by the OSS/J Design Guidelines [OSSJ DG]. First of all there are simple operations, which are performed on single entities. Additionally there are bulk operations, which are performed on a set of entities. For example settroubleticketbyvalue is the method for updating exactly one ticket. But there are also a couple of options for requesting bulk updates: settroubleticketbyvalue settroubleticketbyvalues trysettroubleticketbyvalues settroubleticketbykeys trysettroubleticketbykeys settroubleticketbytemplate updates one ticket the update value is given including the ticket key updates multiple tickets the update values are given including the ticket keys updates multiple tickets the update values are given including the ticket keys updates multiple tickets the update value is given plus a list of ticket keys for the tickets to be updated updates multiple tickets the update value is given plus a list of ticket keys for the tickets to be updated updates all tickets that match a given template the update value is given atomic best effort atomic best effort atomic Final JSR 91 - Trouble Ticket API page 35 / 65

36 trysettroubleticketbytemplate settroubleticketbytemplates trysettroubleticketbytemplate s Figure 12: Example of different flavors for an operation updates all tickets that match a given template the update value is given updates all tickets that match at least one of the given templates the update value is given updates all tickets that match at least one of the given templates the update value is given best effort atomic best effort All bulk methods are either atomic or best effort. Using best effort bulk operations each update succeeds or fails independently of the others. Best effort operations should be used as an optimization to avoid invocation delays and when it is not necessary to make sure that all the updates are performed as a single unit or in all or nothing fashion. Using atomic bulk operations either all updates succeed or all updates are rolled back. This type of operation should be used when it is necessary to make sure that all the updates are performed as a single unit of work. The only difference in usage for atomic and best effort operations is that each best effort bulk operation returns a summary of its success state, while atomic operations only succeed or throw an exception. This summary consists of instances of TroubleTicketKeyResult or TroubleTicketItemKeyResult. A key result contains the key of the touched ticket or ticket item, a success flag and (if failed) a reason for the failure. Clients can limit the returned key results to failures only. In that case a totally successful operation returns no key results at all, which is an empty array or iterator but not null. In case of failure of a bulk operation it throws an exception, which only indicates why the operation itself failed. Atomic operations may indicate that the failure was caused by one of the operations of the bulk, but does not need to specify which and why this one failed. A failing best effort operation will report the reason for failure of the bulked operations in the corresponding result. The following table lists the available flavors by the basic operations. Basic operation by key by value by keys by values by template by templates Final JSR 91 - Trouble Ticket API page 36 / 65

37 create ticket get ticket set ticket close ticket cancel ticket create ticket item get ticket item set ticket item remove ticket item X X X X X X X X X atomic (by nature) atomic & best effort atomic & best effort atomic & best effort atomic (by nature) atomic & best effort atomic & best effort atomic & best effort atomic & best effort atomic & best effort atomic & best effort atomic (by nature) atomic & best effort atomic & best effort atomic & best effort atomic (by nature) atomic & best effort atomic (by nature) atomic & best effort atomic & best effort atomic & best effort atomic (by nature) atomic & best effort Template Search A template search is a search by example. All tickets or items that match a given ticket or item are retrieved. The matching rules for templates are defined in the OSS/J Design Guidelines [OSSJ DG]. Here is a short explanation: Matching rule: A ticket/item A matches a template T if 1. if T.isPopulated(X) then A.isPopulated(X); and 2. if T.isPopulated(X) then T.getX().equals(A.getX()); for all attributes X apart from the trouble ticket key. Thus the attributes of the templates correspond to conditions concatenated by AND in SQL statements. If searching by multiple templates, all tickets that match at least one template are retrieved. Thus the use of multiple templates corresponds to the OR concatenation in SQL statements. Final JSR 91 - Trouble Ticket API page 37 / 65

38 Bulk Operations without Templates All bulk operations, which do not use templates have a number of returned values clearly defined by its arguments and its type and return these in an array. If the corresponding non-bulk operation returns a value, the bulk operation without template for the same purpose returns as many values, as it has taken tickets or items as argument. If the non- bulk operation returns nothing, the corresponding bulk operation does the same Bulk Operations with Template(s) Naming Mode Operations dosomethingbytemplate(s) raise a template search on the server and perform their operation on each of the results of that search. Therefore it is not known how many targets such an operation has, when it is issued and it may be quite a lot. To handle this possible problem the results of an operation by template(s) are returned as an iterator from which they can be retrieved in charges of restricted size. The second part of this specification [JSR91 Part 2] describes iterators for the different integration profiles in more detail. This API applies the auto-naming mode. This implies that implementations are responsible for providing primary key values for trouble ticket values and trouble ticket item values during creation. Clients must not specify a primary key when invoking a create operation Reading Trouble Tickets There are different flavors of operations to read trouble tickets. A client can retrieve trouble tickets by specifying their keys or by specifying templates. All read operations for trouble tickets have a name starting with gettroubleticketby or gettroubleticketsby. And all these operations take a parameter called attributenames. This parameter is a list of attributes the client requests from the server in order to reduce network load. Only the attributes contained in the list of requested attributes are populated in the received tickets. If any of those are not populated in the ticket itself they won t be populated either, so only the intersection of both is contained in the tickets. Passing null or an empty array of attribute names then the request will be treated as if a complete list of all known attributes would have been passed. The response will always include the troubleticketkey attribute. Final JSR 91 - Trouble Ticket API page 38 / 65

39 5.1.4 Reading Trouble Ticket Items There are different flavors of operations to read trouble ticket items. A client can retrieve trouble ticket items by specifying their keys or by specifying templates. All read operations for trouble ticket items have a name starting with gettroubleticketitemby or gettroubleticketitemsby. And all these operations take a parameter called attributenames. This parameter is a list of attributes the client requests from the server in order to reduce network load. Only the attributes contained in the list of requested attributes are populated in the received trouble ticket items. If any of those are not populated in the ticket itself they won t be populated either, so only the intersection of both is contained in the items. Passing null or an empty array of attribute names then the request will be treated as if a complete list of all known attributes would have been passed. The response will always include the troubleticketitemkey attribute Creating Trouble Tickets Create operations for trouble tickets can be used to create one or more trouble tickets. The operations for creating trouble tickets are createtroubleticketbyvalue, createtroubleticketsbyvalues and trycreatetroubleticketsbyvalues. A client Must specify a trouble ticket value for each trouble ticket it intends to create. Must specify a trouble ticket value, which is instance of one of the types returned by the operation gettroubletickettypes. Must not specify a value for the troubleticketkey attribute (or any other equivalent key attributes) May specify the troubleticketstate attribute. Must not specify any other troubleticketstate value than QUEUED or OPENACTIVE - including their sub states. If a client violates these requirements then the server must respond with an OssIllegalArgumentException. A server Final JSR 91 - Trouble Ticket API page 39 / 65

40 must return a complete unique key in the case of successful creation of the trouble ticket. must return an exception in the case of failure. may use default values for any unspecified attribute. may implicitly change the value of any specified attribute. must set a valid initial state for the trouble ticket if not specified by the client. Valid initial states are QUEUED, OPENACTIVE and any of their sub states. This specification defines no trouble ticket value attributes which must be specified within a create request. An implementation may define required attributes. In the case a client does not provide a value for a required attribute and there is no default value or any other implementation constraint is violated then the server must return a CreateException in case the create operation supports exception propagation Creating Trouble Ticket Items Create operations for trouble ticket items can be used to create one or more trouble ticket items. The operations for creating trouble ticket items are createtroubleticketitembyvalue, createtroubleticketitemsbyvalues and trycreatetroubleticketitemsbyvalues. A client must specify a trouble ticket item value for each trouble ticket item it intends to create. must specify a trouble ticket item value, which is instance of one of the types returned by the operation gettroubleticketitemtypes. must not specify a value for the troubleticketitemkey attribute (or all other equivalent key attributes) If a client violates these requirements then the server must respond with an OssIllegalArgumentException. A server must return a complete unique key in the case of successful creation of the trouble ticket item. must return an exception in the case of failure. may use default values for any unspecified attribute. Final JSR 91 - Trouble Ticket API page 40 / 65

41 may implicitly change the value of any specified attribute. This specification defines no trouble ticket item value attributes which must be specified within a create request. An implementation may define required attributes. In the case a client does not provide a value for a required attribute and there is no default value or any other implementation constraint is violated then the server must return a CreateException in case the create operation supports exception propagation Updating Trouble Tickets Update operations for trouble tickets can be used to update one or more trouble tickets. Updates on trouble tickets can be performed by all operations with the name prefix settroubleticket or trysettroubleticket. As a principle a client has to pass only those attributes to be changed to the server. A client must specify values only for all attributes it intends to change. must specify a valid value for troubleticketstate when it intends to change the trouble tickets state. In this case a state transition is performed. This state transition must be in line with the requirements defined in chapter Trouble Ticket State Model (4.2.3). If a client violates these requirements then the server must respond with an OssIllegalArgumentException. A server must return an response as specified for the concrete operation. must return an exception in the case of failure. may implicitly change the value of any specified or unspecified attribute. must ensure that in the case of a explicit or implicit state transition the transition is valid. Valid state transitions are described in chapter Trouble Ticket State Model (4.2.3). must return a OssSetException if any constraint of the trouble ticket management system would be violated by the update and exception propagation is supported by the concrete operation. Final JSR 91 - Trouble Ticket API page 41 / 65

42 5.1.8 Updating Trouble Ticket Items Update operations for trouble ticket items can be used to update one or more trouble ticket items. Updates on trouble ticket items can be performed by all operations with the name prefix settroubleticketitem or trysettroubleticketitem. As a principle a client has to pass only those attributes to be changed to the server. A client must specify values only for all attributes it intends to change. A server must return an response as specified for the concrete operation. must return an exception in the case of failure. may implicitly change the value of any specified or unspecified attribute. must return a OssSetException if any constraint of the trouble ticket management system would be violated by the update and exception propagation is supported by the concrete operation Stale Values in Updates An attribute called lastupdateversionnumber serves as a version control for each entity. The value of lastupdateversionnumber changes at each update of any other attribute. The attribute is totally server controlled and clients must never set it. A client that got hold of an instance of ManagedEntityValue (e.g. trouble ticket or trouble ticket item) by listening to a notification or running a query or a get-request can use that very instance for updates. Combined with the option resyncrequired = true the server will compare the incoming version number to the current version number. If it is actually different a ResyncRequiredException will be thrown. If it is still the same, the entity will be updated and the version number will be increased. Usage of resyncrequired option for bulk operations. Please see chapter for general info on bulk operations. Final JSR 91 - Trouble Ticket API page 42 / 65

43 Method settroubleticketsbyvalues settroubleticketitemsbyvalues trysettroubleticketsbyvalues trysettroubleticketitemsbyvalues settroubleticketsbykeys settroubleticketitemsbykeys trysettroubleticketsbykeys trysettroubleticketitemsbykeys settroubleticketsbytemplate settroubleticketitemsbytemplate trysettroubleticketsbytemplate trysettroubleticketitemsbytemplate settroubleticketsbytemplates settroubleticketitemsbytemplates Bulk Style atomic best effort atomic best effort atomic best effort atomic Usage of resyncrequired The lastupdateversionnumber of each individual ticket must be equal to the lastupdateversionnumber of each backend managed entity otherwise the ResyncRequiredException exception is raised. Each trouble ticket is updated with the provided values unless the last lastupdateversionnumber of the TroubleTicketValue is not equal to the lastupdateversionnumber of the backend trouble ticket. In this case the TroubleTicketKeyResult for that trouble ticket contains the ResyncRequiredException. Option resyncrequired is not available, lastupdateversionnumber is ignored. Option resyncrequired is not available, lastupdateversionnumber is ignored. Option resyncrequired is not available, lastupdateversionnumber is ignored. Option resyncrequired is not available, lastupdateversionnumber is ignored. Option resyncrequired is not available, lastupdateversionnumber is ignored. Final JSR 91 - Trouble Ticket API page 43 / 65

44 Method trysettroubleticketsbytemplates trysettroubleticketitemsbytemplate s Bulk Style best effort Usage of resyncrequired Option resyncrequired is not available, lastupdateversionnumber is ignored Closing and Canceling Trouble Tickets To transfer a ticket to its final base state CLOSED it can be closed or cancelled, depending on the current state of the trouble ticket. The name, of all close operations, starts with close or tryclose. The name, of all cancel operations, starts with cancel or trycancel. A client must specify a value for the trouble ticket state with a close or cancel request must specify the trouble ticket state CLOSED.CANCELED or a sub state for a cancel operation. must specify the trouble ticket state CLOSED or a sub state but not CLOSED.CANCELED or any of its sub states for close operations. If a client violates these requirements then the server must respond with an OssIllegalArgumentException. A server must ensure that the state transition is valid. Valid state transitions are described in chapter Trouble Ticket State Model (4.2.3). If this constraint is violated then depending on the operation a CloseException or CancelException must be returned if applicable. may define further constraints like preconditions for closing or canceling a trouble ticket. If such constraints are violated then depending on the operation a CloseException or CancelException must be returned if applicable. Closing and canceling trouble tickets can also be achieved by using update operations on trouble tickets Removing Trouble Ticket Items All operations to remove trouble ticket items are optional operations. An implementation may support these operations. The remove operations are Final JSR 91 - Trouble Ticket API page 44 / 65

45 removetroubleticketitembykey, removetroubleticketitemsbykeys and tryremovetroubleticketitemsbykeys. A client must specify the key or the keys of the trouble ticket item or items it intends to remove. If a client violates this requirement then the server must respond with an OssIllegalArgumentException. A server may disallow deletion of trouble ticket items in general. In this case all remove operations are unsupported by the implementation and the server must return an OssUnsupportedOperationException if a remove operation is invoked. must ensure the referential integrity between trouble tickets and trouble ticket items. So an implementation may implicitly remove all relations between trouble tickets and the item when the item will be removed or it may disallow removing trouble ticket items, which are involved in a relation with one or more trouble tickets. In the second case an attempt to remove a trouble ticket item, which is related with a trouble ticket must be answered with a RemoveException. must make sure that after successfully removing a trouble ticket item this item can t be retrieved and that the key of the trouble ticket item is invalid. A trouble ticket item that has been removed cannot be retrieved again by queries or any other requests. As an example the method gettroubleticketitembykey will return an ObjectNotFoundException Executing Named Queries The purpose of named queries is 1. to provide support for complex query behavior and 2. to provide a point of extensibility for concrete implementations. The named query pattern is described in detail in the OSS/J Design Guidelines [OSSJ DG] and the OSS/J Common API [JSR144] defines the operation query, which executes named queries. Final JSR 91 - Trouble Ticket API page 45 / 65

46 A client must specify a query value. must specify a query value, which is instance of one of the types returned by the operation getnamedquerytypes. If a client violates these requirements then the server must respond with an OssIllegalArgumentException. Chapter 5.2 describes the named query types defined for this API Executing Update Procedures The purpose of update procedures is 1. to provide support for complex behavior for changing trouble tickets and items and 2. to provide a point of extensibility for concrete implementations. The update procedure pattern is described in detail in the OSS/J Design Guidelines [OSSJ DG] and the OSS/J Common API [JSR144] defines the operation update, which executes update procedures. A client must specify an update procedure. must specify an update procedure, which is instance of one of the types returned by the operation getupdateproceduretypes. If a client violates these requirements then the server must respond with an OssIllegalArgumentException. Chapter 5.3 describes the update procedure types defined for this API. 5.2 Named Queries The named query mechanism from OSS/J Common API [JSR 144] is used. Basically each query is represented by a value object, carrying the query parameters and a query response (yet another value object) carrying the result of a query. In many cases the result will be an iterator, implementing the OSS/J s iterator interface. Final JSR 91 - Trouble Ticket API page 46 / 65

47 The TT API defines these query types: Named Query Type Query Response Type Meaning AllOpenTroubleTickets QueryValue AllTroubleTicketItems RelatedToTroubleTicket QueryValue TroubleTicketItems RelatedToTroubleTicket QueryValue AllOpenTroubleTickets QueryResponse (iterator based) AllTroubleTicketItems RelatedToTroubleTicket QueryResponse (iterator based) TroubleTicketItems RelatedToTroubleTicket QueryResponse (iterator based) Finds all trouble tickets whose troubleticketstate is not CLOSED or any of its sub states. Finds all ticket items related to a ticket (given by the key) Finds all ticket items related to a ticket (given by the key) that also match one of the given templates. AllTroubleTickets RelatedToTroubleTicketItem QueryValue TroubleTickets RelatedToTroubleTicketItem QueryValue AllTroubleTickets RelatedToTroubleTicketItem QueryResponse (iterator based) TroubleTickets RelatedToTroubleTicketItem QueryResponse (iterator based) This query type extends AllTroubleTicketItems- RelatedToTroubleTicket- QueryValue Finds all trouble tickets related to a ticket item (given by key). Finds all trouble tickets related to a ticket item (given by key) that also match one of the given templates. This query type extends AllTroubleTickets- RelatedToTroubleTicketItem- QueryValue Final JSR 91 - Trouble Ticket API page 47 / 65

48 5.3 Update Procedures The named update procedure mechanism from OSS/J Common API [JSR 144] is used. Basically each update procedure is represented by a value object, carrying the update procedure s parameters and an update procedure response (another value object) carrying the result of the update procedure. The TT API defines these update procedure types: Named Update Procedure Type AssociateTroubleTicketItems UpdateProcedureValue DisassociateTroubleTicketItems UpdateProcedureValue Update Procedure Response Type AssociateTroubleTicketItems UpdateProcedureResponse (void) DisassociateTroubleTicketItems UpdateProcedureResponse (void) Meaning A set of ticket items (given by their keys) is marked as related to a ticket (given by its key). The change will affect the value of the attribute troubleticketite mkeys of the ticket. A set of ticket items (given by their keys) is marked as not being related to a ticket (given by its key). The change will affect the value of the attribute troubleticketite mkeys of the ticket. 5.4 Iterators Because some operations could potentially return large amounts of trouble tickets, the iterator design pattern is used for returning the results. Iterators allow clients to receive the result set in chunks. Clients can specify the maximum size of the chunks. There are basically two types of iterators. Final JSR 91 - Trouble Ticket API page 48 / 65

49 First there are iterators, which contain managed entity values like trouble tickets and trouble ticket items. And iterators of the second type contain key results, which hold the state of operations on a set of managed entities. All iterator types, which are relevant for this API are defined by the OSS/J Common API [JSR 144]. Details of the iterator pattern are defined in the OSS/J Design Guidelines [OSSJ DG]. Additionally an implementation may define additional iterator types for named query or update procedure results. The concrete implementation of iterators is different in the different interaction profiles. The User Guide (Part 2) of this specification covers iterators in more detail. 5.5 Implementing and Extending Operations Spec 5-13: An implementation must support all mandatory operations defined for this API. An operation is mandatory if the list of exceptions, which may be returned as a response, does not include the OssUnsupportedOperationExcpeption. So whether an operation is mandatory or optional is ultimately decided by the JVT interface and the XML Schema definitions provided with this specification and the OSS/J Common API [JSR 144]. The following matrix gives an overview of optional and mandatory operations. Basic operation create ticket get ticket set ticket close ticket cancel ticket by key by value M by keys by values atomic O best effort M by template M M M M M M M atomic O best effort M atomic O best effort M atomic O best effort M atomic O best effort M create M atomic O best effort atomic O best effort M atomic O best effort M atomic O best effort M by templates atomic O best effort M atomic O best effort M atomic O best effort M Final JSR 91 - Trouble Ticket API page 49 / 65

50 ticket item M get ticket M O O O item set ticket M atomic O best effort atomic O best effort O O item M M remove ticket O O item M = Mandatory; O = Optional Please note that some methods related to trouble ticket items are mandatory. However, if an implementation decides to not support any trouble ticket item, clients cannot successfully execute these operations. Spec 5-14: All supported optional operations must be returned by the operation getsupportedoptionaloperations. Applying the rules for mandatory and optional operations then all meta data operations and the operations query and update are mandatory. Nevertheless the support for the named query types and update procedure types defined for this API is not mandatory. Implementations should support the defined named query and update procedure types. Spec 5-15: Spec 5-16: Spec 5-17: An implementation may define further named query types. The definitions must follow the OSS/J Design Guidelines. An implementation may define further update procedure types. The definitions must follow the OSS/J Design Guidelines. An implementation must apply the auto-naming mode for trouble ticket and trouble ticket item values. 5.6 Events If a trouble ticket or a trouble ticket item is created, modified or deleted, clients must be able to track these changes by means of notifications. Final JSR 91 - Trouble Ticket API page 50 / 65

51 General rule: A client that listens to notifications during the whole lifetime of a ticketing system can have exactly the same ticketing data as the server would provide in response to read requests. Notifications are sent independently of how the change had been invoked: a. through the OSS/J interface using the same communication profile b. through the OSS/J interface using a different communication profile c. through a different non-oss/j-based interface (e.g. by means of a user interface directly writing into the trouble ticket management system s database) This API defines different types of events, which are used to notify interested clients. Each event instance describes an event on a single managed entity (trouble ticket or trouble ticket item). The conditions for publishing an event are independent for each event type. So publishing an event of one type does not impact the publishing of an event of another type. This implies that multiple events may be published for a certain change. All event types defined within this API directly or indirectly extend the type Event defined in the OSS/J Common API [JSR 144]. This event base type defines some attributes like eventtime (publishing time), applicationdn, managedobjectclass and managedobjectinstance. Please refer to the JSR 144 specification for a detailed description of this type and its attributes. If multiple changes are applied to a ticket or ticket item by one action the number of notifications shall be as low as possible. Example: Our ticket system is SQL based. The user of a ticketing web application presses a button labeled Save Ticket once. The web application passes the data on and eventually several SQL UPDATE statements are executed for the same trouble ticket, e.g. one statement per changed attribute. Still it is highly recommended to publish just one event Trouble Ticket Events These are the event types for trouble tickets: Final JSR 91 - Trouble Ticket API page 51 / 65

52 Figure 13: Trouble Ticket Event Types Be aware that more than one event may be published for a change. E.g. closing a trouble ticket will result in publishing a TroubleTicketCloseOutEvent, TroubleTicketStateChangeEvent and TroubleTicketAttributeValueChangeEvent. For each event type an event property descriptor type is defined. All trouble ticket related events contain the event property OSS_TROUBLE_TICKET_STATE, which holds the state of the trouble ticket at the time the event is published. Additionally the standard OSS/J event properties are used. TroubleTicketCreateEvent This event will be published when a trouble ticket is created in the trouble ticket management system. The event contains the complete trouble ticket value representing the created trouble ticket including all attributes. This event must be the first event published for a specific trouble ticket. TroubleTicketAttributeValueChangeEvent An existing trouble ticket has been modified and at least one attribute was changed. This includes all attributes. For the attribute Final JSR 91 - Trouble Ticket API page 52 / 65

53 troubleticketitemkeys this implies that in the case trouble ticket items are associated to or disassociated from a trouble ticket then this event must be published. Also a change to the troubleticketstate attribute requires publishing this event. The event must contain a trouble ticket value in the attribute newtroubleticketvalue, which contains all new attribute values of changed attributes. Unchanged attributes should be unpopulated. The attribute oldtroubleticketvalue is optional and if it is present then it holds a trouble ticket value with all changed attributes populated with the old attribute values. If this attribute is not supported then it must always be unpopulated. TroubleTicketStateChangeEvent This event must be published if the troubleticketstate attribute of type TroubleTicketValue changes its value. The event contains the mandatory attribute troubleticketkey which holds the key value of the affected trouble ticket, the mandatory attribute newstate which holds the new trouble ticket state value and the optional attribute oldstate which holds the previous trouble ticket state value. If the optional attribute is not supported than it must be unpopulated in the event. TroubleTicketCloseOutEvent This event must be published if the trouble ticket changes to state CLOSED or one of its sub states but not to state CLOSED.CANCELED and its sub states. This event extends the event type TroubleTicketStateChangeEvent and thus owns the same attributes, which are used in the same way. TroubleTicketCancellationEvent This event must be published if the trouble ticket changes to state CLOSED.CANCELED or one of its sub states. This event extends the event type TroubleTicketStateChangeEvent and thus owns the same attributes, which are used in the same way. Final JSR 91 - Trouble Ticket API page 53 / 65

54 5.6.2 Trouble Ticket Item Events These are the event types for trouble ticket items: Figure 14: Trouble Ticket Item Event Types For each event type an event property descriptor type is defined. All trouble ticket item related events contain no additional event property. So just the standard OSS/J event properties are used. TroubleTicketItemCreateEvent This event will be published when a trouble ticket item is created in the trouble ticket management system. The event contains the complete trouble ticket item value representing the created trouble ticket item including all attributes. This event must be the first event published for a specific trouble ticket item. TroubleTicketItemAttributeValueChangeEvent An existing trouble ticket item has been modified and at least one attribute was changed. This includes all attributes. Final JSR 91 - Trouble Ticket API page 54 / 65

55 The event must contain a trouble ticket item value in the attribute newtroubleticketitemvalue, which contains all new attribute values of changed attributes. Unchanged attributes should be unpopulated. The attribute oldtroubleticketitemvalue is optional and if it is present then it holds a trouble ticket value with all changed attributes populated with the old attribute values. If this attribute is not supported then it must always be unpopulated. TroubleTicketRemoveEvent This event must be published if a trouble ticket item was removed from the trouble ticket management system. The event contains the mandatory attribute troubleticketitemvalue, which holds the complete trouble ticket item data as before deleting Implementing and Extending Events Spec 5-18: An implementation must support all event types defined for this API. If an implementation does not support trouble ticket item types then obviously there is no need to publish trouble ticket item related events. Spec 5-19: Spec 5-20: An implementation may support additional event types. For each additional event type an event descriptor type must be defined. If you decide to add any customized notification types you have to provide the event descriptor interface as well. Please follow the naming conventions as described in OSS/J Common API and Design Guidelines. Example: TroubleTicketEscalationEvent, TroubleTicketEscalationEventPropertyDescriptor. Spec 5-21: The existence of additional event types must not impact the behavior for publishing the predefined event types. Spec 5-22: An implementation may use extended event types instead of the build in types. In this case the extended type must directly or indirectly extend the type which is replaced. Final JSR 91 - Trouble Ticket API page 55 / 65

56 the extended event must meet all requirements defined in this specification for the default event types. the extension must behave identical regarding the event properties. Especially the OSS_EVENT_TYPE property must provide the equal value as defined for the default event types. Final JSR 91 - Trouble Ticket API page 56 / 65

57 6 Relationship to other OSS/J APIs The API has been specified in a way that does not enforce the Implementation to use any other OSS/J APIs yet it has been designed for smooth cooperation with other OSS/J APIs. It is recommended for the API Implementations to take advantage of the other OSS/J APIs. The figure below is an extract from the API Roadmap document. It has been presented here to illustrate that the Trouble Ticket Implementation is expected to cooperate with a number of (etom) process areas, many of them supported with OSS/J APIs. The Figure should not be interpreted as the Trouble Ticket API scope but rather a complete Trouble Ticket System Implementation scope. Figure 15: Relationship to other OSSJ APIs Final JSR 91 - Trouble Ticket API page 57 / 65

58 7 Standards In this API we refer to organisations and other standards working in the related areas. 7.1 Telemanagement Forum (TMF) Next-Generation OSS (NGOSS) has been widely recognized as the industry best effort to facilitate service providers around the world in achieving their business objectives. The areas that NGOSS attempts to address are vast and complex therefore not easy to address. Bridging the gap between the higherlevel processes and concepts and realistic, working implementation has proven to be challenging. In this chapter, we explain the relevance of this API Specification towards NGOSS etom Process Areas From etom point of view, the API supports the process areas as listed in Table 1: Main Use-Cases based on etom 921D release 7.1. There are some areas not directly supported by the API. Although consideration has been made to expose interfaces supporting all of the Level 3 areas, some of them have been excluded they have been considered to lie entirely within the Implementation or are addressed by different APIs Shared Information/Data Model (SID) Domains This API will use the following Aggregate Business Entities (ABE) as defined by TMF s Shared Information/Data Model [SID]. The Java realizations of these entities are the Core Business Entities. TroubleTicket TroubleTicketItem Final JSR 91 - Trouble Ticket API page 58 / 65

59 Figure 16: SID Domains NGOSS Lifecycle and Methodology This document and the API can be used to support NGOSS Scope, Analyze, Normalize, Rationalize, Rectify (SANRR) Methodology [GB927]: Business View Features defined in this document, examples System View interface specification only to specify/identify the System capabilities for interoperability reasons Implementation View contains data models, interfaces, etc. Primary API use area 7.2 Business Process Execution Language (BPEL) While the BPEL definition itself [BPEL] might not have an immediate effect on the specification, especially the Webservices integration profile, this specification needs to be usable in a larger context. Final JSR 91 - Trouble Ticket API page 59 / 65