Geofencing API - Add Subscription type 'area-left-or-entered' to subscribe to both event in one time

[patrice-conil]

Problem description Today, to subscribe to area-entered and area-left for the same device, API's consumers need to subscribe twice.

Possible evolution To simplify usage of API for those who want to subscribe to both event we propose to create a new subscription type 'area-left-or-entered'

[jlurien]

I remember some discussion about the convenience to allow subscribing to several events in one subscription request and IIRC agreement was in favor of having a subscription per event type. Having a dedicated event name, just for subscriptions, that maps to 2 different triggered events is not that intuitive, and this mapping would have to be implemented in the backend, which may not be supported directly by some notification systems.

[patrice-conil]

Hi @jlurien, I agree with you about subscribing to uncorrelated events. But here I think we have use cases that correlate two types of events like this one: “As a parent, I want to know when my children arrive/leave school/home.” WDYT?

[jlurien]

As discussed during the meeting, we all agree that developers would likely be interested in subscribing to both events at once, and manage both events with a single subscription, but it was not obvious the best design approach. Options and some pros/cons (others may be added):

A) Allow the subscription to multiple events in one request, changing the subscribed event to an array of event types

• Pros: Clear specification, easy to understand. It is aligned with approach for CloudEvents Subcription API (WIP): https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#types
• Cons: It was discussed in Commonalities and preference was to have a single event per subscription

B) Defining a new event, e.g. area-crossed, with an additional direction attribute, to keep same events for subscription and triggering, similar to the roaming-change event in Device Status

• Pros: Keeps same event types for subscription and notification
• Cons: We need an additional property in notification

C) Having a new subscription event type area-entered-or-left that maps to 2 possible triggered events: area-entered or area-left

• Pros: Keeps current design with just one event per subscription
• Cons: Requires an additional mapping in the server to map the subscribed event to several triggered events

D) Keep current design and ask developers to keep 2 separate subscriptions

• Pros: Keeps current design with just one event per subscription
• Cons: Complicates management by developers

[patrice-conil]

Hi @jlurien, Thanks for your synthesis.

As discussed during the meeting, we all agree that developers would likely be interested in subscribing to both events at once, and manage both events with a single subscription, but it was not obvious the best design approach. Options and some pros/cons (others may be added):

A) Allow the subscription to multiple events in one request, changing the subscribed event to an array of event types

• Pros: Clear specification, easy to understand. It is aligned with approach for CloudEvents Subscription API (WIP): https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#types
• Pros: could be a good choice for a centralized subscription system as requested in Commonalities #121
• Cons: It was discussed in Commonalities and preference was to have a single event per subscription
• Cons: Requires an additional mapping in the server to map the subscribed event types to several triggered events as in C)

B) Defining a new event, e.g. area-crossed, with an additional direction attribute, to keep same events for subscription and triggering, similar to the roaming-change event in Device Status

• Pros: Keeps same event types for subscription and notification
• Cons: We need an additional property in notification
• Cons: Requires an additional mapping in the server to map the subscribed event and direction as in C)
• Cons: type of event is not sufficient, need to look inside data to retrieve its direction (introduce complexity on both ends => new event+direction as same meaning as already existing event)

C) Having a new subscription event type area-entered-or-left that maps to 2 possible triggered events: area-entered or area-left

• Pros: Keeps current design with just one event per subscription
• Cons: Requires an additional mapping in the server to map the subscribed event to several triggered events

D) Keep current design and ask developers to keep 2 separate subscriptions

• Pros: Keeps current design with just one event per subscription
• Cons: Complicates management by developers

[jlurien]

fyi @PedroDiez

[alpaycetin74]

I find A as the most intuitive one for users. It is also more intuitive when mapping it to more than one event in the backend: The developer just loops over the event list and maps each one of them to one event (1-1). This is slightly better than breaking 1 event into 2 pieces. In the future, if we would imagine more events, approach A keeps it still simple (Just the array gets longer). In option C for instance, we would be constantly adding new "combined" events and developers would need to break them down into "single" events.

[shilpa-padgaonkar]

@patrice-conil @jlurien @alpaycetin74 @PedroDiez Could you kindly provide your feedback also in this open issue in Commonalities if you would like to support optionA discussed above?

https://github.com/camaraproject/Commonalities/issues/154

[bigludo7]

As our new subscription model allows to pass an array of event-type we could probably close this one?

As a reminder the version supported for first meta release will not allow this multi-event feature but this point will be for consideration after this meta-release (allowing scenario A)

@jlurien @alpaycetin74 @patrice-conil wdyt? we can close this one?

[alpaycetin74]

Collaborator

I think so, yes. Thank you.

[patrice-conil]

No objection from my side, I think we will be able to manage array of subscription type for the next release.

[jlurien]

So for the current version clients will have to manage both events separately in 2 subscriptions, right. That is OK for me as well

[bigludo7]

As our new subscription model allows to pass an array of event-type we close this one.

As a reminder the version supported for first meta release will not allow this multi-event feature but this point will be for consideration after this meta-release (allowing scenario A)