Synchronization Status for initialEvent = true notifications

[gmuratk]

Problem description

API Design Guideline states subscription-ends notification shouldn't be counted in the subscriptionMaxEvents. However, such a statement is not available for notifications resulting from initialEvent=true.

In addition, there may be cases where a single notification may not be sufficient to initialize/synchronize the data on the client side and clients need to know when the initialization end and when the events start occurring.

Possible evolution

One possible solution might be to introduce a feature initialEventSync with enums like 'synchronizing', synchronizationComplete. This feature can be added similar to terminationReason attribute.

Alternative solution

Additional context

[bigludo7]

Hello @gmuratk

This is a fair point for alignement

Don't you think it will simpler to adopt a rule regarding count (or not) of this initial event to the subscriptionMaxEvents?

Straightforward rule will be to state that it counts. In this case, if a consumer request a subscription with subscriptionMaxEvents set to 1 and maxEvent sets to 1 it may receive immediately the 'business' event and the 'termination event'.

[gmuratk]

Hi @bigludo7
I don't think the suggestion will cover all the cases. In some cases, API provider may have to collect data from different systems or send data in chunks in response to 'initialEvent = true'.

In cases where client may need initialization of state, and then start receiving updates, client will need to understand when the synchronization/initialization complete (from API provider point of view) and start the counter against the subscriptionMaxEvents.

[bigludo7]

I don't think the suggestion will cover all the cases. In some cases, API provider may have to collect data from different systems or send data in chunks in response to 'initialEvent = true'.

Thanks @gmuratk for your answer.
I'm not sure to get the UC Murat... and btw not confortable for the sake of our API consumer to send data in chunks.

If we go to our current API:

• For Geofencing, Device Roaming Subscription, Device Reacheability subscription this is straightforward and I do see value to introduce another attribute - right?
• For Network Insights I do not see examples in the yaml so cannot comment.

[bigludo7]

May i ask other companies to provide feedback on this topic as it appears that we are not aligned as of now with @gmuratk .

@shilpa-padgaonkar @PedroDiez in particular as you were involved in the design.

[gmuratk]

Thanks for soliciting additional feedback, @bigludo7. I'd like the following points to be taken into consideration for this discussion:

1. When I stated, 'send [initial data] in chunks', I want to be clear that multiple notification messages, i.e. 'send the initial data as multiple notification messages'
2. @bigludo7 I think we align on the need that DG needs a statement for counting (or not) the notification message delivering initial event data. However, decision on counting or not counting the initialEvent response(s) may be considered a business decision and API providers may choose differently.
3. However, this means we need to provide a way to distinguish between whether notification message is received in response to initialEvent or not. I think API consumers will benefit from initial or occurred event distinction.
4. If there is a requirement on sending a single message for initialEvent = true, then it should be a behavior stated in the DG. However, that would mean we would be imposing a design/implementation requirement on the API Provider as well.

As @bigludo7 stated, it would be great to hear feedback from others.

[PedroDiez]

Hi,
@bigludo7, @rartych, @gmuratk, @shilpa-padgaonkar

subscription-ends is an operational event, that is, a Telco Operator "facility" to indicate an "event" related to subscription lifecycle indicating its ending. But it is not a "service" event, because the API client does not receive "customer information"

However, initialEvent=true is a "service event", because the API Client is saying, "I want to know if the phoneNumber/device is already in this condition", therefore this event should count for subscriptionMaxEvents logic, because Telco Operators may want to apply event-based charging (i.e. number of events send). At the end is user-based information so it provides valuable information.

Saying that, I am aligned with this Ludovic's comment, if understood correclty. And explicit indicate that initialEvent is included within subscriptionMaxEvents logic.

cc @jgarciahospital

[gmuratk]

Hi @PedroDiez , the distinction you draw between the subscription-ends and initialEvent=true makes sense.

