Open APIs

I'm confused by the Notifications defined in the Notification Resource Models section which seems to appear in all API documents. They define a JSON structure but are not an API call themselves. With regards to TMF621 and TMF642 I don't understand how they fit in to the API Operations. They seem relevant to the API Notifications but then why are they called out into their own section. I'm sure I'm missing something fundamental but can't figure out what it is.

We want to use API Operations 'Create trouble ticket (POST /troubleticket)' and 'Patch trouble ticket (PATCH /troubleticket/{id})' to create and then update an incident in a CRM system. Those two API calls seem clear to me but I've been told to use the Notifications TroubleTicketCreateEvent:

{ 
   "eventId":"00001",
   "eventTime":"2015-11-16T16:42:25-04:00",
   "eventType":"TroubleTicketCreateEvent",
   "event": {
      "troubleTicket" : {-- SEE TroubleTicket RESOURCE SAMPLE --}
      }
}

Is this a wrapper to use with API Operations troubleTicket changing this:

POST /tmf-api/troubleTicket/v4/troubleTicket Content-Type: application/json
{
   "description": "I do not accept the last VOD charge, since the movie was constantly interrupted, I had to quick watching the movie in the middle ",
   "expectedResolutionDate": "2019-06-10T07:34:45.968Z",
   "lastUpdate": "2019-05-31T07:34:45.968Z",
   "name": "Compliant over last bill",
   "requestedResolutionDate": "2019-05-31T07:34:45.968Z",
   "severity": "Urgent",
   "status": "InProgress",
   "ticketType": "Bill Dispute",
   ...

}

into:

POST /tmf-api/troubleTicket/v4/troubleTicket Content-Type: application/json
{
   "eventId":"00001",
   "eventTime":"2015-11-16T16:42:25-04:00",
   "eventType":"TroubleTicketCreateEvent",
   "event": {
      "troubleTicket" : {
         "description": "I do not accept the last VOD charge, since the movie was constantly interrupted, I had to quick watching the movie in the middle ",
         "expectedResolutionDate": "2019-06-10T07:34:45.968Z",
         "lastUpdate": "2019-05-31T07:34:45.968Z",
         "name": "Compliant over last bill",
         "requestedResolutionDate": "2019-05-31T07:34:45.968Z",
         "severity": "Urgent",
         "status": "InProgress",
         "ticketType": "Bill Dispute",
         ...
         }
    }
}

Pretty sure I am misunderstanding your question, but here goes anyway...

The notifications are to notify other systems, e.g. ODA-C or API consumers, that an event has occured such as TroubleTicketCreateEvent or ServiceOrderStateChangeEvent.  These notifications may use the TMF688 Event Management API (REST) or can use the EDA (Event Driven Architecture) utilising the Async APIs TMF620E, TMF640E and hooking directly into an event bus/manager, e.g. kafka.

The payload of the event typically contains the affected entity, e.g. the TroubleTicket or ServiceOrder.

Hope this helps.

------------------------------
Dan d'Albuquerque
Individual
------------------------------

Hi Michael,

The notification payloads - like TroubleTicketCreateEvent - are meant to be delivered over a Hub subscription mechanism. This is a webhook 'subscription' service that the TMF API's mandate to deliver to any interested party, changes in the system. Subscription is achieved by providing an HTTPS endpoint where the events should be delivered.

For example:

Using your 'Create trouble ticket (POST /troubleticket)' API call should result in the Trouble Ticket system delivering a TroubleTicketCreateEvent payload to all the 'subscribed' parties - this can include the calling system of course, but can also be others.

There is no other way to 'use' the event mechanism.

Hi Pieter, 

Although you are correct in general with respect to how notifications work, I would question though the fact that TMF API's "mandate" support of notifications. As per TMF 621 v5.0.0 conformance profile, quote "There are no mandatory notifications for this API.". 

Hi Denis,

Apologies if I wasn't clear. 

In general - this is the mechanism that is used. Certification requirements may or may not mandate notifications on specific APis.