Trouble Ticket and Incident Notification — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Cantata SDK, Kylie release. LSO Cantata is the Interface Reference Point between a Customer (typically an enterprise) and a Service Provider, covering the business/product layer. 7 path(s), 7 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.
openapi: 3.0.1
info:
title: Trouble Ticket and Incident Notification
description: |
**This file forms part of Mplify 124.1**
This API implements Business Requirements described in MEF 113
It allows the Buyer to create, retrieve, and update Trouble Tickets as well
as receive notifications about Incidents' and Trouble Tickets' updates.
This allows managing issues and situations that are not part of normal
operations of the Product provided by the Seller.
List of supported use cases:
- Send Event Notification
Copyright 2025 Mplify Alliance and its contributors.
This file includes content based on the TM Forum Trouble Ticket API (TMF621
v4.0.0) available at https://github.com/tmforum-apis/TMF621_TroubleTicket,
which is licensed by the TM Forum under the Apache License version 2.0.
Such content has been modified by the Mplify Alliance and its contributors.
version: 5.0.0
servers:
- url: 'https://{serverBase}/mefApi/cantata/troubleTicketNotification/v5/'
variables:
serverBase:
description: The base of Buyer's URL.
default: mplify.net
tags:
- name: Notification listeners
description: |
The Buyer's endpoint to send particular event types notifications to.
paths:
/listener/troubleTicketAttributeValueChangeEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity TroubleTicketAttributeValueChangeEvent
description: >-
Client listener for receiving the notification
TroubleTicketAttributeValueChangeEvent
operationId: listenToTroubleTicketAttributeValueChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/TroubleTicketAttributeValueChangeEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/troubleTicketStatusChangeEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity TroubleTicketStatusChangeEvent
description: >-
Client listener for receiving the notification
TroubleTicketStatusChangeEvent
operationId: listenToTroubleTicketStatusChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/TroubleTicketStatusChangeEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/troubleTicketResolvedEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity TroubleTicketResolvedEvent
description: >-
Client listener for receiving the notification
TroubleTicketResolvedEvent
operationId: listenToTroubleTicketResolvedEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/TroubleTicketResolvedEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/troubleTicketInformationRequiredEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity TroubleTicketInformationRequiredEvent
description: >-
Client listener for receiving the notification
TroubleTicketInformationRequiredEvent
operationId: listenToTroubleTicketInformationRequiredEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/TroubleTicketInformationRequiredEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/incidentCreateEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity Incident Create Event
description:
Client listener for receiving the notification Incident Create Event
operationId: listenToIncidentCreateEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/IncidentCreateEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/incidentAttributeValueChangeEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity Incident Attribute Value Change Event
description: >-
Client listener for receiving the notification Incident Attribute Value
Change Event
operationId: listenToIncidentAttributeValueChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/IncidentAttributeValueChangeEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/listener/incidentStatusChangeEvent:
post:
tags:
- Notification listeners
summary: Client listener for entity Incident Status Change Event
description: >-
Client listener for receiving the notification Incident Status Change
Event
operationId: listenToIncidentStatusChangeEvent
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Buyer. MUST be specified in the request when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request when the responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The event data
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/IncidentStatusChangeEvent'
required: true
responses:
'204':
description:
'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
Error:
description: >
Standard Class used to describe API response error
Not intended to be use directly. The `code` in the HTTP header is used
as a discriminator for the type of error returned in runtime.
type: object
properties:
reason:
description: >-
Text that explains the reason for error. This can be shown to a
client user.
type: string
maxLength: 255
message:
description: >-
Text that provide mode details and corrective actions related to the
error. This can be shown to a client user.
type: string
referenceError:
description: url pointing to documentation describing the error
type: string
format: uri
required:
- reason
Error400:
description:
'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required
query-string parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
$ref: '#/components/schemas/Error400Code'
required:
- code
Error400Code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required query-string
parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
type: string
enum:
- missingQueryParameter
- missingQueryValue
- invalidQuery
- invalidBody
Error401:
description:
'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)'
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
description: >-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or
expired
$ref: '#/components/schemas/Error401Code'
required:
- code
Error401Code:
description: |-
One of the following error codes:
- missingCredentials: No credentials provided.
- invalidCredentials: Provided credentials are invalid or expired
type: string
enum:
- missingCredentials
- invalidCredentials
Error403:
description:
'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)'
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
description: |-
This code indicates that the server understood
the request but refuses to authorize it because
of one of the following error codes:
- accessDenied: Access denied
- forbiddenRequester: Forbidden requester
- tooManyUsers: Too many users
$ref: '#/components/schemas/Error403Code'
required:
- code
Error403Code:
description: |-
This code indicates that the server understood
the request but refuses to authorize it because
of one of the following error codes:
- accessDenied: Access denied
- forbiddenRequester: Forbidden requester
- tooManyUsers: Too many users
type: string
enum:
- accessDenied
- forbiddenRequester
- tooManyUsers
Error500:
description: >-
Internal Server Error.
(https://tools.ietf.org/html/rfc7231#section-6.6.1)
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
description: >-
The following error code:
- internalError: Internal server error - the server encountered
an unexpected condition that prevented it from fulfilling the
request.
type: string
enum:
- internalError
required:
- code
Event:
description: >-
Event class is used to describe information structure used for
notification.
type: object
properties:
eventId:
description: Id of the event
type: string
eventTime:
description: Date-time when the event occurred
type: string
format: date-time
eventType:
description: The type of the notification.
type: string
event:
description: The event linked to the involved resource object
type: object
required:
- event
- eventId
- eventTime
- eventType
IncidentAttributeValueChangeEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- incidentAttributeValueChangeEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/IncidentEventPayload'
required:
- event
- eventType
IncidentCreateEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- incidentCreateEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/IncidentEventPayload'
required:
- event
- eventType
IncidentEventPayload:
description: The identifier of the Incident being subject of this event.
type: object
properties:
id:
description: ID of the Incident
type: string
href:
description: Hyperlink to access the Incident
type: string
required:
- id
IncidentStatusChangeEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- incidentStatusChangeEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/IncidentStatusChangeEventPayload'
required:
- event
- eventType
IncidentStatusChangeEventPayload:
description:
The identifier of the Trouble Ticket being subject of this event.
type: object
properties:
id:
description: ID of the Trouble Ticket
type: string
href:
description: Hyperlink to access the Trouble Ticket
type: string
status:
description: The current status of the Trouble Ticket
$ref: '#/components/schemas/IncidentStatusType'
required:
- id
- status
IncidentStatusType:
description: |
Possible values for the status of the Incident
| status | MEF 113 name | Description |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `closed` | CLOSED | The Situation described in the Incident was closed by has been resolved and normal operation has been restored on the Seller.Seller's network. This is a terminal state. |
| `created` | CREATED | A new Incident has been created and allocated a unique `id`. |
| `inProgress` | IN_PROGRESS | The Incident is in the process of being handled and investigated for resolution by the Seller.
type: string
enum:
- closed
- created
- inProgress
TroubleTicketAttributeValueChangeEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- troubleTicketAttributeValueChangeEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/TroubleTicketEventPayload'
required:
- event
- eventType
TroubleTicketEventPayload:
description:
The identifier of the Trouble Ticket being subject of this event.
type: object
properties:
id:
description: ID of the Trouble Ticket
type: string
href:
description: Hyperlink to access the Trouble Ticket
type: string
required:
- id
TroubleTicketInformationRequiredEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- troubleTicketInformationRequiredEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/TroubleTicketEventPayload'
required:
- event
- eventType
TroubleTicketResolvedEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- troubleTicketResolvedEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/TroubleTicketEventPayload'
required:
- event
- eventType
TroubleTicketStatusChangeEvent:
allOf:
- $ref: '#/components/schemas/Event'
- type: object
properties:
eventType:
description: Indicates the type of the event.
type: string
enum:
- troubleTicketStatusChangeEvent
event:
description: >
A reference to the object that is the source of the
notification.
$ref: '#/components/schemas/TroubleTicketStatusChangeEventPayload'
required:
- event
- eventType
TroubleTicketStatusChangeEventPayload:
description:
The identifier of the Trouble Ticket being subject of this event.
type: object
properties:
id:
description: ID of the Trouble Ticket
type: string
href:
description: Hyperlink to access the Trouble Ticket
type: string
status:
description: The current status of the Trouble Ticket
$ref: '#/components/schemas/TroubleTicketStatusType'
required:
- id
- status
TroubleTicketStatusType:
description: |
Possible values for the status of the Trouble Ticket
| status | MEF 113 name | Description |
| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acknowledged` | ACKNOWLEDGED | A request to create a Ticket was received and accepted by the Seller. The Ticket create request has been validated and a Ticket has been created by the Seller and allocated a unique `id`. |
| `assessingCancellation` | ASSESSING_CANCELLATION | A request has been made by the Buyer to cancel the Ticket and is being assessed by the Seller to determine whether to just close the Ticket, or continue to resolve the Issue to prevent similar Create Ticket requests from other Buyers. If the Seller chooses to resolve the Issue, the Seller might create an Incident or an internal Ticket for the Issue, but that is outside the scope of this document. After the Seller has completed the assessment, the Seller updates the Ticket State to `cancelled`. |
| `cancelled` | CANCELLED | The Ticket has been successfully cancelled by the Buy-er. The Buyer will receive no further Event Notifications for the Ticket. This is a terminal state. |
| `closed` | CLOSED | The Buyer has confirmed that the Issue they reported is no longer observed, or the pre-defined time frame (agreed upon between Buyer and Seller) for confirming that the Issue has been resolved has passed without a response by the Buyer. This is a terminal state. |
| `inProgress` | IN_PROGRESS | The Ticket is in the process of being handled and investigated for resolution by the Seller.
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-trouble-ticket-notification-openapi.yml