JSR 91 - OSS Trouble Ticket API Final Overview

Transcription

1 JSR 91 - OSS Trouble Ticket API Final Overview OSS through Java Initiative Michael Nidel, FROX communication TT-API-SPEC_PART1_OVERVIEW.1.1.doc Copyright The Members of the OSS through Java Initiative. All rights reserved. Use is subject to license terms. Final JSR 91 - OSS Trouble Ticket API page 1 / 58

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 supporting creation management and tracking of Trouble Tickets and related information. Final JSR 91 - OSS Trouble Ticket API page 2 / 58

3 Acknowledgements This version (1.1) of the specification is based on the work of Pierre Gauthier (Metasolv) who led the specification of version 1.0. Thanks to everyone who was involved in creating this version of the specification by contributing content, ideas and feedback: Axel Terfloth (IP VALUE) who was the Specification Lead for version 1.1 and, therefore, wrote the majority of this specification document. Amit Kumar Varshney (Wipro) and his colleagues who implemented the RI. Ramin Roham-Pour (IP VALUE) who implemented the TCK for this API. Traugott Dittmann (IP VALUE) who directly contributed to the specification. Vincent Perrot (Sun Microsystems) who provided valuable advice. Final JSR 91 - OSS Trouble Ticket API page 3 / 58

4 Table of Contents Executive Summary 2 Acknowledgements 3 Table of Contents 4 1 Preface Objectives Audience Approval and Distribution Related Specifications and Information How this Specification is organized Revision History 8 2 Introduction Notable Changes to OSS Trouble Ticket API OSS Overview 11 4 Architecture JVT Integration Profile XVT Integration Profile Data Model Perspectives The Content Perspective The Type Perspective The Extension Perspective 18 5 Data Model 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 30 Final JSR 91 - OSS Trouble Ticket API page 4 / 58

5 6 API Operations 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 48 7 Events Trouble Ticket Events Trouble Ticket Item Events Implementing and Extending Events 54 8 Required for Certification 56 Appendix A Glossary and References 57 A.1. Glossary 57 A.2. References 57 Appendix B Specification Summary 58 Final JSR 91 - OSS Trouble Ticket API page 5 / 58

6 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 Specification follows the Java Community Process SM and is referenced as JSR 91. This version of the specification corresponds to the first maintenance release of the JCP SM process also known as Final Release - version 1.1. The latest version of this specification is available for download from the following web sites: o Final JSR 91 - OSS Trouble Ticket API page 6 / 58

