Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarification for initialEvent use in documentation #237

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Clarification for initialEvent use in documentation #237

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
f4a330b
Clarification for initialEvent & roaming event type
bigludo7 Dec 22, 2024
56002e7
Clarification for initialEvent & reacheability event type
bigludo7 Dec 22, 2024
83b8717
Fix MegaLinter issues
bigludo7 Dec 22, 2024
ec2ded6
Fix MegaLinter issues
bigludo7 Dec 22, 2024
db63c35
Fix typos in table header
bigludo7 Dec 23, 2024
a281b70
Fix typos
bigludo7 Dec 23, 2024
f981ae0
Update table in the documentation
bigludo7 Jan 15, 2025
beb0fcb
Add device-network-type-subscription.yaml
bigludo7 Jan 15, 2025
9941900
Delete code/API_definitions/device-network-type-subscription.yaml
bigludo7 Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions code/API_definitions/device-reachability-status-subscriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,26 @@ info:
- the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached
- the API server has to stop sending notification prematurely

**Note on combined usage of ``initialEvent`` and ``subscriptionMaxEvents``**:

If an event is triggered following ``initialEvent`` set to true,
this event will be counted towards ``subscriptionMaxEvents`` (if provided).


**Clarification on ``initialEvent`` & ``event-type`` behaviour:**

Following table illustrate behaviour regarding event triggering depending on **initial** reachability state of the device:

| subscrived event-type | device reachability status at subscription time | event send if ``initialEvent`` set to true |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor typos in table header:
subscrived --> subscribed
event send --> event sent

| ----------------------| ------------- | --------------- |
| reachability-data | OK for data usage | Yes |
| reachability-data | disconnected or only SMS | No |
| reachability-sms | OK for data usage | No |
| reachability-sms | only SMS | Yes |
| reachability-sms | disconnected | No |
| reachability-disconnected | OK for Data or SMS usage | No |
| reachability-disconnected | disconnected | Yes |

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am afraid that table is not coming nicely on the swagger editor

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took some time to interpret the table. Can we add some more information like (not necessary if others are fine with existing information):
Screenshot 2025-01-14 at 12 25 56

### Notifications callback

This endpoint describes the event notification received on subscription listener side when the event occurred.
Expand Down
38 changes: 38 additions & 0 deletions code/API_definitions/device-roaming-status-subscriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,44 @@ info:
- the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached
- the API server has to stop sending notification prematurely

**Note on combined usage of ``initialEvent`` and ``subscriptionMaxEvents``**:

If an event is triggered following ``initialEvent`` set to true,
this event will be counted towards ``subscriptionMaxEvents`` (if provided).

**Clarification on ``initialEvent`` & ``event-type`` behaviour:**

Following table illustrate behaviour regarding event triggering depending on **initial** roaming state of the device:

| subscrived event-type | device roaming status at subscription time | event send if ``initialEvent`` set to true |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor typos in table header:
subscrived --> subscribed
event send --> event sent

| ----------------------| ------------- | --------------- |
| roaming-status | Roaming On | Yes |
| roaming-status | Roaming Off | Yes |
| roaming-on | Roaming On | Yes |
| roaming-on | Roaming Off | No |
| roaming-off | Roaming On | No |
| roaming-off | Roaming Off | Yes |
| roaming-change-country | Roaming Off | No(*) |
| roaming-change-country | Roaming On | No(*) |

(*) Use of ``initialEvent`` has no impact on roaming-change-country event-type.

**Clarification on ``roaming-change-country`` event-type:**

``roaming-change-country`` event is send only when the device stays in roaming situation and change country.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

event is 'sent'

Suppose a device from Germany & all event types subscribed:

- Device moves from Germany to France:
- triggered: roaming-status & roaming-on
- not triggered: roaming-change-country & roaming-off
- Device moves from France to Belgium:
- triggered: roaming-change-country
- not triggered: roaming-status, roaming-on & roaming-off
- Device moves from Belgium back to Germany
- triggered: roaming-status & roaming-off
- not triggered: roaming-on & roaming-change-country


### Notifications callback

This endpoint describes the event notification received on subscription listener side when the event occurred.
Expand Down
Loading