Open APIs

 View Only
  • 1.  TMF620 - Product Catalog Resource Versioning

    Posted Nov 22, 2023 09:42
    Edited by Ilyas Premji Nov 23, 2023 04:23

    Hi, TM Forum members

    I have a few questions regarding the versioning of catalog resources in TMF620.

    In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

    In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

    Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

    • required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
    • optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
    • prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

    Thanks in advance for any input on the subject!



    ------------------------------
    Igor Timarac
    TO BE VERIFIED
    ------------------------------



  • 2.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Nov 24, 2023 11:58

    Hi,

    I agree with you that the versioning specifcation is unsufficiently clear.

    A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

    This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

    I suggest to change the OpenAPI specification for version creation to reflect this:

    • POST /{path}/resource : create a new entity
      • Content-Type: application/json
    • POST /{path}/resource/{id}: create a new version 
      • Content-Type: application/json-patch+json or application/merge-patch+json

    Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

    The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

    There is are more versioning requirements that have to do with the lifecycle.

    • Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
    • There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
      • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
      • maybe other rules need to be defined 

    Regards



    ------------------------------
    Koen Peeters
    OryxGateway FZ LLC
    ------------------------------



  • 3.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Nov 26, 2023 07:45

    Hi Igor and Koen

    We should distinguish between revisions and versions. In gen5, we introduce a history pattern, that allows expression of a history of entity revisions. A new set of guidelines for gen5 is nearing completion, and it will include extensive coverage of the history pattern. This is completely server-managed, in principle each change or set of changes to an entity cause a revision (think file revisions in Microsoft Office, for example).

    The Version field, present in many of the Open API catalog entities (product/service/resource/entity) is completely different from this. The consumer of the API operations "decides" when a new version is to be created, and uses POST with the ID to create a new version. In v4 APIs the tooling didn't really support this, and so manual intervention would have been needed in the swagger to add the ID. Hopefully this was resolved in gen5.

    Koen is correct, in principle, about the interaction between entity states and versions; we didn't really addressed this in the user guide and it would probably be a useful addition. I would say that more generally we need to consider the whole area of Product Lifecycle Management (PLM) going forward in TMF620 (and similarly for the S/R/E catalogs).



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



  • 4.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Mar 01, 2024 08:02

    Hi, TM Forum members

    Relating what Jonathan explained "revision vs. versioning" and trying to match those concepts to the Notification Resource Models in both TMF620 v4 and v5 the create vs valueChange events pose me the following doubts:

    • If I modify a PO characteristic value while keeping the same version this should trigguer a productOfferingAttributeValueChangeEvent while if the version is changed the event should be productOfferingCreateEvent?
    • Should a catalog allow the user to modify a PO characteristic value while keeping the same version if the PO status is "Active"?
    • Is the "Product Offering Attribute Value Change Event" applicable to any entity with status not in("In design";"In Test")?

    Thanks in advance for any input on this.



    ------------------------------
    Gonçalo Furtado
    Celfocus
    ------------------------------



  • 5.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Mar 01, 2024 09:11

    Hi Gonçalo,

    A revision is any change to an entity. An application that supports notifications should emit a notification for each revision. The history can therfore be seen as the sequence of notifcations.

    A version is a different instance of an entity with the same id but a different version value. A version is created by an action of the user. The main difference between a version and an entity is that version have an lifecycle that is implicitly interlinked.

    So to answer your questions:

    • Your assumption matches mine. changing a characteristic generates a notification that basicly provides the next revision. Creating a new version should generate a ProductOfferingCreateEvent.
    • Depending on the lifecycleStatus, changing a characteristic could be prohibited e.g. changes are allowed for lifecycleStatus inStudy and inDesign but not for any other  lifecycleStatus. for lifecycleStatus inTest and beyond probably only the lifecycleStatus can be changed by the user, because it starts impacting processes in other systems. That is where creating a version becomes interesting. It creates a new instance where changes can be prepared, tested before being launched in production. OAS doesn't provide a good way to model these rules, but in our Gateway product we use non TMF JSON objects to define these rules.
    • All catalog entities basically use the same lifecycle with the same lifecycle transition rules. Lifecycle for other TMF entities can be different and therefore requires a different set of rules. 

    I agree that interoperability can be difficult beause of the lack of guidelines around this lifecycle management. TM Forum balances between stricter implmentation rules and allowing innovation, but I believe at some moment in time a more detailed guideline will be required to improve interoperability.

    Regards



    ------------------------------
    Koen Peeters
    OryxGateway FZ LLC
    ------------------------------



  • 6.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Mar 05, 2024 07:32

    We're now working on an update to the design guidelines Part 4, which deals with entity versioning. So hopefully we will be able to make some improvements and formalize the semantics of entity versioning.



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



  • 7.  RE: TMF620 - Product Catalog Resource Versioning

    Posted 2 days ago
    Edited by Igor Timarac 2 days ago

    Hi, everyone

    Sorry for a late reply. As we were on a tight schedule to derive a PoC for versioning in our system and we confirmed internally that the current draft was indeed inconsistent with Swagger DTOs, we went with a custom approach (additional endpoints) from the get go, and I failed to keep up with this discussion.

    Thank you very much for your inputs and assistance on the matter, we're looking forward to the updated design guidelines.

    Best regards,

    Igor



    ------------------------------
    Igor Timarac
    Codaxy d.o.o
    ------------------------------