7 o o 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 approved by this expert group. 1.4 Related Specifications and 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 version 1.4 [JSR 144] OSS/J J2EE Design Guidelines: general guidelines and patterns that apply to all OSS/J APIs - Draft of OSS through Java Design Guidelines v 1.2 [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 defines 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 TMF website. General OSS/J documents and presentations from [OSSJ] Final JSR 91 - OSS Trouble Ticket API page 7 / 58

8 1.5 How this Specification is organized This specification consists of four (4) parts: Overview of the OSS Trouble Ticket API (This document, Part 1): it gives the main principles, and architecture. Users Guide of the OSS Trouble Ticket API (Part 2): it specifies the interface and all components definitions. Java interface references (Part 3) XML reference (Part 4): it details the XML schemas This specification currently does not cover the Web-Services integration profile. 1.6 Revision History Date Version Author State Comments 2001-Apr 0.1 Pierre Gauthier Draft Pierre Gauthier Final Release Axel Terfloth, Traugott Dittmann Maintenance Release Michael Nidel Maintenance Release Update to COM 1.4 Final JSR 91 - OSS Trouble Ticket API page 8 / 58

9 2 Introduction This document specifies the OSS/J Trouble Ticket Application Programming Interface (API) version 1.1 as defined in the OSS/J API Roadmap document [OSSJ Roadmap]. This API has been defined within the scope of Java Specification Request 91 (JSR 91). It covers a description of: Changes to version 1.0 of the OSS Trouble Ticket API Architecture Communication Profiles Data model Trouble Ticket State Model Trouble Ticket Management Operations Events API Extensibility Implementation constraints Certification As described in chapter 1.4, the API follows the OSS/J Design Guidelines [OSSJ DG] and is based on the OSS Common API. This has impact on the API design goals: Reducing learning effort due to similar structure as other OSS/J APIs. The core Trouble Ticket data model is defined by the SID compliant Core Business Entities included in the OSS Common API. The same functionality will be exposed via two integration profiles the JVT and the XVT profile. The API is prepared to support the third Web-Services based profile. The API is not tied to any specific approach, product or scenario Support for basic as well as more complex operations Extensibility of the interface Final JSR 91 - OSS Trouble Ticket API page 9 / 58

10 2.1 Notable Changes to OSS Trouble Ticket API 1.0 The data model for this API is now compliant to the SID/CBE. The base trouble ticket data model (TroubleTicketValue) has been moved to OSS/J Common API (JSR 089) which defines a SID/CBE compliant core data model. The trouble ticket data model used by version 1.0 of this API was based on the ITU-T X.790 standard [ITU X790]. This data model has been replaced by a more generic and SID/CBE compliant data model. This decision has been taken in order to grant more freedom to implementers. Today, only a minority of operational ticketing systems implements the X.790 data model. The X.790 data model is more or less dedicated to landline troubles and includes attributes that many service providers do not require. Even though the X.790 ticket model cannot be part of the OSS/J TT API anymore, it is available for implementers as part of the OSS/J s open source eco system [OSSJ X790]. If the model is required in a project we highly recommend reusing the interfaces from there. All escalation operations have been removed from the API. These operations were specific for the X.790 based data model. The trouble ticket state model has become more flexible. The cross reference to the OSS/J QoS API has been removed. This reference had been used for attaching alarm information to trouble tickets. This will still be possible using the more general approach of attaching trouble ticket items. Trouble ticket items have been introduced to the TT API. A trouble ticket item can be any sort of object that is related to a ticket. Good examples are alarms, services, resources or customers. Implementers will need to extend the TroubleTicketItemValue interface. They can decide whether to include only a link to the related object (e.g. the alarm key) or some or all of the object s data. New operations, named queries and update procedures for trouble ticket items have been added. Final JSR 91 - OSS Trouble Ticket API page 10 / 58

11 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 ticketing 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 - OSS Trouble Ticket API page 11 / 58

12 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 rejected 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 - OSS Trouble Ticket API page 12 / 58

13 4 Architecture The architecture of the OSS Trouble Ticket API follows the architecture defined by the OSS/J Common Design Guidelines [OSSJ DG] and OSS Common API [JSR 144]. Take a look at these documents for more details. 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. 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. For instance, 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) The WS profile is not included in this specification 1, but WS profile will soon be added. 1 There is a prototype available (RI and TCK) for TT API 1.0. Final JSR 91 - OSS Trouble Ticket API page 13 / 58

14 Figure 2: 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. 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) Final JSR 91 - OSS Trouble Ticket API page 14 / 58

15 JVT XVT WS 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 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. Final JSR 91 - OSS Trouble Ticket API page 15 / 58

16 4.1 JVT Integration Profile Figure 3: Resources of the JVT Integration Profile The JVT integration profile is EJB based. The JVT implementation (the server) provides resources, which client 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 - OSS Trouble Ticket API page 16 / 58

17 4.2 XVT Integration Profile Figure 4: Resources of the XVT Integration Profile The XVT integration profile is JMS and XML based. So, all requests, responses, and data are passed as XML document to and from the server. The XVT implementation (the server) provides resources which client 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 A 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. Final JSR 91 - OSS Trouble Ticket API page 17 / 58

