Open APIs

Expand all | Collapse all

TMF622 - Product Ordering Management API: Product

  • 1.  TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 09, 2019 05:06
    Hi,

    I am trying to expose product ordering functionality implemented in a commerce application via TMF APIs abd for that I decided to use product ordering API.
    By reading the specifications of the API I have identified some issues that are unclear for me and I need your help to move forward with the API:
    1. 'Product sub-resource: Product reference. Configure the product relationships & characteristics (only configurable characteristics and necessary only if a non default value is selected) and/or identify the product that needs to be modified/deleted.' - I understand from here (and also by reading the specifications) that Product sub-resource should be used in case of all ordering scenarios: for ACQUISITION of a new tariff plan (such as subscribe to a new GSM plan) to provide the selected product characteristic values; for updates on an existing product it is used to provide the updates that has to take place on that product. What is unclear for me is: if you specify that Product sub-resource from here is a reference to a product then why there are differences between Product resource from this API and Product resource from TMF637 - Product Inventory Management API? Should this resource have a different name (maybe ProductOrderingRef) or is it ok to consider the Product resource from here is the same Product resource from the product inventory API? More than that it will help me to understand what were your considerations when you decided to use Product resource for providing data for a new ACQUISITION because in this case we don't have the Product yet.
    2. Inconsistencies between API definition and swagger json schema in terms of relation type between resources:
      • ProductOrder -> Channel: in the PDF specification the relation is 1 -> * but in the swagger definition relatoin is 1 -> 1
      • ProductOrder -> Note: in the PDF specification the relation is 1 -> * and in the swagger definition relatoin is 1 -> 1

    Kind regards,
    Calin Mates


    Kind regards,
    Calin Mates

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------


  • 2.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 10, 2019 11:37
    Hi Calin

    For R19, we are working on ensuring complete consistency between the specification (word/pdf) document and the swagger file, by having a single source generation for both assets. This was piloted in R18.5 for various APIs in the Service domain, and for R19 the scope includes Product and Product Order APIs.
    Specifically for both note and channel, the relationship in R19 is 0..*.

    Additionally, we introduced a new pattern for an incomplete resource, such as Product as part of a ProductOrder or Service as part of a ServiceOrder, the new resource is called BaseProductRefOrValue, and has less fields than the full Product resource, should be a strict subset.

    Adding @Ludovic Robert​, the lead for Product and Product Order APIs.

    Hope it helps.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 3.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 15, 2019 10:35
    Hi Jonathan,

    Thank you for your reply. Then I understand a different resource is going to be used in Product Ordering API, called BaseProductRefOrValue. Can I consider the list of attributes for BaseProductRefOrValue resource the same as the ones defined in this current version for Product in Product Ordering API specifications?
    Also the name of the 'product' attribute defined for ProductOrder resource should be changed as it would have a new type (BaseProductRefOrValue)?

    Thank you,
    Calin

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------



  • 4.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 19, 2019 16:12
    It would be best if @Ludovic Robert answered this, but I will give my understanding:
    • BaseProductRefOrValue is ideally a strict subset of the current Product resource . The idea was to remove attributes and relationships that are considered not relevant to a Product that is not yet in the inventory (e.g. in quote, shopping cart, order, qualification test).
    • During this refactoring, we are in general not changing attribute names. So for example the attribute for the Product in the ProductOrderItem resource remains with the name product.

    Hope it helps.​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 5.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 20, 2019 04:02
    Hello

    Agreed with @Jonathan Goldberg comment.

    The ​BaseProductRefOrValue was added to remove unuseful/confusing attribute from product when we use this later in productOrder, quote, productOfferingQualification, etc... API but the attribute name should be product because at the end of the day this product (described in the ProductOrder for exemple) will create or update a product in the inventory.

    To provide you an example @Calin Mates in the product schema you have an array to list all the product order(s) that modified this product. Our thinking was having this list in the 'product' structure used in the productOrder, quote, productOfferingQualification, etc.. API would be very confusing... that why we introduced this BaseProduct schema with only the relevant product attributes.

    Hope it helps

    Ludovic


    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 6.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 20, 2019 08:46
    Hi,

    Thank you for tour clarifications.
    I understood the reasons for which you are going to do this change. So I could consider that ProductOrder resource has the attribute product of type BaseProductRefOrValue, having the same list of attributes as the Product resource defined in ProductOrdering API, right?

    Thanks,
    Calin

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------



  • 7.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 29, 2019 08:07
    Hi,

    And also noticed that Product Ordering API swagger definition file has some concrete solution messages such as 'Orange API is over capacity, retry later !' which is not quite a generic error message and I suppose should not be there.

    Regards,
    Calin

    ------------------------------
    Calin Mates
    Aplication Architect
    IBM Corporation
    ------------------------------



  • 8.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 29, 2019 10:14
    Hi Calin,

    Yes you're right. It will be corrected with the Release 19 (coming in June)  thanks to new tooling :)

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 9.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 20, 2019 04:02
    Hi Jonathan,


    I am not convinced that creating a new object like BaseProductRefOrValue is a good idea.
    The conformance definition gives sufficient room for defining attributes that are mandatory or not for a particular use case.
    By creating a new object, the use of inheritance in an implementation is made more difficult and prone to errors.
    By removing attributes you are also restricting certain use cases that some implementers might find useful.

    I am absolutely in favour of keeping the current "product" with all attributes and just defining in the conformance model how to use it.

    Regards







  • 10.  RE: TMF622 - Product Ordering Management API: Product

    TM Forum Member
    Posted May 20, 2019 04:36
    We had considered various alternatives before reaching the current decision:
    • Do nothing and solve in documentation (which is more-or-less what @Koen Peeters has suggested)
    • Create a business-context model, whereby for each API and operation you specify explicitly which attributes are optional/mandatory/relevant, and this would presumably generate fine-grained Swagger representations for the resources in the context of each operation. This is probably the most robust option. Indeed Amdocs has done something similar in its previous generation of exposed SOAP web services, and I believe it was investigated by Josh Salomon in the days of the TMF TIP program (see also https://www.unece.org/fileadmin/DAM/cefact/codesfortrade/CCTS/CCTS-Version3.pdf). But it creates a multitude of resource variations and may have maintenance and legibility impacts
    • Create a coarse-grained separation for key resources, this is what we have decided to do in practice, in R18.5 with ServiceRestriction from Service, and in R19.0 we are continuing this approach, as described by @Ludovic Robert
    ​​​​​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------