Open APIs

 View Only
Expand all | Collapse all

Characteristic array under Relationship pattern in version 5 of TMF APIs

  • 1.  Characteristic array under Relationship pattern in version 5 of TMF APIs

    Posted Nov 24, 2023 08:00

    Hello,

    The question is whether version 5 of the APIs intends to contain a Characteristic array under the Relationship pattern.

    I reviewed one pair of APIs that already have version 5 in Production - TMF620 Product Catalog and TMF637 Product Inventory.

    In the Swagger of TMF620 I find:

    In particular, ProductSpecificationRelationship contains a "characteristic" attribute of type CharacteristicSpecification.

    However, in the Swagger of TMF637 I find:

    In particular, ProductRelationship does not contain a "characteristic" attribute.

    The two specifications seem incompatible to me. Do I miss something? If not, which one of these 2 APIs is 'correct'?

    Thank you and best regards,



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


  • 2.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Nov 26, 2023 07:46

    It should probably be added to the inventory API, thanks for the catch Opher.



    ------------------------------
    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: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Nov 26, 2023 08:24

    I looked further into this, there is an existing JIRA for this waiting to be executed.

    https://projects.tmforum.org/jira/browse/AP-2928



    ------------------------------
    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: Characteristic array under Relationship pattern in version 5 of TMF APIs

    Posted Dec 06, 2023 06:31

    I am coming back to my original question.

    Thank you, @Jonathan Goldberg, for the information.

    This JIRA (https://projects.tmforum.org/jira/browse/AP-2928) is indeed related, but seems to be more focused on the RelationshipCharacteristicSpecification in TMF620 than on the RelationshipCharacteristic in TMF637.

    The only reference to TMF637 I can find there is this comment at the end:

    But I find it confusing, because, as I wrote in my original post, the Swagger of TMF637 does NOT contain RelationshipCharacteristic.

    @Matthieu Hattab - with regards to your message: "The inventory API already has references to the Product Offering and Product Specifications, so one could easily find the PS relationships from the product catalogue." I do not exactly understand what you mean. The way I understand it, the common pattern is to have all specifications in Catalog Management, and all instances in Inventory Management. For example, you can have RelatedEntitySpecification in some catalog, and RelatedEntity in the corresponding Inventory. Shouldn't it be the same with RelationshipCharacteristicSpecification/RelationshipCharacteristic?



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



  • 5.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Dec 06, 2023 11:06

    the product in the inventory has a reference to the Product Specification:

    you can query that product spec with TMF620 V5 and then you can see the productspecificationrelationship and the characteristic that refines the
    relationship.
    I'm not sure the characteristic that refines the relationship should be instanciated in the product inventory. That characteristic is used to enforce a business rule.
    if possible we should keep the api payload as lean as possible.
    Why do you need it for?



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

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



  • 6.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    Posted Dec 07, 2023 02:32

    Hello Matthieu,

    Instantiation of such a characteristic addresses your other question. In your example:

    A CharacteristicSpecification of the ProdSpecRelationship defines the options of required bandwidth, and an instantiation will define the bandwidth that is actually selected for the specific instance of TVProd.

    Does this make sense?



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



  • 7.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Dec 07, 2023 04:55

    the modification you've done on my diagram would work for TMF620. (I'm hoping Jonathan can confim it because that would mean I need to split my TVProdSpec:

    1. one 8KTVProdSpec for 8K channels, where I could add the CharSpec under the ProdSpecRelationship to restrict certain bandwidth values on the Fiber PS, as you updated on my diagram
    2. another one for other resolutions (4K, HD and SD)

    However my model was really for TMF620.
    do you have a need ot see the characteristic under the productrelationship in TMF637?



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

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



  • 8.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    Posted Dec 15, 2023 09:10

    My question was rather generic, about the pattern of CharacteristicSpecification under SpecificationRelationship and Characteristic under Relationship. I used TMF620/TMF637 as example, because version 5 of TMF620 has already been released. In the meantime version 5 of TMF634 (resource catalog) has also been released, and it also contains CharacteristicSpecification under SpecificationRelationship.

    When I look at inventory management APIs, I see inconsistency. For example, TMF639 (Resource) and TMF637 (Product) do not have Characteristic under Relationship, but TM638 (Service) has:

    The one I am really interested with is ResourceSpecification/Resource, but I believe we should adopt the same approach to all similar APIs.

    Best regards,



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



  • 9.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Nov 28, 2023 09:51

    Hello,

    The inventory API already has references to the Product Offering and Product Specifications, so one could easily find the PS relationships from the product catalogue.

    I think the inventory should only have references of what customer has acquired (PO, PS, char, charvalues etc) and no data at all (product name, chosen offers, etc) except when the entity is not has a managed entity (like characteristic value) and then use TMF620 to get the accurate data (from product name to relationship etc).
    Keep the API simple, don't add Characteristic array under the Relationship!

    Interestingly, the benefit of TMF API is to have data in a single source of truth and avoid data duplication. This particular benefit was actually showcased by TM Forum to illustrate how a a Chinese telecom CSP has used TMF APIs and avoid storing data in different places (TMF said this CSP saved millions of dollars just by reducing data storage needs)



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

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



  • 10.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Nov 28, 2023 18:13

    @Jonathan Goldberg,
    Using the characteristic relationship between ProductSpecificationRelationship and CharacteristicSpecification and the provided description, does it support creating relationship between charvalues of 2 different ProdSpec? Using the textual example in the API documentation, can we achieve this:



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

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



  • 11.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Nov 29, 2023 15:05

    Hi Matthieu

    The way the characteristic relationship is currently defined for APIs, I don't think it meets your needs. It gives you a connection between characteristics, not between their values. The SID takes this one level further and gives you a relationship between characteristic spec values.



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



  • 12.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Dec 04, 2023 11:17

    Hi,

    the defintion in the API user guide says:

    A characteristic that refines the relationship. For example, consider the relationship between broadband and TV. For a 4k TV it is important to know the minimum bandwidth to support 4k, so a characteristic Resolution might be defined on the relationship to allow capturing of this in the inventory

    do you have a working illustration of the above definition?

    I can't find a way to model the example provided in the user guide:



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

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



  • 13.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Feb 04, 2025 02:27

    Hi @Matthieu Hattab.

    I was looking for any topic regarding productSpecificationRelationship - characteristic and found this discussion. Unfortunately your last question is not answered. Have you found the way how to model the relationship between broadband and TV since your last post?



    ------------------------------
    Jan Brnka
    T-Mobile Czech & Slovak Telekom, a.s.
    ------------------------------



  • 14.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Feb 04, 2025 05:42

    Hi,

    As the TMF Product Catalogue only supports simple business rules, we opted not to use it for storing our business rules. Over time, we've realised that it has too many gaps and compromises, making it unsuitable for our needs.

    Currently, all our business rules are implemented in code within TMF components such as the Product Configurator, Product Offering Qualification, Service Qualification, and Product Recommendation. However, this approach is not scalable.

    We are actively investigating external rule engines, potentially something similar to the ECA model from the TMF Policy component. A dedicated policy component could support product, pricing, and eligibility rules without the constraints of the TMF Product Catalogue. Rules can be stored with Decision table, FEEL language which are a low-code/no-code solutions to manage rules' conditions.

    Tools under consideration:

    • Gorules
    • Drools/Kogito/jBPM/OptaPlanner (suite)
    • OpenRules
    • Nected
    • Camunda DMN
    • ...

    A key issue is that these rule engines are not self-contained. They require all relevant facts to be provided upfront in the API request, which violates TMF API compliance. One of the core ODA component principles is that they must be self-contained. And TMF API are not designed to provide relevant facts upfront in the API POST request.

    To address this, we may need a hybrid approach, combining a rule engine with an event-driven orchestrator (e.g., n8n, Node-RED, Camunda, or Apache NiFi) to handle "missing" facts. Alternatively, we could implement built-in dynamic fact retrieval within the rule engine. Some developers have also suggested using introspection.

    It's a complex challenge.



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

    Matthieu Hattab
    Lyse Tele AS
    ------------------------------



  • 15.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Feb 06, 2025 10:26
    Edited by Jan Brnka Feb 06, 2025 10:28

    Thank you Matthieu for the answer! Very useful and comprehensive (as always :) ).

    The conclusion for me is that the example of "relationship between broadband and TV" is not covered by productSpecificationRelationship - characteristic. So what's the goal/purpose of productSpecificationRelationship - characteristic? Could you please provide an example? 

    Regarding the TMF Policy Component, I was unable to find detailed information. I did come across the TMF723 Policy Management API and found the Swagger file, but there is not a corresponding user guide. Although I found a brief reference in the GB922 documents, there was no concrete example like in other user guides. Could you please provide an example, particularly one illustrating the "broadband and TV" scenario?
    ------------------------------
    Jan Brnka
    T-Mobile Czech & Slovak Telekom, a.s.
    ------------------------------



  • 16.  RE: Characteristic array under Relationship pattern in version 5 of TMF APIs

    TM Forum Member
    Posted Feb 06, 2025 13:17

    the graphical example between TV Char values and Broadband char Value is indeed not supported, as confirmed above by Jonathan:

    The way the characteristic relationship is currently defined for APIs, I don't think it meets your needs. It gives you a connection between characteristics, not between their values


    On policy, while there is no "Policy" ODA component, yet, TMF describes the Policy Information model in great details:

    • GB922- common has a complete chapter on policy, see "4.21. Policy ABE"
    • GB922 - product has an complex pricing example of using policy. See  "Figure Pr.14 - Product Offering Price Governed by Policy and subsequent pages."

    So what's the goal/purpose of productSpecificationRelationship - characteristic? Could you please provide an example? 

    PS=ProductSpecification 

    let's define this ProductSpecificationRelationshipPS1 requires PS2

    The CharacteristicSpecification under ProductSpecificationRelationship would represent the characteristics of the ProductSpecification  involved in the relationship (either PS1 or PS2).

    Based on the Swagger YAML file and the user guide, we cannot explicitly state which CharacteristicSpecification relates to which ProductSpecification (PS1 or PS2) in the relationship.

    Specifically, when we say "PS1 requires PS2", it could mean 2 things for the CharacteristicSpecification:

      • PS1 (the ProductSpecification that requires another) may have certain characteristics that are required (in the case of a "requires" relationshipType) by PS2.
      • Or, PS2 might contain characteristics that PS1 depends on. In this case, the CharacteristicSpecification would represent the characteristics of PS2 that are necessary for PS1 to be valid or usable.

    the only question left is to determine if the list of CharacteristicSpecification belong to PS1 or PS2. I think your implementation can make that decision, according to your needs. 

    As I'm not a developer and have little clue on this, I asked a generative AI to help identify best practices, common patterns in the API dev community that could help me understand if CharacteristicSpecificationentity belong to PS1 or PS2. Here is the answer:

    If we were to make an educated guess based on common patterns used in APIs and the structure of relationships in similar domain models, here's how we might reason about which ProductSpecification the CharacteristicSpecification is related to in the context of a ProductSpecificationRelationship:

    • Pattern of Dependency Relationships:

      • In many APIs, when there is a dependency between two entities, like PS1 requires PS2, the dependent entity (PS1) often needs the characteristics of the referred-to entity (PS2).
      • In this case, PS1 requires PS2, so the characteristics that are relevant to PS1 would likely be the ones associated with PS2. This makes sense because PS1 might depend on certain attributes or features from PS2 in order to function properly.
    • Characteristics and data Ownership:

      • Generally, characteristics are defined by the entity they belong to. If an entity (like PS1) requires another (like PS2), the characteristics specified in the required entity (PS2) are those that are needed by the requesting entity (PS1).
    • Standard API Modeling for Relationships:

      • In APIs that define relationships between entities (e.g., dependencies, inclusions, exclusions), the characteristics of the secondary entity (PS2) are often the ones that are explicitly stated or referenced in the relationship.
      • For example, in a product catalog API, if a product (PS1) requires another product (PS2), the characteristics of PS2 would likely be important to the functionality of PS1.

      Based on my original diagram, I could then say:

      TVProductSpec requires FiberBroadbanSpec with Bandwidth Char = {250 mbps...1000 mbps}...

      ...which could look like this (I simplified the TMF620 payload):

      {
          "name": "PS1",
          "productSpecificationRelationship": [
              {
                  "characteristic": [
                      {
                          "name": "Bandwidth",
                          "productSpecCharacteristicValue": [
                              {
                                  "name": "Bandwidth",
                                  "values": [
                                      "250 Mbps",
                                      "500 Mbps",
                                      "750 Mbps",
                                      "1000 Mbps"
                                  ]
                              }
                          ]
                      }
                  ],
                  "name": "PS2",
                  "relationshipType": "requires"
              }
          ]
      }

      I now use the concept of policy for these kind requirements... It's just easier.

      Have fun.



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

      Matthieu Hattab
      Lyse Tele AS
      ------------------------------