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.
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
Cancel Trouble Ticket
{
"$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
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.