Open APIs

 View Only
Expand all | Collapse all

Template for Resource Specifications

  • 1.  Template for Resource Specifications

    TM Forum Member
    Posted Mar 20, 2023 08:16

    Hello experts,

    I am working on modeling parts of our network as Resources and Resource Specifications, and encountered the following need:

    There are sets of multiple Resource Specifications that share a sizeable list of common Characteristic Specifications. For example, different models of a product, that have many types of characteristics in common (but also many other characteristics that are unique to each model).

    We would strongly prefer to avoid the need to duplicate the list of common Characteristic Specifications in each Resource Specification that needs it. This is where the idea of a Resource Specification Template comes to mind, but I could not identify in the Resource Specification model a natural mechanism to do it.

    I believe this need is also relevant to Service Specifications and Product Specifications, so might have already been considered and addressed by members of this community.

    Any ideas and feedback will be much appreciated.

    Sincerely,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------


  • 2.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 04:44
    Edited by Frederic Thise Mar 22, 2023 04:48

    Hi Opher,

    I would propose to do it using an inheritance mechanism (similar to OOP):

    1. Use the Specification relationship property with relationshipType: "inheritsFrom" to link the concrete Specification to abstract Specifications (multiple inheritance can be supported) where you can put all common "related" objects like characteristicSpecifications, ... You can of course have a tree of inheritance meaning a "base" Specification can also inherits from other "base" Specifications.
    2. Create these abstract Specifications with @type: "AbstractXXXSpecification" so that they can be discriminated from "normal" Specifications and defined as not instantiable for implementation/validation purpose.
    3. During instantiation, you would only create a single instance with a SpecificationRef to the concrete Specification. It will contain all aggregated instantiated objects (Characteristics, ...)

    In order to support an easy way to retrieve your "concrete" Specification and all abstract specifications and have it returned as a single aggregated one, you could use a TMF630 task /full or /aggregated. This task will make sure to navigate the tree of relationships with relationshipType: "inheritsFrom" and collect all characteristicSpecifications, ...

    I would keep the default retrieve/list operations to returns the relationships as they are and have the aggregated version returned only through task in order to keep the expected default TMF behaviour.

    Cheers,



    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 3.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 09:59

    another approach is to group specifications (CompositeProductSpecification). You can also group characteristics (ProductSpecCharRelationship) to create a composite although I have a little doubt about characteristics because xxxxRelationship in the information framework is normally used to create dependencies between characteristics.

    at least, that 's one recommended approach described in GB922 - Product. I suspect the same exist for service and resource since they use the same entitySpec pattern.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 4.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 11:23

    Hello Matthieu,

    Thank you.

    The challenge I have with the approach you propose is that when instantiating a CompositeResource, I would need to also instantiate additional Resources - one for each ProductSpecification that is grouped under the CompositeResourceSpecification. Is that correct? This is something I would really like to avoid.

    Also, when looking in "GB922 - Resource" I find the following note:

    So it's back to ResourceSpecificationRelationship...

    Best regards,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------



  • 5.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 13:14

    Ah! I didn't know about this note in GB922 resource, good catch.

    I also checked the API for product (620) and resource (634) and I see the same. bundle and relationship for productspecs but only relationship for resourcespec.

    For product, it does make sense to instantiate the composite and the bundled productspec (the composite productspec doesn't have any characteristic, it's only a container), it's exactly what we want.

    If you create multiple distinct resourceSpecs and then for most of them create a relationship towards the commonResourceSpec, would that not work?

    regarding Frederic's solution, I have, a long time ago, used a CRM that offered inheritance between productSpecs (and versioning) but I had a complicated experience with this solution. It was simple for the first setup but after a few months, when the first changes, exceptions etc. came around, it became increasingly difficult to manage.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 6.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 13:42

    Hello Matthieu,

    Thanks again.

    I do not understand what the difference is between what you propose ("create multiple distinct resourceSpecs and then for most of them create a relationship towards the commonResourceSpec") and Frederic's solution.

    To the best of my understanding Frederic suggests the same mechanism, but with one further detail - to assign to the "relationshipType" a special value, e.g. "inheritsFrom".

    Another question is about instantiation. As you pointed out, for products it is the desired behavior to instantiate both the composite and the bundled productspec. For resourceSpecs with common characteristicSpecs I find this behavior undesirable.

    Best regards,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------



  • 7.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 23, 2023 04:14

    example of inheritance:

    I create entity "ProdSpecEntityA" with 2 characteristics:

    colour

    size

    I create entity "ProdSpecEntityB" which 1 characteristic:

    weight

    If I connect SpecEntityB as a "child" (for lack of better word) of ProdSpecEntityA, ProdSpecEntityBautomatically inherits ProdSpecEntityB characteristics

    I create a product offering and I assign product spec: ProdSpecEntityB

    that product offering, when presented through UI, API etc would have 3 characteristics

    colour

    size

    weight

    product offering is not aware of ProdSpecEntityA

    composite

    routerSpecEntityC has 2 characteristics:

    speed

    port

    shiptoSpecEntityD has 4 characteristics:

    address line 1

    post code

    etc

    I bundle the above 2 specs into a composite productspec: bundleSpecEntityE

    I create a product offering and I assign product spec: bundleSpecEntityE

    the product offering is aware that there are 2 distinct productspecs, which I can use in the UI to construct a different user experience during order capture.

    sorry I couln't help you.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 8.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 23, 2023 07:06

    Hello Matthieu,

    Thank you very much for the discussion, it does help me!

    I well understand inheritance and composition.

    The main difference between Frederic's solution and inheritance is how to retrieve the combined specification (ResourceSpecEntityA+ResourceSpecEntityB in your example).

    With 'pure' inheritance it will be: GET ~/resourceSpecification/ResourceSpecEntityA

    In Frederic's solution you need a dedicated Task resource: POST ~/resourceSpecification/ResourceSpecEntityA/aggregate

    Because the GET request will only retrieve ResourceSpecEntityA, without aggregating the characteristic specifications from ResourceSpecEntityB, so nothing will be done implicitly.

    Best regards,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------



  • 9.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 13:32

    Hi Opher,

    As a simpler alternative to using polymorphism and the composite pattern, in alvatross we decided to extend the catalog with characteristic templates so that you can manage these entities independently and reuse them in all catalog specifications. Furthermore, in the last versions of the catalog APIs they introduced the concept of feature, which are groups of characteristics. I think it would be interesting, in terms of reusability, to manage feature templates as well.

    Hope it helps,



    ------------------------------
    Abel Ruiz Huerta
    alvatross by SATEC
    ------------------------------



  • 10.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 22, 2023 13:51

    Hi Abel,

    Thank you.

    Indeed, my initial thought was also of templates. However, I did not see how to do it in a way that is compliant to the TMF634 API. Have you found a way to make it compliant?

    One note - the use of a new type AbstractResourceSpecification is not full polymorphism, but rather mostly to distinguish between the two types. They are both stored in the same DB table, with the same structure, and no new JSON schema is necessary.

    Best regards,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------



  • 11.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 23, 2023 04:32

    Hi Yaron,


    Extending an API does not necessarily imply that it is no longer compliant. In fact, we have extended ours and all of them are compliant and certified. To be compliant you just need to manage some entities, which should have some attributes, operations, etc. Adding and managing a new entity does not prevent you from continuing to be compliant.
    About your note, you are right, and I think that this is a valid approach to implementing specification templates. We decided to use separated templates because in our case this entity is shared by the three catalogs (product, service, and resource). 


    There are many options. Depending on your specific needs, some will fit you better than others.


    Best regards,



    ------------------------------
    Abel Ruiz Huerta
    alvatross by SATEC
    ------------------------------



  • 12.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 23, 2023 08:08

    Hi Abel,

    Thank you for the discussion. It is very helpful.

    I am curious, how do you represent and store the link between a specification and a template? Is it evident in the specification which template it uses?

    Best regards,



    ------------------------------
    Opher Yaron
    Proximus SA
    ------------------------------



  • 13.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 27, 2023 03:33

    Hi Opher,


    When we want to maintain the reference between the specification and the template (sometimes we don't want this, i.e. you just want to copy the template in the specification), we use a characteristicSpecificationRef object, following the same pattern used throughout all the TM Forum APIs,


    Best regards,



    ------------------------------
    Abel Ruiz Huerta
    alvatross by SATEC
    ------------------------------



  • 14.  RE: Template for Resource Specifications

    TM Forum Member
    Posted Mar 27, 2023 08:38

    Hi all

    Very interesting discussion. Based on Opher's initial request, I'm considering introducing a template-type entity into the Open API model that will allow authoring of specification templates, which can be used to instantiate catalog specifications. It will hopefully be useable for P/S/R catalogs.

    Watch this space.



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