Open APIs

 View Only
  • 1.  TMF641 creating milestone events with meta data

    TM Forum Member
    Posted 15 days ago
    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 11 days ago
    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 10 days ago
    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 10 days ago
    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 10 days ago
    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 10 days ago
    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 10 days ago
    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 2 days ago
    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 yesterday
    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
    ------------------------------