18 4.3 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: The Type Perspective 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. There 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 is used for the JVT integration profile and the other for the XML based integration profiles. Both types of data models for an OSS/J API must be equivalent regarding their semantics. The OSS/J Design Guidelines define constraints on how OSS/J data model must be defined in both model types. Further, they defines 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 an vice versa 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. Final JSR 91 - OSS Trouble Ticket API page 18 / 58

19 Figure 5: 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 - OSS Trouble Ticket API page 19 / 58

20 5 Data Model The data model relevant for this API is not part of this specification but is defined in the CBE part of the OSS Common API [JSR 144]. This section gives a description of this data model 2. 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 [JSR144 Part 3] and XML-Schema definitions [JSR144 Part 4], which are part of the OSS Common API 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 3. 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. This package also contains the complex data type TroubleTicketRoleAssignment. Its intended use is to 2 There have been major changes to the data model used in version 1.0 of this API. These differences are described in section The figure does not show all data types. E.g. key and enumeration types were left away. Final JSR 91 - OSS Trouble Ticket API page 20 / 58

21 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 4. TroubleTicketValue inherits from type BusinessInteractionValue and TroubleTicketItemValue inherits from BusinessInteractionItemValue. Both super types are located in the CBE-BusinessInteraction package. 5.1 Trouble Ticket Model Figure 7: 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. 4 The JSR91 Reference Implementation implements a concrete TroubleTicketItemValue subtype. Final JSR 91 - OSS Trouble Ticket API page 21 / 58

22 Table 1: 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. interactiondate interactiondatecomplete businessinteractionstate The point in time when the trouble report was received. It is not necessarily the creation time of the trouble ticket. The point in 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. businessinteractionitemkeys This attribute value equals the value of the troubleticketitemkeys attribute. description troubleticketstate troubledescription roleassignments troubledetectiontime servicerestoredtime troubleticketitemkeys The description of the interaction. The state of a trouble ticket. The description of the trouble. Contains a list involved parties and their roles. The point in time when the trouble was detected. This time is typically before the time the trouble was reported (interactiondate). The point in 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. Final JSR 91 - OSS Trouble Ticket API page 22 / 58

23 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. Table 2: 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. Final JSR 91 - OSS Trouble Ticket API page 23 / 58

24 5.2 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 5. The state of a trouble ticket is maintained in the attribute troubleticketstate. Figure 8: Base trouble ticket state model The state names are defined by the enumeration TroubleTicketState as defined in the Common/CBE API. The TroubleTicketState enumeration extension defined in the TT API adds the definition for the CLOSED.CANCELED sub state. 5 Please note that the base state DISABLED has been removed from 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 - OSS Trouble Ticket API page 24 / 58

25 Figure 9: Enumerations for Trouble Ticket States Meaning of Base States The following table explains the meaning of the base states. Table 3: Meaning of Base States State QUEUED OPEN/ACTIVATE DEFERRED CLEARED CLOSED Meaning Trouble resolution has not yet been initiated. 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. CLOSED.CANCELED 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 Final JSR 91 - OSS Trouble Ticket API page 25 / 58

26 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 4: 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) Implementing and Extending the State Model Spec 5-1: Implementations must not allow invalid state transitions Spec 5-2: Implementations must not disallow valid state transitions, if the destination state is supported by the implementation Spec 5-3: Implementations may use only a subset of base states. Spec 5-4: Implementations may extend the state model. The defined constraints on state transitions must not be violated. Spec 5-5: 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 Final JSR 91 - OSS Trouble Ticket API page 26 / 58

27 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 knew 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 model are recommended to use these values in combination with the new troubleticketstate attribute. 5.3 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 Final JSR 91 - OSS Trouble Ticket API page 27 / 58

28 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: QueryAllTroubleTicketItemsRelatedToTroubleTicketValue QueryTroubleTicketItemsRelatedToTroubleTicketValue 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: QueryAllTroubleTicketsRelatedToTroubleTicketItem QueryTroubleTicketsRelatedToTroubleTicketItem 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 UpvAddTroubleTicketItemsValue If you want to remove 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 UpvRemoveTroubleTicketItemsValue. 5.4 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 Common/CBE API, does not define any domain specific attributes. It extends the BusinessInteractionItemValue type. Final JSR 91 - OSS Trouble Ticket API page 28 / 58

