Open APIs

Expand all | Collapse all

The TMF 637 status is mandatory in the POST?

  • 1.  The TMF 637 status is mandatory in the POST?

    Posted May 07, 2021 10:04
    Hello,


    I have been going through TMF 637 documentations and playing with Postman collections for POST /product. I noticed "status" is marked as mandatory in swagger and sample Post request are not working unless we specify "status" for create product. But at the same time "status" field is non mandatory in conformance document TMF637B.

    Can anyone clarify if this is mandatory or not?If it is mandatory, which seems odd, how will a client determine "status" at the time of product creation in inventory?

    thanks
    alexsunny

    ------------------------------
    alex sunny
    TO BE VERIFIED
    ------------------------------


  • 2.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 10, 2021 03:36
    Hello Alex,

    First, thanks for the catch - we need to fix this inconsistency in the documentation.

    For me, this product state should me mandatory in the POST request. A product in the inventory must always have a state. A product creation in the inventory is not a delivery process by itself, but it reflects a process done in order delivery (nominal case) or an inventory correction by an administrator (exception case). In both cases POST submitter must specify the state.

    I took a look on Service Inventory API for consistency: state is mandatory in the POST.

    Hope it helps,
    Ludovic

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



  • 3.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 11, 2021 03:38
    HI Alex, Ludovic,

    I tend to disagree with the statement that product.status should be mandatory for a POST. In principle a POST will use the input values and default values to create a product in inventory. An implementation should therefore have sensible default values instead of making all fields mandatory. Some values could even be enforced by business logic.

    Example default values:

    product.status='created'; /* forcing the start of lifecycle; should only be overwritten by migration processes */
    product.orderDate=now() /* forcing the orderDate to be the date of the POST: should only be overwritten by migration processes */
    product.isBundle=false /* sensible default value; if it is a bundle POST should override default */
    product.isCustomerVisible=true /* sensible default value; if it is to be hidden on invoices, POST should override default */
    product.startDate= null /* set to now() when status is changed to 'active' */
    product.terminationDate= null /* set to now() when status is changed to 'terminated' */

    Regards

    ------------------------------
    Koen Peeters
    Ciminko Luxembourg
    ------------------------------



  • 4.  RE: The TMF 637 status is mandatory in the POST?

    Posted May 12, 2021 08:03
    Edited by Tomáš Hajný May 13, 2021 04:47
    Hello,
    I tend to agree with Ludovic that product creation in inventory is not the delivery process by itself. I fully agree that certain default values should be defined as part of business logic, but I believe that busines logic related to e.g. product.orderDate, product.startDate, etc., belongs primarily to the Order Management rather than Product Inventory Management. On the other hand, business logic within Product Inventory Management should perform consistency checks so that invalid combinations of attribute values are not accepted.
    Imagine the case when the product inventory update is delayed for some reason - should the default value for product.terminationDate correspond to the moment when update of the inventory was performed, or to the moment when the customer lost access to the product (if this isn't the same time)?

    Just my point of view

    Tomas Hajny

    ------------------------------
    Tomáš Hajný
    ČD - Telematika
    ------------------------------



  • 5.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 12, 2021 09:55
    The representation of state or status reminds me of what I believe to be a topic that may deserve a new pattern belonging to the design guidelines.

    State and status imply a state machine. The states and transitions of the state machine belong to the semantics of the resource and therefore should be implemented by the owning component, which is the master of that resource. If the client is responsible for choosing the target state value, when calling POST, PUT, or PATCH on the resource, the client must know the resource's current state, and the client must know the state machine to know the valid transitions from the current state.

    Instead, I believe the pattern should be the following. The state should be a read-only attribute, and a task resource should be used to transition the state. The target state should be determined internally by the component based on the transition.

    I believe the current pattern is awkward in the current Open APIs.


    ------------------------------
    Ben Eng
    Oracle Corporation
    ------------------------------



  • 6.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 13, 2021 08:39
    I agree OpenAPI should consider implementing this as a pattern.

    State transitions should indeed be internal to the application managing the resource.
    It is therefore a good idea to encapsulate state transitions in a task.
    The task can then also make sure other conditions for the state transition to be fulfilled.

    For TMF673 that would mean adding tasks like below:

    • POST /product/{id}/initiateActivation
      • sets status to 'pendingActive'
    • POST /product/{id}/activate
      • sets status to 'active'
      • sets startDate to now() or a date in the past provided in the payload
      • realisingService or realisingResource must either exist or be provided in payload
    • POST /product/{id}/suspend
      • sets status to 'suspended'
    • POST /product/{id}/resume
      • sets status to 'active'
    • POST /product/{id}/cancel
      • set status to 'canceled'
      • sets terminationDate to now() or a date in the past provided in the payload
    • POST /product/{id}/abort
      • set status to 'aborted'
      • sets terminationDate to now() or a date in the past provided in the payload
    • POST /product/{id}/iniateTermination
      • set status to 'pendingTerminate'
    • POST /product/{id}/terminate
      • set status to 'terminated'
      • sets terminationDate to now() or a date in the past provided in the payload

    Encapsulating these transitions in task has the added advantage that TM-Forum can be much clearer in the intended impact of each transition.

    Regards

    ------------------------------
    Koen Peeters
    Ciminko Luxembourg
    ------------------------------



  • 7.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 13, 2021 09:11
    Edited by Ben Eng May 13, 2021 09:12
    Koen,

    Your examples were obviously for TMF637 (Product Inventory), but your proposal matches exactly what I was thinking. Thank you for contributing examples to help clarify the topic.


    ------------------------------
    Ben Eng
    Oracle Corporation
    ------------------------------



  • 8.  RE: The TMF 637 status is mandatory in the POST?

    TM Forum Member
    Posted May 14, 2021 22:49
    On May 11, 2021 18:28 @Ben Eng wrote:
    | State and status imply a state machine. The states and transitions of the state machine belong to the semantics of the resource and therefore should be implemented by the owning component, which is the master of that resource.

    I agree that the master of the resource should be authoritative for the state. However the consumer (client) of an inventory API should be (but may not be) the master.  We have a number of API archetypes including:
    • Order Management
    • Activation and Configuration
    • Inventory Management
    The component handling Activation and Configuration would be the master of the resources.



    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------