Open APIs

Expand all | Collapse all

Catalog-related API's - lifecycle management & candidate purpose

  • 1.  Catalog-related API's - lifecycle management & candidate purpose

    TM Forum Member
    Posted Jul 25, 2021 18:47
    Edited by Carlos Portela Jul 26, 2021 03:18
    Hello community,

    As part of our current implementation on Service Catalog, we are now looking on managing the specification lifecycle with multi-versioning. At the moment, from the TMF633 presented root resources (serviceCatalog->serviceCategory->serviceCandidate->serviceSpecification), we are only supporting the serviceSpecification resource level as it is being sufficient for our current need. From this investigation for lifecycle/versioning, there are some points I would like to raise:
    • 1.1 - ServiceCandidate purpose?: With this new need to evolve from our current implementation, we've reviewed the possible need of implementing the other root resources from TMF633. I understand the use of serviceCatalog and serviceCategory but, honestly, I am finding difficult to understand the real use and purpose of the serviceCandidate (I've taken a look on other threads as this one but didn't help much). Despite its meaning in SID, I think this resource is bringing more complexity on the API model as it has a 1-to-1 mapping to serviceSpecification and both resources can maintain lifecycle status, versioning, validation. The ID attribute, if not replicated at both levels, will be also confusing for the API user. In fact, all the attributes from serviceCandidate are also possible to be set at serviceSpecification level.
    • 1.2 - Catalog suggestion for evolution: Here's a suggestion for thought on how could catalog API modelling evolve: It could be interesting to have a new resource root being ServiceSpecGroup that defines a single specification identifier and aggregates multiple versions of a specification. In this case, a serviceSpecGroup resource should link to 1 or multiple serviceSpecVersion (currently known as serviceSpecification resource). Please take a look in the picture added below.
    • 2 - ServiceSpec ID+Version: For our use-case, we are planning to not take serviceCandidate resource into account but only serviceSpecification resource. We will use the version attribute to maintain a spec lifecycle together with the ID, lifecycleStatus and validFor. As it is not fully clear in the API User Guide, is it okay to assume that a single serviceSpec.ID attribute can be used in multiple serviceSpec records if the version is different? In this case, the key for a serviceSpec should be always based on ID+Version.
    • 3 - Catalog version gap?: In case we take the approach from the point 2, we foresee a challenge in our catalog modelling. Today, based on the TMF633 (Service Catalog API) definition, it is possible to realize from a serviceSpec a specific version of a resourceSpec. However, this is not possible between serviceSpec's via the serviceSpec relationship. I think this will be challenging to define service (ie CFS-RFS) dependencies and relationships if this attribute is missing on the sub-resource ServiceSpecRelationship. Note that the same is missing at TMF620 (Product Catalog API) between productSpecs but it exists to refer a serviceSpec version from a productSpec. Could this attribute be considered & added (at relationship level) on a new version of the API?

    Suggestion to aggregate multiple serviceSpec versions into a single serviceSpecGroup
    Thanks in advance for your sharings


    ------------------------------
    Carlos Portela
    Prodapt Solutions
    ------------------------------


  • 2.  RE: Catalog-related API's - lifecycle management & candidate purpose

    TM Forum Member
    Posted Aug 10, 2021 09:12
    Edited by Carlos Portela Aug 10, 2021 09:31
    Hello community,

    Is there someone who could provide his view on this post?

    Our main concern is on the point 2 and 3 from above. I will try to sumarize it better:
    As we are working on the catalog lifecycle management, we expect to use the version attribute from the service specification (TMF633) to distinguish the different updates on a spec. However, with the current API model, we are struggling to use the "serviceSpecRelationship" to relate a service version to other specific service version because this sub-resource doesn't have a "version" attribute available.
    For example, I would like to model an IP Service CFS Spec (v1) and define a specRelationship to an UNI (v2). Note that both UNI v1 and v2 are "launched" and active in our catalog and, thus, this differentiation is needed.

    Thanks for the collab

    ------------------------------
    Carlos Portela
    Prodapt Solutions
    ------------------------------



  • 3.  RE: Catalog-related API's - lifecycle management & candidate purpose

    Posted Aug 11, 2021 03:16
    I think that different version will have different id's and thus the id in the refernce will point to the corret spec.

    ------------------------------
    Tony Wilhelmsson
    Tele2 Sverige AB
    ------------------------------



  • 4.  RE: Catalog-related API's - lifecycle management & candidate purpose

    TM Forum Member
    Posted Aug 16, 2021 04:17
    Hey Tony,

    Thanks for your reply.

    I wonder what would be the purpose/use of the version attribute if we keep having ID uniqueness. How would you identify that multiple versions belong to a single spec if you dont have a common ID?
    For me, and also aligned with @Jonathan Goldberg feedback on this link, it should be possible that the same ID can co-exist with an only differentiation at version attribute. However, if we look to the current TMF633 resource model, I see some challenges by following such approach.

    Would be interesting to hear some feedback from OpenAPI collaborators that worked on the catalog & versioning.

    Regards,
    Carlos​

    ------------------------------
    Carlos Portela
    Prodapt Solutions
    ------------------------------



  • 5.  RE: Catalog-related API's - lifecycle management & candidate purpose

    Posted Aug 16, 2021 07:17
    HI
    If the approach is to use id+version as unique identifier then I agree that one need version i references and relationships.

    ------------------------------
    Tony Wilhelmsson
    Tele2 Sverige AB
    ------------------------------



  • 6.  RE: Catalog-related API's - lifecycle management & candidate purpose

    TM Forum Member
    Posted Aug 17, 2021 14:59
    I would like to contribute my idea on some of the questions raised.

    • serviceCandidate: The serviceCandidate is not worked out well in the current TMF633. My take on it, is that a serviceSpecification describes which characteristics and relationships we want to capture for a service. For a VDSL service this could be an upstream and downstream bandwith with the range of values supported by the technology. For a service like VDSL, an service provider typically does not offer all the possible values to the market. In a consumer market typically only a limited set of T-shirt like sizes is offered: S, M, L and XL each with specific values for upstream and downstream  bandwidth.The serviceCandidate identifies in this case the T-shirt sizes on offer. This is particularly important if this alligns with profiles that need to be preconfigured and rolled out on a park of DSLAM before they can be offered on the market. The serviceCandidates describe then the preconfigured profiles available. ProductManagement can then use these serviceCandidates to link them to separate productOfferings, each with a different prices and terms.
    • ServiceSpecId and version are meant to handle sequential improvements of serviceSpecifications. Going forward we want to capture an extra characteristic maxLatency for a service. To achieve this a new version of the serviceSpecification is created that is 'inStudy', 'inDesign', 'inTest'. Test platforms can be configured to recognise the inTest versions so that testing can be performed. The production platform should however only be allowed to sell 'launched' versions. An active but not launched status would allow testing on a productionplatform (friendly user testing) In this logic it does not make sense to have two versions launched as there would be no reason to sell the older version after the new is launched. Setting a new version to launched should therefore automatically set the previously launched version to retired. This means it should no longer be used for new services, but obviously many instances of the older serviceSpecification will still exist in the service inventory. Maybe that doesn't bother us at first and we wait for these instances to disappear over time. Otherwise we might perform a data and/or techical migration that includes adding value for the new "maxLatency" characteristic.
    • Use of version in relationships: This question is a difficult one as several strategies can exist. If our CFS consumerInternet requires an RFS VDSL it will use automatically the launched version. If we improve the RFS definition it can be advantageous that this CFS transparantly uses the newly launched version of the RFS. In that case a relationship does not require the version. For dependencies this can be a different story. The VOIP add-on CFS depends on a consumerInternet CFS. If the consumerInternet has an older version with no latency limit and a new version with a maxLatency characteristic, we might want to signal the the VOIP add-on depends on a particular version of the consumerInternet CFS. It is the question if that dependency requires then a well defined version or rather a minimum version. I personally think that a minimum version would be preferable.

    It is important to understand that TM-Forum does not define an implementation but it defines only the minimum requirement for an implementation. Actual implementations will still extends this minimum implementation with implementation specific extensions.

    I hope my little story helps in increasing understanding.

    Regards

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



  • 7.  RE: Catalog-related API's - lifecycle management & candidate purpose

    TM Forum Member
    Posted Aug 18, 2021 11:53
    Edited by Jonathan Goldberg 27 days ago
    Hi all

    Apologies for stepping in so late, I'll try to make it quick:

    • Service and Resource Candidates - in my opinion these entities have no value at all. None, zilch, nada. So much so that I submitted change requests to remove them from the Open API and from the Information Framework (SID). Basically the Candidate entities have id, href, name, description, and reference to the Specification entities. Due to lack of interest in these CRs, I have withdrawn them, but I have not changed my views on these entities, and it seems to me that one can achieve a perfectly valid catalog model without them (apart from the unfortunate fact that product catalog entities refer to these candidate entities :( ).
    • As described in the Version section of the various Catalog API user guides (towards the end of the document), the id does not change between versions, and the implication is that the id+version together become the primary key. However the assumption is that if version is not supplied then the current (latest) version is intended. Therefore the points made above about the version missing from relationship entities appears to be valid, and we should consider correcting this. @Kamal Maghsoudlou what do you think?
        • Regarding the suggestion for service spec group, seems to me to be an unnecessary complication in the model. If you want (for some reason) to retrieve all versions of a catalog entity, there needs to be a specific end-point for that. The Open API team is working on a pattern for entity version and history, so watch this space (but don't hold your breath, it's early days in that work).
        ​Hope it helps

        ------------------------------
        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: Catalog-related API's - lifecycle management & candidate purpose

        TM Forum Member
        Posted Aug 18, 2021 21:45
        Edited by Vance Shipley Aug 18, 2021 21:58
        A Resource/Service Catalog is an entity, of which there may be many, containing an array of Categories. Categories are entities containing an array of Candidates which reference a specific Specification. So to understand what is "made available" by a Catalog it is necessary to navigate the relationships.

        I understand that most people view a "Service Catalog" as being the REST Collection returned from GET /serviceCatalogManagement/v4/serviceSpecification however that is not what TMF633 tell us. So go ahead and ignore Catalog, Category and Candidate for your purposes but their use remains valid.

        The question about versions is an interesting one. I can see the logic in the id attribute remaining the same while the version increments however the implication is that there is only one version available. It seems equally valid to retain the old entity and create a new one, requiring a new id. But what is the implication on the reference? In the first case there is only one entity available so at best version in the reference is a validity check. In the second case since id is a mandatory attribute version isn't performing a discrimination between available entities of different versions.

        I would suggest that if and when this issue is addressed a solution should support Semantic Versioning.  If serviceSpecification.version: 4.1.32 then a reference with serviceCandidate.serviceSpecification.version: 4.1 would match but serviceCandidate.serviceSpecification.version: 4.1.29 would not.

        ------------------------------
        Vance Shipley
        SigScale
        ------------------------------
        ------------------------------


      • 9.  RE: Catalog-related API's - lifecycle management & candidate purpose

        TM Forum Member
        Posted 27 days ago
        All,

        Thanks a lot for your juicy input.

        I think it will always be our implementation choice between the two options:
        • Option 1: Supporting versioning attribute uniqueness re-using same specId
        • Option 2: Simply increment the specId's on every version (and possibly even discard the usage of version attribute).
        Now, I disagree with @Vance Shipley when we discuss about having a single version available at a time and that's when Option 1 becomes challenging to apply with the current TMF633/620 OpenAPI model.

        I think multiple versions of the same specId can co-exist and be on an available state at the same time. We could imagine that new business requirements drive few changes in the CFS service characteristics (add/remove) and it is not always possible to grant backwards compatibility. When this is the case, we cannot force all SOM northbound consumers to adapt their product-service decomposition logic and catalog. Some BSS systems will still order an older version of a CFS and the SOM layer should still accept both.

        The multiple spec versions available may not mean only different characteristics but also different relationships. For example, a CFS OTT Service v1 might rely on CFS Connectivity v1 but the CFS OTT Service v2 might rely on CFS Connectivity v3. Another example is that, CFS OTT Service v1 would decompose into RFS IPTV Account v1 while CFS OTT Service v2 would decompose into RFS IPTV Account v5. These are the kind of use-cases that cannot be defined or retrieved from the catalog using the existing Catalog API model because it is not possible to specify versions (but only specId) on the relationships between entities from same SID level (Product or Service).

        Of course that, if multiple versions are not simultaneously available or there is backwards compatibility on the latest version, this kind of issue would not exist but that is not always possible on our use-cases.

        ------------------------------
        Carlos Portela
        Prodapt Solutions
        ------------------------------



      • 10.  RE: Catalog-related API's - lifecycle management & candidate purpose

        TM Forum Member
        Posted 26 days ago
        Wiping the egg off my face, I see that I had forgotten about the Lifecycle Management Extensions to Catalog which introduce a syntax to discriminate version:  /id:(version=x). This extension pattern should really be described in TMF630. I do still think a future version should describe the use of semantic versioning.

        I also missed the point that ServiceSpecRelationship does not contain a version attribute, unlike ServiceSpecificationRef which does.  So yes, that surprises me, and it seems like it should be added.

        ------------------------------
        Vance Shipley
        SigScale
        ------------------------------



      • 11.  RE: Catalog-related API's - lifecycle management & candidate purpose

        TM Forum Member
        Posted 26 days ago
        At the risk of spattering more egg (sorry Vance), the version pattern is indeed described in the design guidelines. TMF630, Part 4, has Chapter 2 Entity Versioning and Lifecycle Management. The entire DG set is downloadable here.

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