Open APIs

Expand all | Collapse all

Query on semantics of TMF679 Product Offering Qualification Management

  • 1.  Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted Feb 24, 2021 12:16
    Hello,

    I would be grateful if someone could pass their eye over this and (hopefully) concur.

    A ProductOfferingQualificationItem is a request to do something with a ProductOffering.
    The productOffering, product or category field identifies the PO either exactly or in the latter two cases by defining constraints/grouping.
    The action (of type ProductActionType) defines the action we wish to take.
    "add" would mean we want to add/create on of these Product Offerings.
    "modify" would mean we wish to make some change to an existing product
    "delete" to delete/cease/end service.
    If we sent a ProductOfferingQualificationItem[PO1, add] and the system does not allow the PO to be added then the qualificationItemResult would be unqualified.

    If, in the above scenario, the system wanted to suggest the client use an existing product (e.g. in some modify scenario) how would the API express that?
    I assume additional characteristics or relations imply something common between the add request and the existing product.
    Would it be a ProductOfferingQualificationItem like this?
    {"productOffering" : "PO1"
     "action" : "add"
     "qualificationItemResult" : "unqualified" <-- which means "you can't have this"
     "eligibilityUnavailableReason " : "some meaningful code for this scenario"
     "alternateProductOfferingProposal" : [{"alternateProduct" : {details of the existing product go here}}] <-- which means "have a look at this"
    I.e. we say "no you can't add, but look at this existing product that can meets your needs in some way.
    I assume the exact interpretation would rely on eligibilityUnavailableReason codes specific to the application.

    If, in our scenario, we wish to say "you can add the PO but you must delete this existing product" Might we do this?
    This might be straying beyond what the authors envisaged - but is it at least consistent with the definitions?
    {"productOffering" : "PO1"
     "action" : "add"
     "qualificationItemResult" : "qualified"
     "qualificationItemRelationship" : [{some relation to the item below}]}
    {"productOffering" : "PO2"  <-- this item was not in the request but the system has included it in the response to indicate the thing that must be deleted.
     "product" : {"id" : "some identifier for existing product"}
     "action" : "delete"
     "qualificationItemResult" : "qualified" }

    Many thanks for anyone who got this far! Alasdair


    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------


  • 2.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted Feb 25, 2021 02:17
    Hello Alasdair,

    First we have  the plan to align ProductOfferingQualification with ServiceQualification API Pattern in order to clarify. We'll have 2 resources: CheckProductOfferingQualification  which globally w'll have same structure than today ProductOfferingQualification  and must be use for precise request and get a response for the eligibility (with alternate). We'll introduce a QueryProductOfferingQualification  resource - this one fetaure search criteria abd the response will list all available/eligible PO matching your criteria.

    Now to your questions : For me right now it is impossible in this API to go further than providing alternate. You can query for a new product offering (or a set of them) and get result & alternate, you can also pass existing product(s) and check configuration change, you can mix both (I want this offer in this commercial bundling thant I own).

    I'm wondering if your requirement will no be close to some kind of 'Configuration API' that manage a whole configuration and assess all rules (even pro actively) to indicate all possibilities. It could be done from scratch (new API) or an evolution of today POQ (as you suggested) but we did not put some thought onthis within the API group already.

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 3.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted Feb 25, 2021 04:39
    Thanks for the reply Ludovic.

    I will have a look at the Service Qualification to see where things are going.

    I think the sticking point in the current API is the inclusion of a mandatory single action. I think including a mandatory action is mixing concerns.  When the we specify productOffering, category or partial product details we are specifying details of the to-be state of the customer's inventory. When the client specifies the action we are dealing with _how_ to get there. We cannot say "we want to end up in some state involving PO1", we must say "we want to add PO1" or "we want to modify PO1". We are saying the client must interrogate the customer inventory first and part of the qualification logic is client side (which I would like to avoid).

    I suggest making the action optional in the request, mandatory in the response. That would allow a client to say "we want to end up in some state involving PO1" and the service can say "yes" to this and can respond populating the appropriate action depending on the customer's estate.

    E.g. for a qualification request for PO1 and product characteristic foo=bar
    and dealing with a product that is handled in a singleton manner - maybe one per customer, maybe we are specifying address details too etc etc
    our request would be PO1[product/foo=bar] (no action specified)
    if the customer has nothing to start our response would be: PO1[action=add, product/foo=bar]
    if the customer has PO1 and foo=bar our response would be : PO1[action=no_change, product/foo=bar,id=1], or unqualified with a reason of "already got this"
    if the customer has PO1 and foo=xxx our response would be : PO1[action=modify, product/foo=bar,id=1]   i.e. you must modify to get there
    If the customer cannot have a PO1 then we would return unqualified
    You can also return alternatives e.g. you might return two items PO1[action=add, product/foo=bar] and PO1[action=modify, product/foo=bar,id=1] if there is a choice of approach
    In all cases the response might return other data the implementation deems appropriate

    Alasdair

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 4.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted Feb 25, 2021 07:40
    ... and having just read the Service Qualification spec I see there is no action field in the XxxServiceQualificationItem.
    If Service Qualification doesn't use an action can be do away/make option for Product Offering Qualification?

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 5.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted May 13, 2021 12:13
    Picking up this thread again. I think my point was obscured by too much wordy explanation. I will try and be more precise...

    The a client of Product Qualification cannot simple ask "can my customer have YXZ (with some constraints)", the client is forced to say "can my customer add XYZ" or "can my customer update XYZ", in effect the client must inspect the customer's estate and work up the order actions for a product. The schema forces this because action is mandatory and there is no don't care term value - the client must decide if the scenario is an add|update|noChange|delete. There are cases where this is overly prescrptive.

    I notice the Service Qualification API does not include an action on Service Qualification Item and so can avoid this problem. As Product Qualification will be aligned with Service Qualification can I assume that future versions of the Product Qualification API will remove the action field or at least make it optional?

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 6.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted May 17, 2021 10:51
    Hello Alasdair,

    As previously stated we have the objective to align future Product Offering Qualification version with Service Qualification. Doing that we'll have 2 separate resources.

    I'm aligned with your view with QueryProductOfferingQualification - It should not require action as the objective is to get a list of product offering available (and aligned with criteria passed in the request).

    I'm a bit more concerned for CheckProductOfferingQualification because here we would like to manage more advanced UC  where we want to check if we can add a product in relationship with existing, change an existing product (changing relationship, characteristic value) or event terminate a product. The action field is required for this, or, at least explicit the requester-intend. (If a product.id is present, is it a product to change or to terminate or only pass as reference ? The action will provide the answer).

    In your example - if I already own PO1 with foo=xxx - and request CheckPOQ for PO1 with foo=bar how do you understand if I want to change existing or a new instance of PO1? You need to explicitly pass the action and pass the product.id for change (or the server has to understand this is a change because there is a product.id ....which is not trivial) - and in both case need to look on your inventory.

    For me, action is missing in CheckServiceQualification and should be re-introduced, but this is a good topic to be discussed in API team.

    Thanks,
    Ludovic


    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 7.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted May 17, 2021 11:37
    Ludovic,

    Thanks for going back to this. I think we are on the same page:

    I.e.
    The client should not have to specify action on QueryXXXXQualification as query is, by definition, a search for possible solutions.
    QueryXXXXQualification asks "What can I have?" without necessarily knowing what is in the current estate.
    To be clear - I think there are cases where the client might wish to specify action, it should be optional, not removed.

    From the ServiceQualification docs CheckXXXXQualification is not a search operation but the validation of a specific change against an extant configuration.
    CheckXXXXQualification asks "Can I do this?"
    Which implies the client has knowledge of the current state of Products or Services and plans a specific update.
    So we are dealing with specific updates and action is needed otherwise we cannot be precise about the change - so yes, I agree action is needed here.

    To answer your question - the scenarios I am dealing with really fit the the Query mode. I would see them playing out like this (assuming a singleton PO).
    Client performs Query[PO1, foo=bar]
    and could get back QueryResponse[qualificationResult=Qualified, PO1, foo=bar, action=add] if they don't have the PO1 already
    or they might get back QueryResponse[qualificationResult=Qualified, PO1, foo=bar, action=update, product/id=1234] if they have PO1 already and should update it
    (obviously this is specific to the rules of a given product)
    I.e. the Query response would fill in the action and maybe some other data so the client knows what to do.

    If the rule was that you order the same product many times (not updating) they might always get back
    QueryResponse[qualificationResult=Qualified, PO1, foo=bar, action=add]
    every time.

    If the rule was that they could either add to update I assume they could get back
    Item[qualificationResult=Qualified, PO1, foo=bar, action=add] to add a new PO
    Item[qualificationResult=Qualified, PO1, foo=bar, action=update, product/id=1234] to update the existing
    (in reality we would probably include more data to nail down exactly what to do).

    But all of these are really Query use cases, for Check it makes sense that action is mandatory.

    Another thing that I noticed was ProductQualificationItems do not have children (i.e. embedded/nested ProductQualificationItems) whereas TMF622 ProductOrderItems can be nested. I think this is an oversight? I.e. if we have a BundledProductOffering or CompositeProduct with related POs, or want to qualify based on a CompositeProduct don't we need the nested structure?

    Regards, Alasdair

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 8.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted May 18, 2021 03:20
    Hello Alasdair,

    Thanks for your reply.
    It will bring some work to the team ;)
    • Reintroducing the action for CheckServiceQualification (I will raise a Jira)
    • Keeping if for CheckPOQ
    • Assessing to add it as optional in QueryPOQ (Probably need also a Jira)

    For the embedded/nested this is a fair question. It should be only on check pattern I guess. Probably need a Jira to get the team advice: in one hand the API is already a complex one with the alternate pattern but in the other hand as you mentioned for consistency with other product API it could make sense.

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 9.  RE: Query on semantics of TMF679 Product Offering Qualification Management

    TM Forum Member
    Posted May 18, 2021 04:36
    Not too much work I hope!

    NB: I think you need the embedded Item on both Query and Check.
    E.g. what are my options for PO1 with Gold setting?
    response:
    * you can add a PO1 with child (add) Gold
    * you can update this existing PO1 by adding a Gold child (maybe it's Silver today)
    same general arguments as above. (this is actually a real scenario within BT, obviously I am changing names and keeping it vague for commercial reasons).

    The basic argument is if the query is searching by pattern matching on partial data in a TMF679 Query payload then it should be able to express anything (in the product domain) that TMF622 can express. Otherwise you don't have the scope to search over the whole space of possibilities.

    Alasdair

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------