User Guide FIT Trouble Ticket API
AG-FIT 621
Release 0.0.1 (Build 846) 2026-03-16 in development
Release notes
Please see the version history for the list of changes in the last versions.
Description
The Trouble Ticket API provides a standardized client interface to Trouble Ticket Management Systems for creating, tracking and managing trouble tickets as a result of an issue or problem identified by a customer or another system. Examples of Trouble Ticket API originators (clients) include CRM applications, network management or fault management systems, or other Trouble Ticket management systems (e.g. B2B). The API supports the ability to send requests to create a new trouble ticket specifying the nature and severity of the trouble or issue as well as all necessary related information. The API also includes mechanisms to search for and update existing trouble tickets. Notifications are defined to provide information when a trouble ticket has been updated, including status changes. A basic set of states of a trouble ticket has been specified (as an example) to handle trouble ticket lifecycle management.
Resources
-A trouble ticket represents a record, or an issue raised by requestor that need to be solved, used for reporting and managing the resolution of problems, incidents or request -Main trouble ticket attributes are its description, severity, type, related dates (creation, expected resolution, resolution), state and related information (change message and change date), related parties (originator, owner, reviser, etc.), related entities (product, product order, customer bill) and notes
Operations
-Retrieval of a trouble ticket or a collection of trouble ticket depending on filter criteria -Partial update of a trouble ticket -Creation of a trouble ticket
Notification of events on trouble ticket
-Trouble ticket state change
-Trouble ticket attribute value change
-Trouble ticket resolved
-Trouble ticket delete (typically restricted to admin role)
-Trouble ticket created
-Trouble ticket Information required
Trouble Ticket API performs the following operations on trouble ticket specification
-Retrieval of a trouble ticket specification or a collection of trouble ticket specification depending on filter criteria -Partial update of a trouble ticket specification -Creation of a trouble ticket specification -Notification of events on trouble ticket specification: -Trouble ticket specification state change -Trouble ticket specification attribute value change -Trouble ticket specification delete (typically restricted to admin role) -Trouble ticket specification created
TMF API Reference
TMF API Reference : TMF - 621 Trouble Ticket
FIT Adaptations
TroubleTicket: - PATCH & DELETE are not used for FIT - Added Milestone / JeopardyAlert adapted to FIT requirements
TroubleTicketSpecification: POST, PATCH & DELETE are not used for FIT
Added Task resources: CancelTroubleTicket & InflightChangeTroubleTicket
TroubleTicket strongly-typed extension @FaultTicket: AgreementRefOrValue, TimeSlot, Appointment, faultDescriptionMessage, resolutionDisputeReason, expressFaultResolution, interimMessageRequested, endUserContactAllowed
Sources
The source API definition can be found at fit-tmf621.yaml
Documentation for API Endpoints
All URIs are relative to https://api.example.org/tmf-api/troubleTicketManagement/v5
| Method | HTTP request | Description |
|---|---|---|
| createCancelTroubleTicket | POST /cancelTroubleTicket | Creates a CancelTroubleTicket |
| listCancelTroubleTicket | GET /cancelTroubleTicket | List or find CancelTroubleTicket objects |
| retrieveCancelTroubleTicket | GET /cancelTroubleTicket/{id} | Retrieves a CancelTroubleTicket by ID |
| createInflightChangeTroubleTicket | POST /inflightChangeTroubleTicket | Creates a InflightChangeTroubleTicket |
| listInflightChangeTroubleTicket | GET /inflightChangeTroubleTicket | List or find InflightChangeTroubleTicket objects |
| retrieveInflightChangeTroubleTicket | GET /inflightChangeTroubleTicket/{id} | Retrieves a InflightChangeTroubleTicket by ID |
| listenToCancelTroubleTicketStateChangeEvent | POST /listener/cancelTroubleTicketStateChangeEvent | Client listener for entity CancelTroubleTicketStateChangeEvent |
| listenToInflightChangeTroubleTicketStateChangeEvent | POST /listener/inflightChangeTroubleTicketStateChangeEvent | Client listener for entity InflightChangeTroubleTicketStateChangeEvent |
| listenToTroubleTicketJeopardyAlertEvent | POST /listener/troubleTicketJeopardyAlertEvent | Client listener for entity TroubleTicketJeopardyAlertEvent |
| listenToTroubleTicketMilestoneEvent | POST /listener/troubleTicketMilestoneEvent | Client listener for entity TroubleTicketMilestoneEvent |
| troubleTicketAttributeValueChangeEvent | POST /listener/troubleTicketAttributeValueChangeEvent | Client listener for entity TroubleTicketAttributeValueChangeEvent |
| troubleTicketCreateEvent | POST /listener/troubleTicketCreateEvent | Client listener for entity TroubleTicketCreateEvent |
| troubleTicketInformationRequiredEvent | POST /listener/troubleTicketInformationRequiredEvent | Client listener for entity TroubleTicketInformationRequiredEvent |
| troubleTicketResolvedEvent | POST /listener/troubleTicketResolvedEvent | Client listener for entity TroubleTicketResolvedEvent |
| troubleTicketSpecificationAttributeValueChangeEvent | POST /listener/troubleTicketSpecificationAttributeValueChangeEvent | Client listener for entity TroubleTicketSpecificationCreateEvent |
| troubleTicketSpecificationCreateEvent | POST /listener/troubleTicketSpecificationCreateEvent | Client listener for entity TroubleTicketSpecificationCreateEvent |
| troubleTicketSpecificationDeleteEvent | POST /listener/troubleTicketSpecificationDeleteEvent | Client listener for entity TroubleTicketSpecificationCreateEvent |
| troubleTicketSpecificationStatusChangeEvent | POST /listener/troubleTicketSpecificationStatusChangeEvent | Client listener for entity TroubleTicketSpecificationCreateEvent |
| troubleTicketStatusChangeEvent | POST /listener/troubleTicketStatusChangeEvent | Client listener for entity TroubleTicketStatusChangeEvent |
| createTroubleTicket | POST /troubleTicket | Creates a TroubleTicket |
| listTroubleTicket | GET /troubleTicket | List or find TroubleTicket objects |
| retrieveTroubleTicket | GET /troubleTicket/{id} | Retrieves a TroubleTicket by ID |
| listTroubleTicketSpecification | GET /troubleTicketSpecification | List or find TroubleTicketSpecification objects |
| retrieveTroubleTicketSpecification | GET /troubleTicketSpecification/{id} | Retrieves a TroubleTicketSpecification by ID |
Documentation for Authorization
OAuth2ClientCredentials
- Type: OAuth
-
Flow: clientCredentials
-
Token URL: https://auth.example.org/oauth2/token/
- Scopes:
- read: read objects
- write: write objects
This API can be secured using OAuth 2.0. OAuth separates the authentication provider from the resource. The authorization server issues access tokens which are used to access the protected resource. This allows consumption of the API without sharing credentials with the API provider. OAuth 2.0 is implemented in various ways using flows. The most common flow for machine-to-machine interfaces is the Client Credentials flow. This is the flow used for this API. Below is a sequence diagram illustrating the Client Credentials flow.
See also Api Authentifizierung
Sample use cases
**TODO API Doc: Similar to TMF "SAMPLE USE CASES" add sequential (?) diagrams for creation and modification such as cancellation or rescheduling **
Resource model
Managed Entity and Task Resource Models
Trouble Ticket resource
A trouble ticket represents a record, or an issue raised by requestor that needs to be solved, used for reporting and managing the resolution of problems, incidents or request.
Resource model
Lifecycle
TODO API Doc: Update the state diagramm and states
...