However, we have to recognize initialEvent=true maybe used to get the current status, rather than checking against a condition. For example, DeviceStatus roaming-status-subscription API defines event type roaming-status. A client may subscribe to this event type with an initialEvent=true which will send back the current status, and then any other status changes. Client in this case would be using the initialEvent=true as a cache sync, and then retrieve any additional updates to the state.

An API may want to implement delta updates for event notifications. In such cases it will be necessary for the current status to be distinguished from the event notifications. For example, if an even notification consists of 10 data elements, but when there is a change to only one of them, there is no need to send all the other 9 data elements. API consumer can subscribe to this notification with initialEvent=true, receive a 'cache-sync' response containing all 10 data elements, and as changes occur, only receive the incremental changes.

[PedroDiez]

Hi,

@gmuratk @bigludo7 As per my understanding we are aligned about initialEvent to be considered into subscriptionMaxEvents logic, after it has been comment in today's commonalities meeting (14/OCT)

@gmuratk Regarding your latest comment. In design commonalities initialEvent is to indicate API Server (i.e. Telco Operator) to send an event in case the user is already in a let's say "situation" that is already matching subscription initialEvent so as if the requested suscription is not yet satisfied by the "user situation" even initialEvent is sent no notification would be generated.

I tend to think your understading of initialEvent is just an initial event about "user situation" not linked to the suscription details. Is it right?

Just for me to understand, could you provide and example about the case you mention? (several data elements)

For example, if an even notification consists of 10 data elements, but when there is a change to only one of them, there is no need to send all the other 9 data elements. API consumer can subscribe to this notification with initialEvent=true, receive a 'cache-sync' response containing all 10 data elements, and as changes occur, only receive the incremental changes.

[gmuratk]

Hi @PedroDiez,
While the Design Guideline description is as you stated above, there is at least one API, device-roaming-status, which defines an event type org.camaraproject.roaming-status-subscriptions.v0.roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely - This suggests that there is no check against the 'situation' (on or off) and an event with the current status must be returned if the initialEvent is set to true by the API consumer. While this may have been unintentional, to be honest, I think it may be better to embrace it and allow for 'current status' to be retrieved.

An example use case we have at hand is the Capability and Runtime Restrictions (C&RR). An API Provider may define 10s or 100s of Runtime Restrictions (applying to different subscribers, locations, network conditions). An API consumer that supports the C&RR can initialize its cache (e.g. at the start of a session) by retrieving all the runtime restrictions, and then receiving only changed runtime restrictions, which may be a very small number of restrictions.

[bigludo7]

BTW - on a specific point:
@gmuratk you raised a good point worth to be documented in the device-roaming-status-souscription yaml
For event type org.camaraproject.roaming-status-subscriptions.v0.roaming-status we have to indicate clearly the expected behavior if initialEvent is set to True. --> I will trigger an issue there.

[PedroDiez]

Hi,

Thanks for the explanation @gmuratk

[rartych]

@gmuratk
I guess you propose for synchronization the dedicated parameter in notification data field - I call it 'trigger', then for org.camaraproject.roaming-status-subscriptions.v0.roaming-status we would have:

    RoamingStatus:
      description: Event detail structure for org.camaraproject.roaming-status-subscriptions.v0.roaming-status event
      type: object
      properties:
        roaming:
          type: boolean
          description: Roaming status. True, if it is roaming.
        countryCode:
          $ref: "#/components/schemas/CountryCode"
        countryName:
          $ref: "#/components/schemas/CountryName"
        subscriptionId:
          $ref: "#/components/schemas/SubscriptionId"
        trigger:
          type: enum
             - INITIAL_EVENT
             - EVENT_OCCURRENCE
  

If you consider multi-stage synchronization additional values for enum can be defined.

I think the synchronization as you describe it is not considered in current subscription APIs, hence it is hard to define common guidelines and artifacts. And maybe too early. Each subproject currently defines thedata field structure.

Anyway it can be tested in Capability and Runtime Restrictions (C&RR) definition if it is created as Sandbox.
(Another reason to go for it.)

[gmuratk]

@rartych I was thinking along the same lines. Thanks!