FIT Trouble Ticket API

AG-FIT 621

Release Value

Version

1.1.0

Date

2026-09-01

State

pre-released

Description

The Trouble Ticket API provides a standardized interface for creating, tracking, and managing trouble tickets raised by customers or other systems. It also provides task resources and notifications for the trouble-ticket lifecycle.

See Entstörauftrag for sample use cases.

FIT adaptations

The FIT profile is based on the TM Forum Trouble Ticket Management API and applies a number of FIT-specific adaptations.

The following operations and resource extensions differ from the base TM Forum API:

  • PATCH and DELETE operations on TroubleTicket are not used in the FIT profile.

  • Milestone and jeopardy handling is adapted to the requirements of the FIT trouble-ticket lifecycle.

  • POST, PATCH, and DELETE operations on TroubleTicketSpecification are not used in the FIT profile.

  • The task resources CancelTroubleTicket and InflightChangeTroubleTicket are added to support cancellation and changes to an existing trouble ticket.

  • FaultTicket extends the Trouble Ticket resource model with attributes required for FIT fault-management use cases.

The complete FIT-specific resource definitions and supported operations are documented in the API reference.

Managed entity resource model

Trouble Ticket

A trouble ticket records an issue raised by a requester that needs to be resolved.

Lifecycle

Trouble Ticket lifecycle

Resource model

Fault Ticket resource model

JSON representation sample

{
  "$schema" : "../schema/fit-tmf621.schema.json",
  "@type" : "FaultTicket_FVO",
  "description" : "Internetverbindung fällt mehrmals pro Tag aus",
  "orderPostedDate" : "2024-02-08T08:00:00+01:00",
  "ticketType" : "fault",
  "requestedResolutionDate" : "2024-03-08T00:00:00+01:00",
  "externalIdentifier" : [ {
    "@type" : "ExternalIdentifier",
    "id" : "1000222",
    "externalIdentifierType" : "troubleTicketExternalId",
    "owner" : "DEU.VFD"
  } ],
  "relatedEntity" : [ {
    "@type" : "RelatedEntityRefOrValue",
    "role" : "affectedProduct",
    "entity" : {
      "@type" : "EntityRef",
      "id" : "922ebf01-e930-47a0-842e-059d1f188a15",
      "@referredType" : "Product"
    }
  }, {
    "@type" : "RelatedEntityRefOrValue",
    "role" : "optionalServices",
    "entity" : {
      "@type" : "ProductOffering",
      "name" : "Ganzheitliche Entstörung"
    }
  }, {
    "@type" : "RelatedEntityRefOrValue",
    "role" : "diagnosis",
    "entity" : {
      "@type" : "EntityRef",
      "id" : "873ebg01-a930-47a0-842e-059d1f188b23",
      "@referredType" : "ProductTest"
    }
  } ],
  "relatedParty" : [ {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "orderManagementBuyerContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221456789"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917754545454"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "j.kirk@example.net"
      } ],
      "familyName" : "Kirk",
      "salutation" : "Herr",
      "givenName" : "James T.",
      "title" : "Captain"
    }
  }, {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "installationContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221456790"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917754545455"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "m.scott@example.net"
      } ],
      "familyName" : "Scott",
      "salutation" : "Herr",
      "givenName" : "Montgomery",
      "title" : "Lt. Cmdr."
    }
  } ],
  "accessLineId" : "DEU.DTAG.FTYLIQ7PFT",
  "agreement" : [ {
    "@type" : "Agreement",
    "name" : "buyerServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500011"
    } ],
    "businessId" : "500012",
    "agreementType" : "buyerServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "ordererServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500014"
    } ],
    "businessId" : "500013",
    "agreementType" : "ordererServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "singleContract",
    "businessId" : "555001",
    "agreementType" : "singleContract"
  } ],
  "endUserContactAllowed" : true,
  "expressFaultResolution" : "oneTime",
  "faultQuestionnaire" : [ {
    "questionId" : "DSL01",
    "answerId" : "DSL01-03"
  }, {
    "questionId" : "DSL04",
    "answerId" : "DSL04-02"
  } ],
  "interimMessagesRequested" : true,
  "networkTerminationLocation" : "Flur",
  "requestedTimeSlot" : {
    "@type" : "TimeSlot",
    "validFor" : {
      "startDateTime" : "2024-03-08T12:00:00+01:00",
      "endDateTime" : "2024-03-08T16:00:00+01:00"
    }
  },
  "categoryId" : "SABB"
}

