FIT Trouble Ticket API

AG-FIT 621

Release Value

Version

1.0.0

Date

2026-03-30

State

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.

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."
  },
  "category" : [ "add" ],
  "note" : [ {
    "@type" : "TroubleTicketRemark",
    "text" : "Note from Buyer to Seller"
  } ]
}

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

Validation using the conformance profile

Download the FIT TMF621 JSON Schema

Supporting files