Open APIs

Expand all | Collapse all

TMF620 R21 Representation of Bundles and their contents

  • 1.  TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Aug 24, 2021 07:57
    Edited by Andrew Torrance Aug 24, 2021 10:07
    A possibly simple question about TMF620 and representing bundles.

    Earlier versions of TMF620 hinted at using Relationships to indicate that products belong to bundles.

    I'm coming up to speed with the R21 which includes the concept of "Bundled Product Offering". It is implied this is sufficient to express a bundle but I can't find enough fields to represent what I need without adding other relationships.

    Unfortunately, the examples TMF620 leave bundledProductOffering is left blank for all resources.

    I present a simplified example, rather than risk identifying a CSP I have used a different industry example that hopefully most will be familiar with!

    { "id": 1 , "name": "Happy Meal", "isBundle": true, "isSellable": true, "productOfferingPrice": { <Meal Price> } }
    { "id": 2 , "name": "Burger", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Burger Price> } }
    { "id": 3 , "name": "Small Fries", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Fries Price> } }
    { "id": 4 , "name": "Small Cola", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Drink Price> } }
    { "id": 5 , "name": "Small Lemonade", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Drink Price> } }
    { "id": 6 , "name": "Ronald Toy", "isBundle": false , "isSellable": false }
    { "id": 7 , "name": "McCheese Toy", "isBundle": false, "isSellable": false }

    I want to indicate that the Happy Meal consists of a Hamburger, Small Fries, Cola or Lemonade, and one of the toys (which cannot be bought alone, unlike everything else)

    Fundamentally there are two things that need to be stated somewhere
    * Definition of the Bundle (that it consists of burger, fries, one "drink", one "toy")
    * Definition that a product satisfies a bundle requirement in some way (i.e. that Hamburger is in the bundle, or that Cola/Lemonade are "drinks")

    What I'm not sure about is which one of the two items "BundledProductOffering" is intended to cover, and where to put the other

    The attribute productOffering.BundledProductOffering is described as follows, the sentences aren't very clear

    "BundledProductOffering" A list of bundled product offerings (BundledProductOffering [*]). A type of ProductOffering that belongs to a grouping of ProductOfferings made available tothe market. It inherits of all attributes of ProductOffering

    I'm not sure how to interpret the statement "It inherits of all attributes of ProductOffering" - if this is a statement about the physical JSON objects, it doesn't appear to be reflected in the Swagger.  Or is this more meaning an implicit reference.



    If it's the first, is the intended representation something like this?
    {
    "id": 1 , "name": "Happy Meal", "isBundle": true, "isSellable": true, "productOfferingPrice": { <Meal Price> },
    "bundledProductOffering": [
    {
    "id": ??, "name": "Hamburger", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1},
    "id": ??, "name": "Fries", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1},
    "id": ??, "name": "Drink??", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}
    ...
    }
    ]
    }

    But how does a consumer 'know' that the Hamburger BundledProductOffering is anything to do the the Hamburger ProductOffering?
    If the Bundles can only name individual Product Offerings that seems restrictive and makes the quantities in bundledProductOfferingOption feel a bit redundant (CSP offers are as likely to be "pick 3 add-ons from this set", as "pick 3 of the same add-on")


    if the intention is to put bundledProductOffering against the individual Drinks to link them to the type, then the bundledProductOfferingOption doesnt seem to be in the right place, as the quantity allowed is a function of the bundle the productOffering is in, not just the productOffering itself.

    e.g. a "Family meal" could allow 4 burgers, 4 drinks, 4 drinks to be selected and should be able to reuse the same ProductOffering/Spec.


    Finally, is it assumed a Bundle is sold for a single price, or is it possible to state a ProductOfferingPrice that is specific to a product when sold inside a bundle. I am thinking of cases where numberRelOfferLowerLimit != numberRelOfferUpperLimit, you may want to charge the customer depending on number of choices (In fast food case, maybe this is the "add wings for $1", in TV case maybe it's "add International Calling for $5 when taking the Triple Play".

    I suspect I'm missing something obvious in both cases, any guidance, or correction to my example much appreciated.







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


  • 2.  RE: TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Aug 24, 2021 12:32
    Hi Andrew
    I'll try to address your points briefly, it's possible that the best way to handle this would be with a voice call.
    • The entity BundledProductOffering in TMF620 is a sort of enhanced ProductOfferingRef. The ID, href, and name are of course the attributes of the corresponding ProductOffering that is being referred to. But the critical part is the embedded Option sub-entity, where the marketeer can set the minimum and maximum for the Product that will be instantiated at ordering time from the referred product offering.
    • Product Offerings are referred to, not embedded, so that the same "simple" PO can be re-used in multiple bundles
    • The price of the bundle will typically override any prices set in the referred offerings (that's the point of the bundle), but of course the specific implementation of the API needs to set expectations so that catalog users will know what the behavior is. It may also depend on the capability of the billing/charging system that will eventually receive the ProductPrice instantiated from the offering price.
    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.
    ------------------------------



  • 3.  RE: TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Sep 01, 2021 13:17
    Thanks Jonathan,

    I would be delighted to take a call - will reach out once you're back from vacation.

    So taking your advice above the representation of the various resources may be like this, for one particular bundle permutation

    { "id": 1 , "name": "Happy Meal", "isBundle": true, "isSellable": true, "productOfferingPrice": { <Meal Price> },
    "bundledProductOffering": [
    {"id": 2, "name": "Burger", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 3, "name": "Small Fries", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 4, "name": "Small Cola", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 7, "name": "McCheese Toy", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}}
    ]
    }

    { "id": 2 , "name": "Burger", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Burger Price> } }

    { "id": 3 , "name": "Small Fries", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Fries Price> } }

    { "id": 4 , "name": "Small Cola", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Drink Price> } }

    { "id": 5 , "name": "Small Lemonade", "isBundle": false, "isSellable": true, "productOfferingPrice": { <Drink Price> } }

    { "id": 6 , "name": "Ronald Toy", "isBundle": false , "isSellable": false }

    { "id": 7 , "name": "McCheese Toy", "isBundle": false, "isSellable": false }



    To the wider community:

    Is there any functionality within TMF620 to define a more flexible 'Bundle'-like entity, or have you used some other entity for this?

    In my example above, it'd be taking the different toys.

    Coming back to the CSP world, suppose a Cable TV provider lets users choose 8 TV channels from a list of 50 for a flat price.
    Creating every feasible combination as a separate Bundle entity is not really feasible as there are 536,878,650 possible choices. 

    Ideally we would model this as a  bundle, with data inside the bundle to say it is a bundle of any 8 of these 50 choices.
    I can see we can include all 50 channels, say they're not included by default, but how to say "you can only have 8 of these" - would we need to extend the class ourselves?

    I suppose if you made the Product Offering more generic e.g. "TV Channel" it could work, but I've seen requirements for very varied 'pick and mix' type of bundles such that squashing all the things you cold pick into 1 offering would render it meaningless.


    Representing 'price when inside the bundle'

    While I understand  the 'bundle price' will often override individual prices, It is not uncommon for a CSP to say "if you buy the triple play bundle then XXX add-on is cheaper than if you buy it alone".

    For example, if an element within bundle has numberRelOfferDefault=0 , numberRelOfferUpperLimit=5 , then it's reasonable to expect the customer might be charged differently if they have 0 of them or if they have 5. Otherwise there isn't much incentive to configure Lower != Upper.

    It is also very common, for tax or revenue reasons, to have to apportion 'bundle price' across many services. e.g. a CSP may market a "TV and Broadband deal" for $100, but for revenue/tax purposes they are really selling a $75 package and a $25 broadband package.

    Is there an accepted way to state - this ProductOffering has many ProductOfferingPrices and here is the applicability of each? Apologies if I have missed something obvious but the example payloads in the spec are very limited in how they present this.

    I see "Bundled Product Offering Price" but as far as I can tell that is for bundling prices together rather than saying the price of a product within a bundle.





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



  • 4.  RE: TMF620 R21 Representation of Bundles and their contents

    Posted Sep 02, 2021 02:30
    Hi Andrew,

    good points. We were faced with both challenges you mention some years ago.

    First, how to define a group of related offerings, from which a customer can choose between min and max offerings (e.g. 0 to 1). A real-life use-case would be: with a mobile tariff plan you can choose at most 1 subsidized handset from a set of hundreds of different models. We introduced a concept called "relationship group" with min & max characteristics. This is an optional property of product relationships and offering relationships. It's an extension of the core SID model in our implementation.

    The second use-case - how to charge differently for a various number of enabled related offerings - can be solved with several productOfferingPrices, each has a different constraint and/or pricing logic algorithm. E.g. constraint for 1 add-on, 2 add-ons etc. The counting logic needs to be implemented in the billing system. This way, we implemented charging for TV add-ons, where a customer was able to choose between 0 and 5 add-ons on IPTV and pricing wasn't linear, but each additional add-on had a lower per unit price (e.g. 1 add-on 1$, 2 add-ons 1.50$, 3 add-ons 1.67$ etc.).


    ------------------------------
    Bostjan Keber
    Marand d.o.o.
    ------------------------------



  • 5.  RE: TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Sep 06, 2021 10:25
    Hi Bostjan,

    First, how to define a group of related offerings

    Is your concept of "relationship group" the same as BundledProdOfferOption?
    But you mentioned "min & max characteristics"
    I see min and max qty when used with BundledProdOfferOption, but I haven't experienced "min and max characteristics" yet.

    In
    GB922, there is example for an offer when customer must choose 1 handset from a list of 5 phones. Each phone is modelled as a simple productoffering.
    the example looks very similar to your requirement.

    The second use-case
    For the price of TV add-ons, your example illustrates volume discount (either tiered or simple). This is vanilla SID. You can use a PolicySet to define volume discount. they have slightly different name, though:
    • quantity based discounts
    • quantity-tier based discounts
    I was also suggested to use Discount Price Alteration but it didn't feel intuitive and I didn't explore it further.

    my 2 cents,

    Matthieu

    ------------------------------
    Matthieu Hattab
    Altibox AS
    ------------------------------



  • 6.  RE: TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Sep 06, 2021 13:49
    Hi Matthieu,

    Thanks for pitching in.

    I think the difference is that, as it appears to be defined in the Open API, BundledProdOfferOption only lets you state the quantity of an individual ProductOffering, which I have read to mean a single actual product (1 toy, 1 handset etc), so you can represent that the user can have 0 or 1 of each phone handset, but not that they can only pick 1 in total (in the handset case, because of subsidy)

    If GB922 defines it in some other way, that's great for users of GB922/SID, but less so if our partners are relying on TMF620 on its own. If you have an example representation that sticks within TMF620, please do share.

    On your second point, could you expand a little? Are you saying that this object 'PolicySet' exists in one of the OpenAPI, or suggesting that something from SID that might be incorporated into OpenAPI in a future release?  Treating it as a discount can work in some straightforward cases, but that makes assumptions about the base cost (Handsets, TV channels, even soda & milkshakes, can have all different prices individually, but are usually 'banded' for bundle purposes).


    I had wondered if the right thing might be to somehow let BundledProductOffering to point at a group of offerings rather than just one - which was the reason for my initial question about whether it was pointing at exactly one by virtue of ID sharing.

    Perhaps this could be done by having a kind of 'abstract' product offering object, and representing elsewhere that this offering could be matched by various others

    (Feel free to replace "toy" with "handset" in the below)

    { "id": 1 , "name": "Happy Meal", "isBundle": true, "isSellable": true, "productOfferingPrice": { <Meal Price> },
    "bundledProductOffering": [
    {"id": 2, "name": "Burger", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 3, "name": "Small Fries", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 4, "name": "Small Cola", bundledProductOfferingOption: {"numberRelOfferDefault": 1, "numberRelOfferLowerLimit": 1, "numberRelOfferUpperLimit": 1}},
    {"id": 99, "name": "Any Toy", bundledProductOfferingOption: {"numberRelOfferDefault": 0, "numberRelOfferLowerLimit": 0, "numberRelOfferUpperLimit": 1}}
    ]
    }

    {
    "id": 99 , "name": "Any Toy", "isBundle": false , "isSellable": false
    // Possibly include the relations from 99 to 6+7 here
    }

    { "id": 6 , "name": "Ronald Toy", "isBundle": false , "isSellable": false }
    { "id": 7 , "name": "McCheese Toy", "isBundle": false, "isSellable": false }


    I'm not convinced by my own suggestion here, because
    * it requires multiple queries for a client to be able to discern what should be quite a simple fact, which is what can the bundle be made out of, and
    * a client that hasn't had the same brainwave as me might not understand why the Products in the Inventory don't appear to match the Catalogue.
    * it doesn't obviously and neatly extend to being able to say "Toy/Handset A is included by default but you can have Handset B instead", which is the next thing my customers will look for! (well i suppose you could have a property on #99 saying its default representation is #6, so then it just comes down to where you like making your extensions, and I felt this was a common enough use case it might have an out-of-the-box answer!)




    ​​

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



  • 7.  RE: TMF620 R21 Representation of Bundles and their contents

    TM Forum Member
    Posted Sep 06, 2021 14:48
    Edited by Matthieu Hattab Sep 06, 2021 15:58
    Regarding pricing:
    The resource model doesn't include PolicySet. But if a system (CPQ...) need pricing rules to calculate the correct price, you'd have to extend the api to get these rules from the Product Catalogue
Management.

    Regarding "Product grouping".
    UC003 from IG12128 could shed some light. It shows the customer order using APIs, especially TMF620.

    Below picture shows the "Global Catalogue View" of a broadband bundleproductoffering, including a composite (Box) of 2 atomic components (box 1, box 2). Kind of how you want to present your mobile phones.
    UC003 implicitly suggests that TMF620 fully support this scenario. therefore the API should get the structure (BundlePO/Composite PO Spec/Atomic PO Spec)
    In TMF620, the Product Specification resource model also show these relationships.
    We just need to find out what sub class the product specification is made of: Atomic or Composite