Task resource models

Lifecycle

Task resource lifecycle

Task lifecycle states

Cancel Trouble Ticket

cancel-trouble-ticket-resource 
{
  "$schema" : "../schema/fit-tmf621.schema.json",
  "@type" : "CancelTroubleTicket_FVO",
  "requestPostedDate" : "2022-05-11T10:30:00+02:00",
  "entity" : {
    "@type" : "TroubleTicketRef",
    "id" : "ac925eed-111b-4558-82e3-c48153c8c95c",
    "href" : "https://api.example.org/tmf-api/troubleTicketManagement/v5/troubleTicket/ac925eed-111b-4558-82e3-c48153c8c95c"
  }
}

Inflight Change Trouble Ticket

inflight-change-trouble-ticket-resource
Reschedule example
{
  "$schema" : "../schema/fit-tmf621.schema.json",
  "@type" : "InflightChangeTroubleTicket_FVO",
  "requestPostedDate" : "2024-02-09T17:30:00+01:00",
  "entity" : {
    "@type" : "TroubleTicketRef",
    "id" : "ac925eed-111b-4558-82e3-c48153c8c95c",
    "href" : "https://api.example.org/tmf-api/troubleTicketManagement/v5/troubleTicket/ac925eed-111b-4558-82e3-c48153c8c95c"
  },
  "category" : [ "reschedule" ],
  "requestedResolutionDate" : "2024-03-09T00:00:00+01:00",
  "requestedTimeSlot" : {
    "@type" : "TimeSlot",
    "validFor" : {
      "startDateTime" : "2024-03-09T12:00:00+01:00",
      "endDateTime" : "2024-03-09T16:00:00+01:00"
    }
  }
}
Add-information example
{
  "$schema" : "../schema/fit-tmf621.schema.json",
  "@type" : "InflightChangeTroubleTicket_FVO",
  "requestPostedDate" : "2024-10-24T10:32:00+02:00",
  "entity" : {
    "@type" : "TroubleTicketRef",
    "id" : "ac925eed-111b-4558-82e3-c48153c8c95c",
    "href" : "https://api.example.org/tmf-api/troubleTicketManagement/v5/troubleTicket/ac925eed-111b-4558-82e3-c48153c8c95c"
  },
  "buyerMessage" : {
    "code" : "7040",
    "text" : "Ergänzende Information zum Auftrag.",
    "additionalInformation" : "Note from Buyer to Seller"
  },
  "category" : [ "add" ]
}

Notifications

The API reference documents create, status-change, attribute-value-change, information-required, jeopardy-alert, and milestone events for Trouble Ticket resources, as well as state-change events for the task resources.

Open the complete API reference

Authentication

This API is secured using OAuth 2.0. For machine-to-machine communication, it uses the Client Credentials flow. The authorization server issues an access token that the client uses to access protected API resources without sharing its credentials with the resource server.

oauthclientcredentialflow-puml

See Security schemes for the API-specific OAuth 2.0 configuration and FIT API authentication for the common authentication requirements.

Validation using the conformance profile

The conformance profile defines which attributes, structures, and constraints are applicable to the FIT implementation of TMF621. It can be used to validate Trouble Ticket payloads for compliance with the FIT specification.

The following artifacts are provided for validation and reference:

  • JSON Schema – machine-readable schema for automated validation of JSON payloads.

  • Excel – human-readable overview of the supported attributes, structures, and conformance requirements.

Supporting files