Open APIs

 View Only
  • 1.  Notifications semantics

    TM Forum Member
    Posted Jan 16, 2025 10:10

    Hi,

    I am trying to design API notifications and I have some questions, because specifications and user guides are not everly detailed in this regard.

    Let's say we have TMF622 API and the following events:

    • ProductOrderCreateEvent
    • ProductOrderAttributeValueChangeEvent

    • ProductOrderStateChangeEvent

    Now my primary concern here is about the payload and what happens when I have multiple changes to an order per transaction. The API specs states that the content of those events is just ProductOrder but examples in UserGuide suggest that it is not a full object, just a part of an object after the change:

    • ProductOrderAttributeValueChangeEvent - contains only the changed attribbutes
    • ProductOrderStateChangeEvent - contains only order Id + href and state (and itemStateChange which in fact is not mentioned in v5 swagger spec...)
    • ProductOrderCreateEvent - contains a full order

    So my questions are:

    • Does this notifications have full value or delta semantics?
    • What if in one logical operation I am changing multiple fields at once, I assume it's enough to emit one ProductOrderAttributeValueChangeEvent?
    • What if in one logical operation (i.e. db transaction) I am changing the state (or any field for that matter, also a milestone) more than once (processes like orders can have automatic state transitions, so I may skip e.g.), do I have to emit many events? (I assume yes)


    ------------------------------
    Łukasz Kubica
    Comarch S.A.
    ------------------------------


  • 2.  RE: Notifications semantics

    TM Forum Member
    Posted Jan 17, 2025 01:16

    Hi Łukasz

    Good question and it is one that has recently resulted in JIRA AP-6550 (Include Event patterns in TMF763 Gen5 Design Guidelines Part 7).  Part 7 is currently undergoing final review and should be released shortly.

    Regarding your questions:

    Does this notifications have full value or delta semantics? Answer: Currently it is a delta but the contents of the delta for each event type still needs to be agreed (in Part 7)

    What if in one logical operation I am changing multiple fields at once, I assume it's enough to emit one ProductOrderAttributeValueChangeEvent? Answer: Correct, one event is sufficient for multiple changes (once again this will be clarified in Part 7)

    What if in one logical operation (i.e. db transaction) I am changing the state (or any field for that matter, also a milestone) more than once (processes like orders can have automatic state transitions, so I may skip e.g.), do I have to emit many events? (I assume yes) Answer: Correct, you would require multiple events in this case.

    Sorry I cannot help more at this time, but you won't have to wait long for a more precise answer.



    ------------------------------
    Dan d'Albuquerque
    Entronica Company Limited
    ------------------------------



  • 3.  RE: Notifications semantics

    TM Forum Member
    Posted Jan 17, 2025 05:01

    Thanks.

    It is very important to me as I am currently designing the generic event notification mechanism. 

    One note though, the "delta" which can be expressed through partial snapshots is limited when it comes to field removal, let's say I have removed 1 order item, then I have to send a full list of order items? (without the removed item). My suggestion is that using JSON Patch might be much more effective here, I understand that this is a classical json patch vs merge-patch dilemma.



    ------------------------------
    Łukasz Kubica
    Comarch S.A.
    ------------------------------



  • 4.  RE: Notifications semantics

    TM Forum Member
    Posted Jan 17, 2025 05:14
    Edited by Lukasz Kubica Jan 17, 2025 05:15

    And one more thing, the filtering semantics.

    I assume that any query e.g. "query": "[?(@.event.resource.status=='Resolved')]" is applied to the object snapshot after the modification (so I change status from new -> resolved and emit event with status:"Resolved". But when in the event body there is anything that did not change (and with JSON Merge-patch and collections there is, e.g. if I remove 1 order item I need to repeat all not removed), then the query semantics get blurry, because there are two possible:

    • query applies to a change, so in the above example I only want ONE notification for every status CHANGE to "Resolved"
    • query applies to an object after modification, so I get notification each time status IS "Resolved"

    This is accidentally not a problem with status, but it is a problem when I would like to capture a change on any attribute, e.g. a characteristic set on a Product as a result of fulfilment etc. 



    ------------------------------
    Łukasz Kubica
    Comarch S.A.
    ------------------------------