Open APIs

 View Only
Expand all | Collapse all

TMF641 creating milestone events with meta data

  • 1.  TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 07, 2022 12:07
    Hi All,

    We have a requirement around supplying metadata for a milestone when creating these types of event notification. This meta data takes the form of a collection of objects that are associated to a milestone. I was trying to think about a way of representing these within the existing data model and not extending the TMF API.

    Our order management system would recieve inbound updates from fibre access providers detailing the status of the fullfilment in their systems. At this point we have a need to publish this information out to allow subscribers (namely business systems) to understand the latest update.


    Whilst the service order milestone seems appropriate (and is the approach we were intending to take), it would appear an extension would be required unless anyone has any good suggestions on how this might be achieved?

    The data would look something like this if we extended milestone  but not sure how compliant this approach is or if others have faced this challenge?

    {
        "id" : "xyz123",
        "@type" : "ServiceOrder",
        //other service order attributes
        "milestone" : [
            {
                "id" : "dffokfl38734897598",
                "name" : "SomeTypeOfMilestoneUpdate",
                "message" : "Something has happened to the order or 1 of the line items which will be interesting to some subscribers",
                "metadata" : [
                    {   
                        "code" : "abc123",
                        "description" : "useful description",
                        "reason" : "explain why",
                        "category" : "categoryA"
                    },                
                    {   
                        "code" : "xyz456",
                        "description" : "useful description",
                        "reason" : "explain why",
                        "category" : "categoryB"
                    }
                ]        
            }
        ]
    }

    thanks in advance for any thoughts/guidance



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


  • 2.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 11, 2022 12:31
    In case anyone is able to help on this with some guidance i have also picked up a new ask around representing such information against a specific state changed event also. Whilst i could see a potential option of extending milestone (though not sure about how compliant this is) with having the state of an order/order line as just a string im not sure how this could be done.

    many thanks

    Dave

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



  • 3.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 12, 2022 07:39
    Hello David
    For me, you should have a @type attribute in the Milestone class to be compliant with TMF extension model.
    You have created a specialization of the Milestone, and it needs to be present in the payload.

    Something like this (providing example of using  your notification and standard one):
    {
        "id" : "xyz123",
        "@type" : "ServiceOrder",
        //other service order attributes
        "milestone" : [
            {
                "id" : "dffokfl38734897598",
                "name" : "SomeTypeOfMilestoneUpdate",
                "message" : "here a extended milestone",
                "@type" : "ExtendedMilestone",
                "metadata" : [
                    {   
                        "code" : "abc123",
                        "description" : "useful description",
                        "reason" : "explain why",
                        "category" : "categoryA"
                    },                
                    {   
                        "code" : "xyz456",
                        "description" : "useful description",
                        "reason" : "explain why",
                        "category" : "categoryB"
                    }
                ]        
            },
            {
                "id" : "45",
                "name" : "SomeTypeOfMilestoneUpdate",
                "message" : "here a standard milestone",
                "@type" : "Milestone",
           
            }
        ]
    }​


    This @type is used a discriminator.

    After regarding use of a specific Metadata node or directly adding code/description/reason/category I haven't specific thoughts.

    Hope it helps

    Ludovic


    ​​

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 4.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 12, 2022 09:23
    Hey @Ludovic Robert,

    thanks for coming back to me on this, I have whilst pondering on this over the last couple of days come to a similar conclusion over '@type'. Your similar view ​​is very helpful.

    I think on the meta data node its purely due to having 0..* 'codes' per milestone (clearly the base milestone can be used if there is no meta data). The other option i had thought of in the interim was to add a 'milestoneCharacterisitcs' node to this type of milestone and therefore this would provide future extensibility should any other data be needed.

    Whilst this does give a reasonable answer for the milestones i dont see an option to link a similar set of data to a state update given that the state note in the order line and order is just a string and not a complex type, would you have any thoughts on that?

    many thanks

    Dave

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



  • 5.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 12, 2022 09:48
    Just an idea, David, but perhaps extending the model with a StatusChange class. Look what we have in TMF621 to track trouble ticket state change.
    You keep as it the state in the order and add statusChange attribute targeting StatusChange class. Then you can extend  this one to your purpose.


    BTW I will not recommend using Characteristic without CharacteristicSpecification somewhere. Look for service, we have serviceCharacteristic in 641/638 which are defined as ServiceCharacteristicSpecification in 633.

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 6.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 12, 2022 11:51
    thanks for the futher point @Ludovic Robert we will take a look at the 621​ spec!

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



  • 7.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 12, 2022 14:59
    Just to expand on Ludovic's point on characteristic - the quickest way to create an open-ended, weak contract is to add unbounded characteristics to a model. These become a dumping ground for arbitrary name-value pairs, with private (and sometimes undocumented) understanding between provider and consumer.
    The only legitimate circumstance to use characteristics (and not strongly-typed model attributes) is when there is a sound definition of the characteristic, i.e. a characteristic specification; this allows consumer and provider to validate the existence (name) and value rules against the specification.
    Catalog APIs are the obvious example, but the pattern appears commonly across the API model.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 8.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 20, 2022 17:14
    Hey @Ludovic Robert,

    One thing i struggle to to wrap my head around with the TMF API's is how a client that consumes my API's Swagger (which seems is only meant to describe the base milestone from what i can see)​ comprehends the structure of the extendend milestone. This same confusion applys to any extension of the TMF base objects.

    I think that the answer is they only know at the point of receiving a response and have to identify that the schema does not live in the existing prebuild client classes (Generate from the swagger) but there is a link to the schema included in the object which needs to be used for 'just in time' object comprehension. I'm just not sure how in reality this works and how the client does this?

    Is there any chance any one has an example of what the server sends and how the client interprets this?

    So far we have considered to include both schemas (Milestone and ExtendedMilestone) in the swagger definition and then use oneOf (below) but i'm well aware this doesnt offer the server the licence to deliver a new milestone derived type without a new API version.

    Note - we use YAML to describe our API's not JSONSchema.

    type: array
    items:
      oneOf:
        - $ref: '#/components/schemas/Milestone'
        - $ref: '#/components/schemas/ExtendedMilestone'​


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



  • 9.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Jan 21, 2022 05:55
    Hello David

    This is a very good question and to be honest I haven't not a straight answer. 
    How an API customer can know the specialisation (if any) provided by a server?
    For me, we can take a look on the 'home' resource that you can provide with your API and this home resource should be a good way for your potential API customer to 'understand' your API (Home is described in the design guideline part 3).

    We leveraged this in a catalyst where we want to handle in one endpoint both TMF flavor and MEF flavor of the quote API (MEF using a TMF specialization) -  home resource provided following information:
    {
      "_link": {
        "self": {
          "href": "https://serverRoot/quoteManagement/v0/home"
        }
      },
      "list-quote": {
        "href": "https://serverRoot/quoteManagement/v0/quote",
        "title": "Retrieve a list of quote",
        "method": "GET"
      },
      "retrieve-quote": {
        "href": "https://serverRoot/quoteManagement/v0/quote",
        "title": "Retrieve a quote by id",
        "method": "GET"
      },
      "create-mef-quote": {
        "href": "https://serverRoot/quoteManagement/v0/quote",
        "title": "Create a quote using MEF Flavor",
        "schemaUrl": "//quoteManagement/v1/schema/MefQuote",
        "method": "POST",
        "fields": [
          {
            "name": "version",
            "value": "6.0.0-RC"
          },
          {
            "name": "@type",
            "value": "mefQuote"
          }
        ]
      },
      "create-tmf-quote": {
        "href": "https://serverRoot/quoteManagement/v0/quote",
        "title": "Create a quote using TMF Flavor",
        "schemaUrl": "//quoteManagement/v1/schema/TmfQuote",
        "method": "POST",
        "fields": [
          {
            "name": "version",
            "value": "5.0.0"
          },
          {
            "name": "@type",
            "value": "tmfQuote"
          }
        ]
      }
    }​

    With that my customer was able to "understand" that the server could handle both POST Quote for TMF or MEF flavor and we provided the schema url.

    I understood it partially answered your request because here it works at resource level and not at a class level but probably it can provide you some idea.

    Hope it helps

    Ludovic




    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 10.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Feb 21, 2023 11:06

    Hey @Jonathan Goldberg

    Hope you dont mind but i thought to bring my understanding of how we use @type back here as some time back i'd be pondering how to use it properly.

    In my business my API consumers want a really clear interface definition for them to consume at design time and build their client applications to. 

    My problem in the case of @type : 'ExtendedMilestone' If i had not included this in the swagger of my TMF641 API (which i think is the intention of TMF.... i.e. take it off the shelf from the Open API table and never change it) then how when i add in this extended model do i provide this understanding and schema to my client?

    At the end of the day they cannot design or build anything to the extended content it provides if the first time they or their software knows about it is receiving an API response which includes a container which has 

    "@type" : "ExtendedMilestone",
    "schemaLocation" : "//api/v1/schema/ExtendedMilestone"


    So is this a case of saying the intention of TMF for polymorphic extensions is to: -

    • At Design time create
      • A TMF641 schema which exactly matches the one in the Open API table
      • Create lots of other schema documents (not APIs) where each one contains a polymorphic extension subclass (ExtendedMilestone, DavesMilestone, AnotherMilestone)
      • Provide both the TMF641 & your additional 'schema documents' to your API consumers at design time for them to build to
      • Whenver you add a new polymorphic extension subclass (ExtraMilestone) just issue the new schema document
    • At run time
      • deliver the @type/@baseType attritbutes along with schemaLocation to facilitate ????
        • This is what i dont understand as i've given the API consumers the schema document at design time so they can consume into their client and build a client library to handle it, yes the @type/@baseType tell them which of their client classes they could cast it to but how do they use the link?

    In a sense I'm thinking that i still havent quite wrapped my head around what the thinking is on the approach for these extensions because if the above isnt true then i'm not really sure how clients are meant to adopt and write logic based on the attributes contained in the extensions.



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



  • 11.  RE: TMF641 creating milestone events with meta data

    TM Forum Member
    Posted Feb 28, 2023 16:52
    Edited by David Whitfield Feb 28, 2023 16:54

    Hey @Dave Milham

    Do yo know of anyone who can give an explanation of my above questions? Whilst in theory and on paper it sounds good it doesnt really explain how this is meant to work in practice between squads designing and building these apis and squads that are designing and building applications that consume these apis

    cheers

    Dave



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