Open APIs

Expand all | Collapse all

Taking 633 Service Specifications into 638 Services

  • 1.  Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Sep 22, 2021 07:54
    Hi All,

    I've posted previously on the arrangement and linking of service specifications on the catalog and the use of poly morphism which is suggested by the SID examples.

    Now i'm trying to conceive how this transitions into inventory via an order. In the service order API (and inventory) the TMF swagger's just have the service as a single object and the examples in the document dont really show polymorphism (@type = 'service'). So faced with the idea that we are thinking of using poly morphism in the catalog(specifications) I wonder which would be the recommeded approach for order/inventory?

    633-641-638-combined-model


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


  • 2.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Sep 30, 2021 11:24
    Hi David
    I don't think that there is a preference one way or another, it really depends on your business needs and your software architecture considerations.

    P.S. For a realistic example of the strong typing (with polymorphism) as against fully dynamic, see the introduction in the user guide for TMF634 Resource Catalog - I show there how the same resource specification can be modeled dynamically with characteristics or with strongly typed attributes.

    P.P.S. sorry for delay in answering, I have now finished holiday/vacation period and am back to normal work.

    ------------------------------
    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.
    ------------------------------



  • 3.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Oct 01, 2021 07:33

    Everyone needs a good holiday @Jonathan Goldberg, hope you had a good rest!

    Thanks for getting back to me as always.

    I suppose whilst i understand that we can achieve it two different ways my question was really saying if we were to use polymorphism and strong typing in the catalog then shouldnt this also be used in the inventory? I thought that each sub classed specification in the catalog with its own extended attribute data would have to have an equ​ivilent sub classed service in the inventory world? If not (my OR THIS approach above) how do the extension attributes get passed by a client via an order in TMF641 to inventory?

    I did look up your example (TMF634 v4.0.1), thanks for the pointer, its left me with more questions! I'm thinking im missing something but it appears the example contridicts the example given in TMF630 Part2 (v4.0.0). This shows this swagger definition as 

    PhysicalResource:
    title: PhysicalResource
    type: object
    properties:
    id:
    type: integer
    
    Equipment:
    title: Equipment
    type: object
    allOf:
    - $ref: "#/definitions/PhysicalResource"
    - properties:
    operatingState:
    type: string


    and then an example here (ive cut it down)...

    It has the following differences i could see: -
    A - the @type is 'Equipment' which is the custom polymorphic extenstion, Looking at your example it appears to suggest that the @type should actually still be 'PhysicalResource'
    B - the 630 example makes no use of targetResourceSchema field, your example does.

    Is one or the other correct or are these two different methods of extension? I couldnt find an example like yours in 634 within the TMF630 extension guide

    {
    "id": "45",
    "href": "/resourceInventoryManagement/physicalResource/45",
    "publicIdentifier": "07467223333",
    "@type": "Equipment",
    "@baseType": "PhysicalResource",
    "@schemaLocation":
    "http://server:port/resourceInventoryManagement/schema/Equipment.yml",
    "category": "Category 1",
    "lifecyleState": "Active",
    "manufactureDate": "2007-04-12",
    "serialNumber": "123456745644",
    "versionNumber": "11",
    "operatingState": "Working",
    "resourceSpecification": {
    "id": "6",
    "href": "/resourceCatalogManagement/resourceSpecification/6",
    "@type": "PhysicalResourceSpecification"
    },
    "resourceCharacteristic": [{
    "name": "physicalPort",
    "valueType":"Object",
    "value": {
    "@type": "PhysicalPort",
    "@schemaLocation": "http://host:port/schema/PhysicalPort.yml",
    "name": "LAN Port",
    "isActive": true
    }
    },
    {
    "name": "color",
    "value": "red"
    }]
    }






    ​​​​​

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



  • 4.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Oct 01, 2021 07:40
    Hi Dave
    I was actually referring to the section called Characteristic-Based or Schema-Based in the introduction of TMF634 user guide.
    Compare the two JSON payloads below.
    Hope it helps.

    Dynamic
    {
        "name": "Virtual Storage Medium",
        "description": "This resource specification defines the virtual storage medium",
        "@type": "LogicalResourceSpecification",
        "@baseType": "ResourceSpecification",
        "resourceSpecCharacteristic": [
            {
                "name": "Maximum Allowed Storage",
                "description": "The storage limit in the virtual storage medium, ",
                "valueType": "integer",
                "configurable": true,
                "minCardinality": 1,
                "maxCardinality": 1,
                "isUnique": true,
                "resourceSpecCharacteristicValue": [
                    {
                        "valueType": "integer",
                        "value": 1024000
                    },
                    {
                        "valueType": "integer",
                        "value": 2048000
                    }
                ]
            }
        ]
    }
    ​

    Schema-based
    {
        "name": "Virtual Storage Medium",
        "description": "This resource specification defines the virtual storage medium",
        "@type": "LogicalResourceSpecification",
        "@baseType": "ResourceSpecification",
        "targetResourceSchema": {
            "@type": "VirtualStorage",
            "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Resource/VirtualStorage.schema.json"
        }
    }
    And the referred schema file might appear as follows:
    {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "VirtualStorage.schema.json",
        "title": "VirtualStorage",
        "definitions": {
            " VirtualStorage ": {
                "$id": "# VirtualStorage ",
                "description": "This resource specification defines the virtual storage medium.",
                "type": "object",
                "properties": {
                    "Maximum Allowed Storage": {
                        "type": "integer", 
                        "description": "The storage limit in the virtual storage medium",
                        "enum": [1024000, 2048000]
                    } 
                },
                "required": ["Maximum Allowed Storage"],
                "allOf": [
                    {
                        "$ref": "LogicalResourceSpecification.schema.json#LogicalResourceSpecification"
                    }
                ]
            }
        }
    }
    ​



    ------------------------------
    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.
    ------------------------------



  • 5.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Oct 01, 2021 08:12
    understood @Jonathan Goldberg, thanks, that was what i have been looking at, forgive me if im interpreting it incorrectly but if i were to translate the example given in TMF630 into your example i believe it would look like the below and not what you have in the 634 document. Can you point out what im missing?...

    ResourceSpecification:
    title: ResourceSpecification
    type: object
    properties:
    id:
    type: integer
    
    LogicalResourceSpecification:
    title: LogicalResourceSpecification
    type: object
    allOf:
       - $ref: "#/definitions/ResourceSpecification"
    properties:
    name:
       type: string
    
    VirtualStorage:
    title: VirtualStorage
    type: object
    allOf:
       - $ref: "#/definitions/LogicalResourceSpecification"
    properties:
    maximumAllowedStorage:
       type: integer
       enum:[1024000, 2048000]​

    Example (not sure ive got this completely right but hopefully you get the idea of the confusion i have with the different approaches)

    {
    "id": "45",
    "href": "/resourceCatalogManagement/resourceSpeification/45",
    "name": "Virtual Storage Medium"
    "@type": "VirtualStorage",
    "@baseType": "LogicalResourceSpecification",
    "@schemaLocation": "http://server:port/resourceCatlogManagement/schema/VirtualStorage.yml",
    "maximumAllowedStorage": [1024000, 2048000]
    }​



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



  • 6.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Oct 13, 2021 16:47
    Hey @Jonathan Goldberg could you help at all with my confusion on the items above at all?​

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



  • 7.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Oct 27, 2021 12:11
    Hi David
    Firstly, I really must apologize again for not getting back to you earlier.

    I'll try to explain (my understanding of) the polymorphic pattern and how it applies to catalog elements.
    So, before the complication of the catalog, we have the ability to extend the behavior of the vanilla Open API elements. Suppose TalkTalk (for instance) wants to extend Individual with an attribute eyeColour (this is my go-to example of an extension, although it is completely irrelevant to telco business, and has privacy concerns).
    Anyway, you would have a new entity TTIndividual (shall we say), which would look like this:
    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "TTIndividual.schema.json",
      "title": "TTIndividual",
      "definitions": {
        "TTIndividual": {
              "$id": "#ProductOffering",
          "description": "TalkTalk's extension of Individual",
          "type": "object",
          "properties": {
            "eyeColour": {
              "type": "string",
              "description": "The human's eye color"
            }
          },
          "allOf": [
            {
              "$ref": "../EngagedParty/Individual.schema.json#Individual"
            }
          ]
        }
      }
    }​
    In the JSON payload, you would set @type to TTIndividual, @baseType to Individual, and @schemaLocation (conceptually) to point at the file above.
    Now let's go the catalog. TalkTalk might want to extend ResourceSpecification (or other spec entities) for whatever reason, let's say you wanted to add an attribute cost of type Money. It would look very similar to the example above, and the alterations in the JSON ​payload would be in accordance. But this would apply to all your ResourceSpecification entities.
    All of the above is before we come to discuss strongly typed specifications as against characteristic-based specifications. The embedded targetSchema pattern allows you, specifically for catalog specification, to define a further level of specialization, so you can have a strongly-typed VirtualStorage on top of your general extension of ResourceSpecification.
    I hope this rant makes sense. I do have the feeling that the examples I quoted in the user guide document may not be correctly aligned with what I wrote here, and I think that this is what is worrying you.

    ------------------------------
    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: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Nov 04, 2021 08:35
    I know you thought long and hard on this for me to give an answer, so i'm really grateful for that @Jonathan Goldberg!

    I guess in terms of the above if i did want that situation where i was to extend indivdual (or service specification) with an attribute that i wanted to ensure all of my TT objects contained then is there a reason i need to bother with the extension definition, can i not just put that in my implementation of my open api spec. I am therefore stating from the off when an API client consumes my documentation that 'this is what an indivdual looks like', do they need to know there is such thing as a base TMF defined indivdual which doesnt contain one of the attributes?

    I'm not sure i have got my head around @schemaLocation vs @targetSchema, I dont understand what the latter is for. Given the example for Virtual storage i gave above, i considered that to be a strongly typed extension and i understood that @schemaLocation was the correct attribute to use?​​​​​

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



  • 9.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Nov 01, 2021 06:31
    Hi David,

    Although both approaches are valid, the second approach leads to much simpler inventories. The more information is derived from the catalog, the less data needs to be stored in the inventory. The service catalog typically has few (hunderds) of entities where a typical service inventory has many (millions) of entities that are kept as simple as possible.

    Using the technique of the serviceCandidates describing the T-shirt size even most characteristics can be kept out of the service inventory by referencing the serviceCandidate. Unfortunately the reference to the serviceCandidate got ommited from TMF638 v4.0. Moving complexity from the inventory to the catalog greatly improves the efficiency and perofrmance of IT implementations.

    I prefer to use the poymorphism only to fix these ommisions. I personally believe that using polymorphism for defining complex characteristics or even promoting characteristics to properties at the entity level leads to less stable API definitions. TM Forum did a great job at separating the API definitions from service provider specific payloads. The examples provided for polymorphism seem to reverse that logic. That is less beneficial for service providers and more beneficial for those in the business of selling IT change requests. I guess one's perspective changes depending the side you are on.

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



  • 10.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted Nov 04, 2021 11:01
    Hi @Koen Peeters, as always thanks for the input.

    Yes a similar view was being taken internally and the direction was towards the 'or this' approach. We are likely to already have a large number of 'service specific' characterisitics against a service to manage lots of supplier based information which is needed internally from inventory​.

    Your above point is really interesting actually as our approach so far has been to consider an fibre offering (essentially speed) as different service specifications. However if i understand your point in the referenced thread then you're suggesting that you can have a single service specification then each candidate can define the speed characterisitics in the catalog: -

    e.g.

    • ServiceSpecification: Fibre Access
      • serviceCharacteristicSpecifications
        • name: downstream, valueType: integer, unitOfMeasure: MBPS
        • name: upstream, valueType: integer, unitOfMeasure: MBPS
    then

    • ServiceCandidate: Fibre Access Basic
      • characteristic
        • name: downstream, value: 40
        • name: upstream, value: 10
    • ServiceCandidate: Fibre Access Fast
      • characteristic
        • name: downstream, value: 150
        • name: upstream, value: 30
    etc

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



  • 11.  RE: Taking 633 Service Specifications into 638 Services

    TM Forum Member
    Posted 28 days ago
    Hi David,

    This is exactly how I see this.


    The ServiceSpecification and the ServiceCandidate are the answers to two distinct but related questions.
    The ServiceSpecification answers the question "What is a fiber Access". The ServiceCandidate answers the question "which flavours of Fiber Access does this company offer".
    The process of fulfilling a Fiber Acces is probably mostly the same for all candidates. But depending on your network infrastructure each candidate could link your speed to a profile. These profiles typically need to be rolled out over a park of OLT devices. That is an exercise that is not without effort and the decidion to add profiles or modify profiles is not taking lightly and typically is not part of the fulfilment process.

    In the fulfilment process instances of services will reference one of these pre-existing profiles tied to a serviceCandidate.

    I hope this clarifies the reasoning behind the proposed approach.


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