JSR 91 - OSS Trouble Ticket API Final Overview

(1)

JSR 91 - OSS Trouble Ticket API

Final - 1.1

Overview

OSS through Java™ Initiative

Michael Nidel, FROX communication TT-API-SPEC_PART1_OVERVIEW.1.1.doc

(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.

(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.

(4)

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

(7)

o http://www.jcp.org/

o http://java.sun.com.products/oss

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

(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

2002-02-02 1.0 _{Pierre Gauthier} Final Release 2006-06-30 1.1 _{Axel Terfloth,}

Traugott Dittmann

Maintenance Release 2006-12-13 1.1.1 _{Michael Nidel} Maintenance

Release

(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.

(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.

(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

(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.

(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 specification1, but WS profile will soon be added.

(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)

(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.

(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.

(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.

(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.

4.3.1 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.

4.3.2 The Type Perspective

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.

4.3.3 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.

(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.

(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 model2.

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 API3. 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

(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 actions4.

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

(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 The point in time when the trouble report was received. It is not necessarily the creation time of the trouble ticket. interactionDateComplete The point in time when the trouble

resolution process was finished. This is typically the time when the trouble ticket enters the state CLOSED.

businessInteractionState 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 The description of the interaction. troubleTicketState The state of a trouble ticket. troubleDescription The description of the trouble.

roleAssignments Contains a list involved parties and their roles.

troubleDetectionTime The point in time when the trouble was detected. This time is typically before the time the trouble was reported

(interactionDate).

serviceRestoredTime The point in time when the affected service was or will be restored.

(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

roleName The name of the role. The possible values must be defined by enumerations. The enumeration TroubleTicketRole defines a single enumeration value ‘ORIGINATOR’. assignedParty The value represents the assigned party.

(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 standard5.

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.

(25)

Figure 9: Enumerations for Trouble Ticket States

5.2.1 Meaning of Base States

The following table explains the meaning of the base states.

Table 3: Meaning of Base States State Meaning

QUEUED Trouble resolution has not yet been initiated.

OPEN/ACTIVATE Appropriate actions to resolve the reported trouble are being carried out.

DEFERRED The corrective action has been postponed.

CLEARED Trouble has been corrected, awaiting verification.

CLOSED Trouble resolution process is finished. The trouble was solved and resolution verified.

(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

T o Q U E U E D T o O P E N A C T IV E T o D E F E R R E D T o C L E A R E D T o C L O S E D T o C L O S E D . C A N C E L E D

From not existing

(initial states) yes Yes no no no no

From

QUEUED (yes) yes no no no yes

From

OPENACTIVE No (yes) yes yes no yes

From

DEFERRED no yes (yes) no no yes

From

CLEARED no yes no (yes) yes yes

From CLOSED no no no no (yes) no From CLOSED. CANCELED no no no no no (yes)

5.2.3 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

(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

(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.

(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

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 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.

(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.

(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 parties6. 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.

(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

(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. Since the TT data model is abstract TroubleTicketValue must not be part of the result.

getTroubleTicketItemTypes 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

Get the event descriptors for a given event type.

(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  updates one ticket  the update value is given

including the ticket key setTroubleTicketByValues  updates multiple tickets

 the update values are given including the ticket keys

atomic

trySetTroubleTicketByValues  updates multiple tickets  the update values are

given including the ticket keys

best effort

setTroubleTicketByKeys  updates multiple tickets  the update values is given

plus a list of ticket keys for the tickets to be updated

atomic

trySetTroubleTicketByKeys  updates multiple tickets  the update value is given

plus a list of ticket keys for the tickets to be updated

best effort

setTroubleTicketByTemplate  updates all tickets that match a given template  the update value is given

atomic

trySetTroubleTicketByTemplate  updates all tickets that match a given template

best effort

(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

best effort

Figure 11 Example of different flavors for an operation

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.

(36)

nature) set ticket X atomic &

best effort atomic & best effort atomic & best effort atomic & best effort close ticket X atomic &

best effort

atomic & best effort

atomic & best effort cancel ticket X atomic &

best effort atomic & best effort atomic & best effort create ticket item X atomic & best effort get ticket item X

atomic (by nature) atomic (by nature) atomic (by nature) set ticket item X atomic &

best effort atomic & best effort atomic & best effort atomic & best effort remove ticket item X atomic & best effort

6.1.2.1 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.

(37)

it has taken tickets or items as argument. If the non-bulk operation returns nothing, the corresponding bulk operation does the same.

6.1.2.3 Bulk Operations with Template(s)

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.

6.1.2.4 Naming Mode

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.

6.1.3 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.

(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.

6.1.5 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.

(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.

6.1.6 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).

A server

• Must return a complete unique key in the case of successful creation of the trouble ticket item.

(40)

constraint is violated then the server must return a CreateException in the case the create operation supports exception propagation.

6.1.7 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’ (5.2). 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’ (5.2).

• 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.

6.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

(41)

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 a 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.

6.1.9 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.

(42)

Method Bulk Style Usage of resyncRequired setTroubleTicketsByValues setTroubleTicketItemsByValues atomic The lastUpdateVersionNumber of each individual ticket must be equal to the lastUpdateVersionNumber of each backend managed entity otherwise the ResyncRequiredException exception is raised. trySetTroubleTicketsByValues trySetTroubleTicketItemsByValues best effort

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 exception.

setTroubleTicketsByKeys setTroubleTicketItemsByKeys

atomic Option resyncRequired is not available, lastUpdateVersionNumber is ignored. trySetTroubleTicketsByKeys trySetTroubleTicketItemsByKeys best effort Option resyncRequired is not available, lastUpdateVersionNumber is ignored. setTroubleTicketsByTemplate setTroubleTicketItemsByTemplate

atomic Option resyncRequired is not available, lastUpdateVersionNumber is ignored. trySetTroubleTicketsByTemplate trySetTroubleTicketItemsByTemplate best effort Option resyncRequired is not available, lastUpdateVersionNumber is ignored. setTroubleTicketsByTemplates setTroubleTicketItemsByTemplates

atomic Option resyncRequired is not available,

(43)

Method Bulk Style Usage of resyncRequired trySetTroubleTicketsByTemplates trySetTroubleTicketItemsByTemplates best effort Option resyncRequired is not available, lastUpdateVersionNumber is ignored.

6.1.10 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 a sub state for close operations.

A server

• Must ensure that the state transition is valid. Valid state transitions are described in chapter ‘Trouble Ticket State Model’ (5.2). 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

(44)

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.

6.1.12 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.

(45)

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.

Chapter 6.2 describes the named query types defined for this API.

6.1.13 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 a update procedure.

• Must specify a update procedure, which is instance of one of the types returned by the operation getUpdateProcedureTypes.

(46)

The TT API defines these query types:

Named Query Type Query Response Type Meaning

Query

AllOpenTroubleTickets

Value

QueryTroubleTicketsResponse (iterator based)

A trouble ticket is found, if the troubleTicketState does not start with CLOSED. Query AllTroubleTicketItems

RelatedToTroubleTicket

Value

QueryTroubleTicketItemsResponse (iterator based)

Finds all ticket items related to a ticket (given by the key) Query TroubleTicketItems RelatedToTroubleTicket Value Query TroubleTicketItems Response (iterator based)

Finds all ticket items related to a ticket (given by the key) that also match one of the given templates.

This query type extends Query- AllTroubleTicketItems- RelatedToTroubleTicket-Value Query AllTroubleTickets RelatedToTroubleTicketItem Value

Query TroubleTickets Response (iterator based)

Finds all trouble tickets related to a ticket item (given by key).

Query TroubleTickets

RelatedToTroubleTicketItem

Value

Query TroubleTickets Response (iterator based)

Finds all trouble tickets related to a ticket item (given by key) that also match one of the given templates. This query type extends Query-AllTroubleTickets- RelatedToTroubleTicketItem-Value

(47)

6.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 Update Procedure Response Type Meaning Upv AssociateTroubleTicketItems Value Upv AssociateTroubleTicketItems Response (void) 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. Upv DisassociateTroubleTicketItems Value Upv DisassociateTroubleTicketItem s Response (void) 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.

(48)

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

6.5 Implementing and Extending Operations

Spec 6-1: 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 b y k ey b y v a lu e b y k ey s b y v a lu es b y te m p la te b y te m p la te s create ticket M atomic O best effort M get ticket M M M M set ticket M atomic O best effort M atomic O best effort M atomic O best effort M atomic O best effort M close ticket M atomic O best effort M atomic O best effort M atomic O best effort M cancel ticket M atomic O best effort atomic O best effort atomic O best effort

(49)

item get ticket item M O O O set ticket item M atomic O best effort M atomic O best effort M O O remove ticket item O O 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 6-2: 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 6-3: An implementation may define further named query types. The definitions must follow the OSS/J Design Guidelines. Spec 6-4: An implementation may define further update procedure

types. The definitions must follow the OSS/J Design Guidelines.

Spec 6-5: An implementation must apply the auto-naming mode for trouble ticket and trouble ticket item values.

(50)

7 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.

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.

(51)

7.1 Trouble Ticket Events

These are the event types for trouble tickets:

Figure 12: Trouble Ticket Event Types

Be aware that more than one event may be published for a change. For instance, 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

(52)

TroubleTicketAttributeValueChangeEvent

An existing trouble ticket has been modified and at least one attribute was changed. This includes all attributes. For the attribute 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.

(53)

This event extends the event type TroubleTicketStateChangeEvent and thus owns the same attributes, which are used in the same way.

7.2 Trouble Ticket Item Events

These are the event types for trouble ticket items:

Figure 13: Trouble Ticket Item Event Types

For each event type an event property descriptor type is defined. All trouble ticket related events contain no additional event property. So just the standard OSS/J event properties are used.