Open APIs

Expand all | Collapse all

TMF 688 Event API and Event resource in other APIs

  • 1.  TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Apr 07, 2021 19:34
    Hi

    We are currently exploring the use of TMF 688 event API to notify the consumer of the APIs as regards significant events associated with the resource (e.g. ResourceCreate, ResourceDelete, ResourceStateChange etc)

    An initial observation is that the 'Event' resource model in TMF 688 is not aligned to the 'Event' model in the other TMF APIs such as TMF 622 (ProductOrder) and TMF 641 (Service Order).

    The 'Event' resource model in TMF688 does not have the 'fieldpath' attribute for example.
    Which of the two resource models would be an accurate representation of the base type 'Event'

    I was also interested in understanding
    - the 'analyticcharacteristic' attribute (an array of name/value characteristics) defined within the 'Event' resource model. What is the intended use of this attribute.
    - How can the 'Event' resource model in 688 be used to notify the consumer of the API or any other interested subscriber changes to resources. e.g.
        - Changes to the value of one or more attribute within a resource
        - Addition of one or more new attribute or one or more sub-resource within the resource
        - Removal of one or more new attribute or one or more sub-resource with the resource
    - the intended use of the attribute correlationID, domain

    Thanks in advance for any guidance you can provide.

    KR
    Lance



    ------------------------------
    Lancy Mendonca
    ------------------------------


  • 2.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Apr 28, 2021 03:46
    Good morning to the community,

    We are also interested in this topic and have similar questions.

    Best regards,

    Roland

    ------------------------------
    Roland Leners
    SATEC GROUP
    ------------------------------



  • 3.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Apr 29, 2021 11:18
    Hi,

    We are also looking to use the TMF688 event model for an implementation that also includes TMF641 service ordering/TMF622 Product Ordering.

    Our initial interpretation of the 688 model was that it was used for internal events to an application implementation and the TMF641/TMF622 provided external updates to clients/subscribers.

    However on looking at this again is the intention that a 641/622 event lives inside a 688 event? and if that is the case does the full 641 model live inside the 688 event property?

    many thanks

    Dave

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 4.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 17, 2021 05:29
    Just giving this a bump in the hope that someone might be able to help on this?

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 5.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 17, 2021 11:52
    I do not understand your question, but in general all notification (events) can be received by the Event688  API (listener) for further processing.
    Question: Does the fieldpath element belong to the notification event?
    and the @type is the class discriminator for the event class.
    If @type=ResourceCreateEvent then the event class is the ResourceCreateEvent with eventType=ResourceCreateNotification as notification type. This means that the payload of the event has a resource instance included , which was created.
    In this example the ResourceInventory API sends a ResourceCreateNotification to the EventAPI (HUB) via POST (Callback) operation.

    KR Thomas
    ​​​

    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------



  • 6.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 17, 2021 16:10
    Edited by David Whitfield Jun 17, 2021 16:13
    Hi @Thomas Braun. I mean to say that the TMF688 spec says that everything which is published to you​r event streaming platform is wrapped in the TMF688 event header.

    I am therefore presuming that if you wish to stream TMF641 events onto your event streaming platform for clients to subscribe to then they are written as a TMF688 and the event field of that TMF688 contains the entire TMF641 payload.

    To be explicit (please see below)....

    [ 
    { 
    "@type": "ServiceOrderCreateEvent", 
    "@schemaLocation": "http://xx/Event.schema.json", 
    "@baseType": "event", 
    "id": "3e34689f-d4ae-44b7-bc97-d64eeaf2ba76", 
    "href": "http://www.tmforum.org/tmf-api/eventStreaming/Event/3e34689f-d4ae-44b7-bc97-d64eeaf2ba76", 
    "eventId": "256c42f0-7cae-4cfe-8b96-f5773796f8ff", 
    "eventTime": "2016-07-02T14:20:54", 
    "eventType": "ServiceOrderCreateNotification", 
    "correlationId": "238764827364827t367", 
    "domain": "domain-x", 
    "title": "Mail service not responding", 
    "description": "The mail service is no longer responding and sending mails", "timeOccurred": "2016-07-02T14:20:54", 
    "timeReceived": "2016-07-02T14:21:08", 
    "priority": "Normal", 
    "source": 
    { 
    "id": "12345", 
    "href": ".../relatedEntity/12345" 
    }, 
    "reportingSystem": 
    { 
    "id": "34534", 
    "href": ".../reportingEntity/12345", 
    "name": "name" 
    }, 
    "relatedParty": 
    [ 
    { 
    "id": "12312", 
    "href": "http://.../party/12345", 
    "role": "Owner" 
    } 
    ], 
    "event": 
    { 
    "serviceOrder": 
    {
      {-- SEE ServiceOrder RESOURCE SAMPLE --}
    } 
    } 
    ]
    ​

    However should that client look inside the "event" field of the TMF688 it would not find a full TMF641 event as is described by that document below it would only find the "serviceOrder" part.

    { 
    "eventId":"00001", 
    "eventTime":"2015-11-16T16:42:25-04:00", 
    "eventType":"ServiceOrderCreateEvent", 
    "event": 
    { 
    "serviceOrder" : {-- SEE ServiceOrder RESOURCE SAMPLE --} 
    } 
    }


    ------------------------------

    David Whitfield
    TalkTalk Group
    ------------------------------



  • 7.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 18, 2021 05:54
    Hi David,

    in your example the @type=ServiceOrderCreateEvent describes the complete class of the event (notification).
    So by that class description the event (payload) element contains the ServiceOrder (instance/resource) which was created.

    The client can look into that part, if he knows the class of the ServiceOrder, which is described by the event.serviceOrder.@type element. (@type=ServiceOrder)

    Below I copied an comlete ServiceOrder example as event payload.

    and you can have access by EventAPI GET operation:
    GET /tmf-api/event/v4/event?eventType=ServiceOrderCreateNotification& fileds=eventId,eventTime,eventType,event
    Accept: application/json

    ​Response 200
    { 
    "eventId":"00001", 
    "eventTime":"2015-11-16T16:42:25-04:00", 
    "eventType":"ServiceOrderCreateEvent", 
    "event": 
    { 
      "serviceOrder": {
    
        "id": "43",
        "href": "http://serverlocation:port/serviceOrdering/v4/serviceOrder/43",
        "externalId": "BSS747",
        "priority": "1",
        "description": "Service order description",
        "category": "TMF resource illustration",
        "state": "acknowledged",
        "orderDate": "2018-01-12T09:37:40.508Z",
        "requestedStartDate": "2018-01-15T09:37:40.508Z",
        "requestedCompletionDate": "2018-01-15T09:37:40.508Z",
        "expectedCompletionDate": "2018-01-15T09:37:40.508Z",
        "startDate": "2018-01-12T09:37:40.508Z",
        "@type": "ServiceOrder",
        "note": [
            {
                "date": "2018-01-15T09:37:40.508Z",
                "id": "1",
                "author": "Harvey Poupon",
                "text": "Some text"
            }
        ],
        "relatedParty": [
            {
                "id": "456",
                "href": "http://serverlocation:port/partyManagement/v4/party/456",
                "role": "requester",
                "name": "Jean Pontus",
                "@referredType": "Individual"
            }
        ],
        "serviceOrderItem": [
            {
                "id": "1",
                "action": "add",
                "state": "acknowledged",
                "service": {
                    "@type": "Service",
                    "state": "active",
                    "serviceType": "CFS",
                    "serviceCharacteristic": [
                        {
                            "id": "452-gh6",
                            "name": "vCPE",
                            "valueType": "object",
                            "value": {
                                "@type": "JSONSpecification",
                                "@schemaLocation": "http://my.schemas/vCPE.schema.json",
                                "vCPE_IP": "193.218.236.21",
                                "MaxTxRate": 300,
                                "TransmitPower": "11 dBm",
                                "maxTream": "OFF"
                            }
                        }
                    ],
                    "serviceSpecification": {
                        "@type": "ONAPServiceSpecification",
                        "@baseType": "ServiceSpecificationRef",
                        "@schemaLocation": "http://my.schema/ONAPServiceSpecification.json",
                        "id": "12",
                        "href": "http://.../serviceSpecification/12",
                        "name": "vCPE",
                        "version": "1",
                        "invariantUUID": "456-852-357",
                        "toscaModelURL": "http//...",
                        "targetServiceSchema": {
                            "@type": "onapJsonScheam",
                            "@schemaLocation": "http://nbi/api/v4/serviceSpecification/456-852-357/specificationInputSchema"
                        }
                    }
                },
                "@type": "ServiceOrderItem"
            },
            {
                "id": "2",
                "action": "modify",
                "state": "acknowledged",
                "service": {
                    "id": "456",
                    "@type": "Service",
                    "href": "http://serverlocation:port/serviceInventoryManagement/v4/service/456",
                    "state": "active",
                    "serviceType": "CFS",
                    "serviceCharacteristic": [
                        {
                            "id": "452-gh6",
                            "name": "InputPort",
                            "valueType": "string",
                            "value": "456/7"
                        }
                    ],
                    "supportingResource": [
                        {
                            "id": "3456_DFG5-H690",
                            "href": "http://serverlocation:port/resourceInventoryManagement/v4/resource/3456_DFG5-H690",
                            "@referredType": "CloudResource"
                        }
                    ]
                },
                "@type": "ServiceOrderItem"
            },
            {
                "id": "3",
                "action": "add",
                "state": "acknowledged",
                "service": {
                    "state": "active",
                    "serviceType": "CFS",
                    "@type": "Service",
                    "serviceRelationship": [
                        {
                            "relationshipType": "reliesOn",
                            "service": {
                                "href": "https://serverlocation:port/serviceManagement/v4/service/45",
                                "id": "45"
                            }
                        }
                    ],
                    "serviceSpecification": {
                        "id": "48",
                        "href": "http//serverlocation:port/serviceCatalogManagement/v4/serviceSpecification/48",
                        "name": "genericDataService48",
                        "version": "2"
                    },
                    "feature": [
                        {
                            "id": "Feat1",
                            "isEnabled": true,
                            "name": "DataDownload",
                            "@type": "Feature",
                            "featureCharacteristic": [
                                {
                                    "name": "VolumeCapped",
                                    "value": true,
                                    "id": "444",
                                    "valueType": "boolean"
                                }
                            ]
                        }
                    ]
                },
                "@type": "ServiceOrderItem"
            },
            {
                "id": "4",
                "action": "modify",
                "state": "acknowledged",
                "service": {
                    "id": "12",
                    "href": "http://serverlocation:port/serviceInventoryManagement/v4/service/12",
                    "state": "inactive"
                },
                "@type": "ServiceOrderItem"
            }
        ]
    }
    
    }
    }​


    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------



  • 8.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 18, 2021 10:02
    Hey @Thomas Braun, thanks again for your reply.

    Whilst i understand that your example does follow the pattern that is defined by the TMF641 document for notifications it doesnt seem to align with the TMF688 example which suggests that the header contains a good number fields (i.e. the header contains @type, @baseType,source,related party etc

    Are you suggesting that if you want to write a sales order event to the streaming system you use the example given in the TM641 document then add in the extra headers suggested by the TMF688 document?

    If this is the case and say a field like the related party (i.e. role = "creator") of the original service order was "partnerXZY"​​ and the related party (i.e. role = "creator") of the event was "order management system" how would you represent this?

    It was for this reason i had drawn the assumption that the whole TMF641 event along with its headers had to sit inside the event field of the TMF688.

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 9.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 23, 2021 04:38
    hey @Thomas Braun, any thoughts on this at all? Appreciate your help with working through this.

    Maybe a little more context on what we're doing to help you understand. We are looking to use an orchestration within our microservices architecture (as opposed to choreography) so we intend for there to be events between microservices some which are requests for action (an instruction) and some dictate something that has happened (notification). Our plan is to use the TMF688 schema to wrap these events. This would be our extensions to the base event for that use case.

    As we are implementing TMF641 we would also want to write these kinds of events (notifications) to the event streaming system.

    Therefore at the moment I am struggling with (as @Koen Peeters​ mentioned) the difference in the header structure in 688 vs 641.

    I believe that if we were to write 'internal microservice' events (based on the TMF688 spec) and TMF641 events to the event streaming system we would be contradicting the TMF688 documentation. As i interpret it, it states everything on that event streaming system confirms to 688. From what i can see in the examples 641 lacks properties that 688 defines like: - description, correlationId, domain, title etc

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 10.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 17, 2021 13:29
    Good evening community,

    I agree that the current version of the TMF688 event API is written as a management API for a generic streaming platform.
    It does not explain how this applies to the events described in the other TMF API.

    In a typical ODA component one expects to use an API gateway to expose all the API supported by the component.
    In such a component one would expect to have a single hub that allows other components to subscribe to all the Events produced by that component.
    I believe these Events should  be formatted using the Event header used by all specifications. The Event described in TMF688 doesn't seem to comply with that model and that is a bit disappointing.

    On the other hand does the TMF688 fill some gaps that are not clear from any other specification.
    It introduces the concept of creating a Topic, that automatically has two endpoints:
    • /topic/{id}/event: for publishing the events
    • /topic/{id}/hub: for subscribing to the events
    This pattern is definitely reusable for any implementation.

    We are currently preparing an commercial implementation based on kafka.
    Feel free to contact me if you are interested in beta-testing.


    ------------------------------
    Koen Peeters
    Ciminko Luxembourg
    ------------------------------



  • 11.  RE: TMF 688 Event API and Event resource in other APIs

    TM Forum Member
    Posted Jun 18, 2021 07:07
    Hi ,

    yes the TMF688 Event API is a generic API for eventing and streamaing platforms; that means that all Event API resource (Event,Topic,Hub) should be implemented by that streaming platform. (e.g. KAFKA)
    The Topic resource is defined as container resource for Event resource .
    and can be used to set-up a Topic/event graph for domain specific Event processing.
    The Hub resource is defined  for holding subcription for other clients, which can be notified by s.c. CallBack Post operation of the Event API (see.API Notifications chapter) to other clients/Listeners

    KR Thomas Braun



    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------