Explicit initialEvent for event type org.camaraproject.roaming-status-subscriptions.v0.roaming-status

[bigludo7]

Problem description
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

Expected action
In this case do we expect to send immediately a notification with the current status? I guess yes but it should be explicitly documented

Additional context
Following discussion with @gmuratk

[sachinvodafone]

Are we proposing to refine the API guideline definition for IntialEvent, or suggesting to add this information directly into our specification? I believe , the API guideline does state clearly that the user will receive an immediate response with the current state when initialEvent is set to true.

[bigludo7]

I was thinking adding the information in the specification.
Here the point is specific for this event type

• For roaming-on event-type - if you set initialEvent to true yo do not receive event if device not in roaming
• For roaming-off event-type - if you set initialEvent to true yo do not receive event if device is in roaming
• For roaming event-type - if you set initialEvent to true you can expect to receive immediately an event whatever the device roaming status

If you think that is is not necessary to add this precision I'm fine.

[sachinvodafone]

As I see that this behavior is already in the guidelines, so I would prefer to improve the existing definition in guideline itself if it is not clear. This will make it clearer and more consistent for all other APIs. Lets wait for others comment/preference on this.

[rartych]

In Design Guidelines there are general defintions.
In API definition we should include all necessary information for API developer and API consumer.

When initialEvent in Roaming status event is true then the subscription to this event almost covers the call to /device-roaming-status/retrieve.

If there is a value to indicate that the notification is related to initialEvent it can be done as proposed here:
camaraproject/Commonalities#299 (comment)

[gmuratk]

As @PedroDiez pointed out here, initialEvent = true, doesn't guarantee an immediate response with current state.

Design Guidelines state: "Set to true by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request."

So technically, this event type shouldn't support initialEvent = true, as the event itself is not a specific situation to be checked against. However, I still see the value of such event type. As you point out @rartych, this can help in future to move towards event only based approach (single query/sync and subscribe), and move away from separately querying first and creating a subscription later.

If the initialEvent definition can't be changed, then maybe we should consider adding an optional initialSync=true in the config attributes table. This attribute can differ from initialEvent = true, by removing the check against the current situation for these types of events and ensuring a response by the API Provider with current situation/state.

[PedroDiez]

I was thinking adding the information in the specification. Here the point is specific for this event type

• For roaming-on event-type - if you set initialEvent to true yo do not receive event if device not in roaming
• For roaming-off event-type - if you set initialEvent to true yo do not receive event if device is in roaming
• For roaming event-type - if you set initialEvent to true you can expect to receive immediately an event whatever the device roaming status

If you think that is is not necessary to add this precision I'm fine.

Agree with this, because generally these events are raised when a transition happens, and initialEvent is to request the event when the condition indicated in the subscription is already in place.

So:

• For roaming-on event-type, initialEvent is to generate the event if the device is already in roaming (if not in roaming it cannot generate anything because the proper nature of the event type is to indicate "entering in roaming")
• For roaming-off event-type initialEvent is to generate the event if the device is already in home network (analogous reason as above in the inverse way)
• For roaming event-type, initial Event is to generate the event anyway whatever the device roaming status, because in that event transitions in both ways are requested to be notified.

[gmuratk]

In my view, the suggestion on 'roaming event-type' seems to be overriding the initialEvent definition as an exception in documentation. By removing the 'current situation check we would be giving different behaviors to initialEvent based on event type definition.

[akoshunyadi]

In my view, the suggestion on 'roaming event-type' seems to be overriding the initialEvent definition as an exception in documentation. By removing the 'current situation check we would be giving different behaviors to initialEvent based on event type definition.

We can also say, that we don't skip the check for current situation, but we do the same in both cases :-)

[gmuratk]

@akoshunyadi I used that suggestion and added in the table I added to #222 conversation.