Open APIs

 View Only
  • 1.  TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 19, 2023 10:05

    I am looking at the version 5 TMF620 and pleased to find the 'Selection Group' problem has been solved.

    However I am struggling with some of the options given for definitions.

    I believe I understand the basic premise, e.g. if my "Consumer Broadband" consists of 

    ProductOffering: Consumer Broadband (isBundle=true)

        BundledGroupProductOfferingOption

            1: { name=Routers , numberRelOfferLowerLimit=1, numberRelOfferUpperLimit=1, productOffering: [ ... some routers .. ] }

            2: { name=Gifts , numberRelOfferLowerLimit=0, numberRelOfferUpperLimit=1,, productOffering: [ ... some gifts.. ] }

    I can see how things like Speed can go in here, though at some point you are looking at it really being a different Offering altogether (if the customer ends up with a different item, for a different price, is it really the same thing? But that's down to the data going in.

    This is extremely close to something we implemented internally, albeit with different key names. Migrating should be straightforward.

    However, in JSON Examples in TMF620 document, on page 62, the bundledGroupProductOfferingOption array attribute is directly beneath productOffering

    But in the swaggerfile itself, the productOffering has bundledGroupProductOffering (with a name) which in turn has bundledGroupProductOfferingOption (an object with the lower, upper and array of the Offerings actually in the group).

    In situations like this, which is definitive?

    Second, what I think is my more conceptual misunderstanding, is the purpose of "bundledProductOffering" - which features in many places, but is left empty in all the JSON examples. 

    I assume the 'top level' bundledProductOffering is for when the offering is an older (pre v5) style bundle whereby the ProductOffering consists of multiple things stuck together. This is of less interest to implement for us as most 'bundles' will have some degree of flex.

    Where I get completely lost is the attribute bundledProductOffering within bundledGroupProductOffering - is there a documented use cases envisaged for this, or is it just residue from subclassing? 

    What does it mean to populate bundledGroupProductOffering.bundledProductOffering and not just bundledProductOffering directly? Have others used this for a specific case?

    The description "Child offerings, from which instances can be created as direct or hierarchically indirect children of the parent offering." is not leaving me any wiser.



    ------------------------------
    Andrew Torrance
    Cerillion Technologies Limited
    ------------------------------


  • 2.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 20, 2023 11:06

    Hi Andrew,

    let me try to explain:

    You are right, the JSON example is incorrect, the bundledGroupProductOfferingOption is not directly an attribute of the ProductOffering; as in the OAS file and the diagram, the ProductOffering has an array of BundledGroupProductOfferings. Such a Group is a collection of BundledProductOfferings, and it can have a Option that defines how many instances of the BundledProdictOfferings you may choose in total. On the individual BundledProductOfferings contained in the group, you can also have an Option that defines how many instances you can have from that offering. And to make it even more flexible, you can have a tree structure of Groups, with Options on all levels, so that you can build very complex options for selection.

    Putting the "Routers" and "Gifts" in the same Group as in your example would mean that the customer can choose between them, and get exactly one Router and optionally (up to) one Gift; but for that you would not need the Group, just attach the BundledProductOffering directly to the Top-Level productOffering, with corresponding BundledProductOfferingOptions. But you if want to let your customer choose between two different types of Gifts, and he can have zero to two in total, but only one of Type A and up to two of Type B, you can express that by setting up:

    ProductOffering: Consumer Broadband (isBundle=true)
         bundledProductOffering [  1: { name=Router, bundledProductOfferingOption { numberRelOfferLowerLimit=1, numberRelOfferUpperLimit=1 }  ]  // you get exactly 1 Router
         bundledGroupProductOffering [   // you can choose ...
         1: {
                 name=Gifts,
                 bundledGroupProductOfferingOption { numberRelOfferLowerLimit=0, numberRelOfferUpperLimit=2 },   // between 0 and 2 in total
                 bundledProductOffering [
                     { name=GiftTypeA, bundledProductOfferingOption { numberRelOfferLowerLimit=0, numberRelOfferUpperLimit=1 },  // one may be of type A
                     { name=GiftTypeB, bundledProductOfferingOption { numberRelOfferLowerLimit=0, numberRelOfferUpperLimit=2 },  // up to 2 may be of type B
                ]
         ]

    And yes, also having an array of BundledProductOfferings is for backward compatibility, and can still be used for the simpler cases where you do not need the complexity of the Group.

    Does this make sense to you?



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------



  • 3.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 20, 2023 11:44

    Lutz, thank you for confirming

    I think I follow this example so long as Router, GiftTypeA and GiftTypeB represent actual gifts Product Offerings rather than another collection of things (so if there were up to 10 different prizes available, this would be an array of length 10)

    e.g. If there were 2 models of Router and the customer had to make a choice, that would be within a bundledGroupProductOffering , right?

    (If the Router was something the customer didn't have an active say in at all, i suppose it wouldn't be a Product at all but some linked Resource)

    So in summary

    bundledProductOffering = array of ProductOffering that are always included

    bundledProductOffering[0] = the first Product that's bundled (i.e. customer forced to have it)

    bundledGroupProductOffering = array of groups

    bundledGroupProductOffering[0].bundledGroupProductOfferingOption = Definition of how many things from the group I'm allowed

    bundledGroupProductOffering[0].bundledProductOffering[0] = Definition of how many instances of that thing I'm allowed within the group (for optional services rather than physical gifts this will usually be 0/1 as it only makes sense to have HBO or Voicemail once per bundle)

    .. and a mandatory item could be represented inside bundledProductOffering[] or inside bundledGroupProductOffering[x].bundledProductOffering[y] with LowerLimit=1.

    Thanks again!



    ------------------------------
    Andrew Torrance
    Cerillion Technologies Limited
    ------------------------------



  • 4.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 23, 2023 12:02
    Edited by Matthieu Hattab Oct 24, 2023 08:34

    @Andrew Torrance

    You wrote:

    bundledProductOffering = array of ProductOffering that are always included

    bundledProductOffering[0] = the first Product that's bundled (i.e. customer forced to have it)

    As far as I understand English (I'm not a native speaker), there is no difference between these phrases:

    • "always included"
    • "first product" / "forced to have it"

    A bundle PO can have manybundledProductOffering but each bundledProductOfferingrepresents a single product offering (PO)available in the bundle PO.

    The only thing you can do is to define how many instances of a bundled PO can be procured in the bundle. This is achieved using these attributes controlling the cardinality of bundled PO:

    • numberRelOfferLowerLimit
    • numberRelOfferUpperLimit

    Do you see another meaning or do you see another functionality?

    @Lutz Bettge

    you've created the new functionality of BGPO, does this make sense:

    business wants this:

    And this is my current understanding on how it is modelled in V5:

    is this correct?



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

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



  • 5.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 23, 2023 13:04

    @Matthieu Hattab

    Thanks for your comments and the diagram - I agree something that takes a real business offer and represents how that turns into the real objects would be invaluable.

    I think you may have misread part of my remarks. In my summary I am referring to elements as they would appear in the finished JSON. I believe you are referring to class names (but changing the case). Just talking about the classes introduces ambiguity as I am asking about different uses of the same class.

    The top level element bundledProductOffering is an array. If it is supposed to be a single item, there is a fairly important error with the OAS spec!

    The elements within that array are objects of class BundledProductOffering. I think this is what you're referring to when you say bundledProductOffering(sic) is a single offer. The case unfortunately matters. 

    As far as I know, there is no concept of "first product", "always included" and "forced to have it"

    In my comment  bundledProductOffering[0] just means the first element of that array (which is an object of type BundledProductOffering). I was appealing to JSONPath, but forgot to prefix everything with '$.'. I agree the ordering of this is arbitrary, I just wanted a way to be extra-clear I was talking about an element of the array and not the whole array.

    "Always Included" or less formally "forced to have it" would be an item where Lower Limit is greater than zero. 

    I agree that bundledProductOffering[x].bundledProductOfferingOption.numberRelOfferLowerLimit (and UpperLimit)  could be used to express selection rules providing they relate to cardinalities of the individual offers only and there is no grouping.

    For most Telecoms-adjacent Services most of the time that's going to be lower=upper=1 , or lower=0&upper=1. 

    The Groups are what provides the true selection capability, especially if the thing you're trying to model is picking a bunch of things for a fixed price (e.g. select 10 basic TV channels and 3 premium ones; or select exactly 1 router from a choice of models). 

    I note your queries about the diagram are addressed to @Lutz Bettge - I'll add my €0.02.

    The lines on the diagram appear to be the correct ERD but as a representation of a concrete example, seeing lines from the TV Box to both the top-level bundle and the Group is confusing.

    In the JSON representation (going from Lutz's earlier correction to my example) , I think in this case the TV boxes would be within a bundledGroupProductOffering only (whereas the 5G Gateway would be at the top-level bundledProductOffering) - so it would be helpful for diagram to make this obvious. As seeing the generic 'possible' relations in the same arrow style as the concrete relations in this case makes it harder to follow for those of us who don't already have the correct answer.

    This is especially important when the same classes are being re-used.

    FInally, Thank you for highlighting numberRelOfferDefault - I had missed that when going through!

    Thanks

    Andrew



    ------------------------------
    Andrew Torrance
    Cerillion Technologies Limited
    ------------------------------



  • 6.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 24, 2023 08:30

    Hi Andrew,
    I quoted Lutz Bettge because he participated to the elaboration of bundledGroup functionality and hopefully can help.

    The lines on the diagram appear to be the correct ERD but as a representation of a concrete example, seeing lines from the TV Box to both the top-level bundle and the Group is confusing.

    You are probably right. The relationships with the bundledGroupProductoffering (BGPO) should be enough. I updated the diagram. 

    @Jonathan Goldberg could confirm this.

    The Groups are what provides the true selection capability, especially if the thing you're trying to model is picking a bunch of things for a fixed price (e.g. select 10 basic TV channels and 3 premium ones; or select exactly 1 router from a choice of models). 

    I'll send you a private message on the topic of pricing in bundled group.



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

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



  • 7.  RE: TMF620 v5 - BundledProductOffering v BundledGroupProductOffering

    TM Forum Member
    Posted Oct 24, 2023 10:09

    @Matthieu: Sorry for the late response; yes, this is exactly how it is meant to be used!



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------