Open APIs

 View Only
  • 1.  Questions about the best way to map a Subscription agreement/contract model

    Posted Jul 22, 2022 00:23
    Hi

    My company is currently implementing the TMForum's rest base open API's. We use the subscription agreement or contract model similar to Shopify (see this link for details). It is basically an agreement between us and our customer over a period of time for a set of recurring purchases. Initially, mapping the subscription contract model to TMF's "agreement" made sense. Now I'm struggling a bit to map this usecase;

    When a customer wishes to cancel subscription contract they need to put in a request. This is a manual process in which the request is sent to a special team for review before it is accepted or rejected. If it's accepted, then usually the customer is allowed to finish out the time remaining on the subscription contract before it is finally de-activated.

    The best mapping that I've come up with is the use of the TMF 622 - Product Ordering Management;

    POST /productOrder - with a "productOrder_create" request that contains a productOrderItem that looks something like

    "productOrderItem": [
       {
          "id": "001",
          "quantity": 1,
          "action": "cancel",
    
          ...,
          ...,
    
          "productOrderItemRelationship": [
             {
                "id": "001",
                "relationshipType": "agreement",
                ...,
                ...,
             }
          ]
       }
    ]

    The issues I'm facing are these;

    • There is a 'ProductOrder' entity but not a more generic 'Order' entity. The GB922_Customer_v21.5.pdf doc mentions that some enterprises consider an Order to be a type of Agreement with the Order formalizing the Agreement. So where is the 'Order' resource that I can use?
    • There is a generic 'OrderItem' which would be great for my purposes but there is no indication as to whether or not it's a supertype of 'ProductOrderItem' or where it's used.
    • The documentation around the 'id' of the 'OrderItem' implies a line item, and not a way to identify the actual entity I which to work on. In the case of other CRUD actions ("modify", "no-change", "delete"), would I be able to use the uuid of the entity instead of a generic sequential id?
    • In the example above I'm using the "productOrderItemRelationship" to circle back to itself, but is there another way to indicate the type of 'Order' I'm working on?
    Any help is appreciated.

    ------------------------------
    samantha holder
    Mitel Networks
    ------------------------------


  • 2.  RE: Questions about the best way to map a Subscription agreement/contract model

    TM Forum Member
    Posted Jul 22, 2022 09:54
    Hi Samantha
    OrderItem is a contained entity of ProductOrder, in the API TMF622. Perhaps it should have been called ProductOrderItem, but it won't be changed now.
    I would not expect to see an order item for an agreement, since you don't "order" agreements. There is (I believe) a relationship between Product (in the inventory) and Agreement (I just don't remember which way the relationship points). This allows you to express semantics such as:
    • An agreement covering a specific product
    • A framework agreement governing multiple products
    • and more
    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: Questions about the best way to map a Subscription agreement/contract model

    Posted Jul 25, 2022 16:03
    Hi Jonathan,

    Thanks for the swift response. Yes I've already analysed the relationship you mention (the agreementItems, each of which holds a ref to the product) and we use it to track the products purchased by the customer under the agreement. We've implemented the Agreement Management and Product Inventory swaggers so our customers can view their agreements with us and the associated products.

    What I'm trying to find a TMF framework to model is the usecase where a customer wishes to cancel an agreement:

    • they send a request to us via the TMF swagger
    • we return an acknowledgement of the request sent
    • they can then use the notificiation event listeners for the status of the agreement
    • the agreement goes through a workflow where it would go through several states: acknowledged, in review, cancelled
    Looking at the Agreement swagger, I inferred that the HTML apis would allow customers to perform CRUD operations on the agreements with instant gratification but this is not what we want. I understand you don't "order" agreements, though I do like the idea of a framework for requesting actions on entities that can't be completed immediately. ProductOrder swagger does this for products. Wondering what we can use for agreements.

    Thanks for your help!

    ------------------------------
    samantha holder
    Mitel Networks
    ------------------------------



  • 4.  RE: Questions about the best way to map a Subscription agreement/contract model

    TM Forum Member
    Posted Jul 26, 2022 07:01
    Feel free to add a Cancel task operation to your specific implementation of Agreement (look at Cancel Order in TMF622 for an example of a task operation, and in the design guidelines TMF630 for general coverage).
    But clearly the business process for canceling an agreement could be complex, depending on the involved party roles, products, and much more. You need to consider carefully the benefits of automation as against the disadvantages.
    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.
    ------------------------------



  • 5.  RE: Questions about the best way to map a Subscription agreement/contract model

    Posted Jul 28, 2022 11:43
    Hi Jonathan,

    Thank you so much for your help on this issue. I'll look into adding a Cancel task operation.

    ------------------------------
    samantha holder
    Mitel Networks
    ------------------------------