29 Figure 10: Enumerations for Trouble Ticket States 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 5: 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. Action Quantity 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 trouble ticket items. In this case the value of this attribute holds the quantity. Final JSR 91 - OSS Trouble Ticket API page 29 / 58

30 5.5 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 of the OSS/J Common API [JSR 144]. 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 advises 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. 5.6 Implementing and Extending the Data Model The trouble ticket data model as defined by the CBE part of the OSS Common API [JSR 144] 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 5-6: Implementations of the TT API must extend the core trouble ticket data model. Spec 5-7: Implementations must define and provide at least one concrete trouble ticket type, which extends the type TroubleTicketValue. Spec 5-8: Implementations must define and provide at least one concrete trouble ticket key type, which extends the type TroubleTicketKey. Spec 5-9: Implementations may use trouble ticket item values. If implementations want to use trouble ticket items then they must define and provide at least one concrete trouble ticket item type, which extends the type TroubleTicketItemValue. Spec 5-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 5-11: All extensions of the data model must follow the rules defined in the OSS/J Design Guidelines [OSSJ DG]. Final JSR 91 - OSS Trouble Ticket API page 30 / 58

31 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 6. So within this API party values may or may not contain keys depending on the implementation. Spec 5-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. 6 Typical CRUD operations like createpartybyvalue. Final JSR 91 - OSS Trouble Ticket API page 31 / 58

32 6 API Operations 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 descriptions. 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 Each described operation exists in each integration profile and owns the equivalent semantics in each integration profile. 6.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 Meta Data Operations Clients can request the capabilities of the OSS/J interface in terms of supported data model and supported operations. Final JSR 91 - OSS Trouble Ticket API page 32 / 58

33 Table 6: List of meta data operations Operation Meaning getsupportedoptionaloperations Get the names of the optional operations supported. getmanagedentitytypes 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. gettroubletickettypes Get the trouble ticket types supported by the implementation. gettroubleticketitemtypes 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. getnamedquerytypes Get the named query types supported by the implementation. getupdateproceduretypes Get the named update procedure types supported by the implementation geteventtypes Get the event types supported by the implementation. geteventdescriptor All meta data operations are mandatory for implementations. Get the event descriptors for a given event type. 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 a look at the OSS/J Common API [JSR 144] and the OSS/J Design Guidelines [OSSJ DG]. Final JSR 91 - OSS Trouble Ticket API page 33 / 58

34 6.1.2 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 trysettroubleticketbytemplate settroubleticketbytemplates 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 values 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 updates all tickets that match a given template the update value is given updates all tickets that match at least one of the atomic best effort atomic best effort atomic best effort atomic Final JSR 91 - OSS Trouble Ticket API page 34 / 58

35 given templates the update value is given trysettroubleticketbytemplates updates all tickets that match at least one of the given templates the update value is given Figure 11 Example of different flavors for an operation 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 create ticket get ticket by key X by value X by keys atomic (by by values atomic & best effort by template atomic (by nature) by templates atomic (by nature) Final JSR 91 - OSS Trouble Ticket API page 35 / 58

36 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 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 & best effort atomic & best effort atomic (by nature) atomic & best effort 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 Bulk Operations without Templates All bulk operations, which do not use templates have a number of retuned 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 Final JSR 91 - OSS Trouble Ticket API page 36 / 58

37 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 ticket. 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 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 Final JSR 91 - OSS Trouble Ticket API page 37 / 58

38 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 item. 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 item. 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 all 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 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. Final JSR 91 - OSS Trouble Ticket API page 38 / 58

39 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 the 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. 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 Final JSR 91 - OSS Trouble Ticket API page 39 / 58