From a28b026b39e293f99e7d6c0cfa84a983446644bf Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 12:28:34 +0200 Subject: [PATCH 01/15] add time based notification filtering Signed-off-by: Kerry Archibald --- .../3677-time-based-notification-filtering.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 proposals/3677-time-based-notification-filtering.md diff --git a/proposals/3677-time-based-notification-filtering.md b/proposals/3677-time-based-notification-filtering.md new file mode 100644 index 00000000000..5f6476de7b3 --- /dev/null +++ b/proposals/3677-time-based-notification-filtering.md @@ -0,0 +1,106 @@ +# MSC3677: Time based notification filtering +Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to be able to manage the level of noisiness from an application based on day and time. + +Users should be able to configure many periods of notification levels during the day; for example before work, lunch hour, and after work. +They should also be able to schedule notification levels for a particular day of the week; for example a quieter notification setting all day on No Meeting Wednesday, or complete silence over the weekend. + +## Proposal + +We introduce a push notification [condition](https://spec.matrix.org/v1.2/client-server-api/#push-rules) `time_and_day` to filter based on time of day and day of week. + +This conditions specifies `intervals` and `timezone`. + +`timezone` is an [Olson formatted timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone format allows for automatic handling of DST. +If not set, UTC will be used. + +`intervals` is an array of day and time interval configurations. +Intervals in the array are an OR condition. + +Each interval is an object that defines a `time_of_day` tuple and `day_of_week` array. + +- `time_of_day` is a tuple of `hh:mm` [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). This condition is met when the server's timezone-adjusted time is between the values of the tuple. Values are inclusive. +- `day_of_week` is an array of integers representing days of the week, where 1 = Monday, 7 = Sunday. This condition is met when the server's timezone-adjusted day is included in the array. + +When both `time_of_day` and `day_of_week` conditions are met for one of the intervals in the`intervals` array the rule evaluates to true. + +```json +{ + "kind": "dnd_time_and_day", + "timezone": "Europe/Berlin", + "intervals": [ + { + "time_of_day": ['00:00', '09:00'], + "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri + }, + { + "time_of_day": ['17:00', '23:59'], + "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri + }, + { + ... + } +}, +``` + +A popular usecase for this condition is overriding default push rules to create a do not disturb behaviour. +For example, Wednesday morning focus time rule +```json +{ + "rule_id": ".m.rule.master", + "default": false, + "enabled": true, + "conditions": [ + "kind": "dnd_time_and_day", + "intervals": [ + { + "time_of_day": ['09:00', '11:00'], + "day_of_week": [3] // Wednesday + }, + ], + "actions": [ + "dont_notify" + ] +} +``` + + +## Potential issues +- If a user changes timezone their push rules will not automatically update. + +## Alternatives + +#### System +Some systems (e.g. iOS) have their own DND / focus mode but this is only an option if all of your devices are within that vendor ecosystem (here Apple) and doesn't help when you have e.g. an iPad and an Android phone. +This also needs to be configured per device. + +#### `room_member_count` style comparison +```json +"conditions": [ + { + "kind": "time_of_day", + "is": ">=18000000" // 17:00 NZST, 5:00 UTC + }, + { + "kind": "time_of_day", + "is": "<=75600000" // 9:00 NZST, 21:00 UTC + }, + + ] +``` +As only one rule per `kind` + `rule_id` is allowed and rule conditions are an `AND` this allows only one contiguous range to be defined. This precludes one of the main usecases for the feature - ignoring notifications outside of work/waking hours. + +#### Device assessment +An alternative version of the `time_and_day` defined above used timezone agnostic times and did not define a timezone. This rule would be assessed only on the device. + +#### ms offsets for time intervals +Previous versions used ms offsets to represent time of day instead of `hh:mm`. Ms offsets may behave incorrectly on days with a DST jump. + +## Security considerations +- Stores user's timezone on the server. DND periods saved to the server without timezone information would reveal information about a user's approximate timezone anyway. Users who do not wish to store their timezone can set DND periods in UTC. + +## Unstable prefix + +- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.msc3677.time_and_day` + +## Dependencies +None. From fc3642e86228b1199361bc9a0c02c6c17f2bec5c Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 12:31:50 +0200 Subject: [PATCH 02/15] correct msc num Signed-off-by: Kerry Archibald --- ...filtering.md => 3767-time-based-notification-filtering.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{3677-time-based-notification-filtering.md => 3767-time-based-notification-filtering.md} (97%) diff --git a/proposals/3677-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md similarity index 97% rename from proposals/3677-time-based-notification-filtering.md rename to proposals/3767-time-based-notification-filtering.md index 5f6476de7b3..3702274888c 100644 --- a/proposals/3677-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -1,4 +1,4 @@ -# MSC3677: Time based notification filtering +# MSC3767: Time based notification filtering Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to be able to manage the level of noisiness from an application based on day and time. Users should be able to configure many periods of notification levels during the day; for example before work, lunch hour, and after work. @@ -100,7 +100,7 @@ Previous versions used ms offsets to represent time of day instead of `hh:mm`. M ## Unstable prefix -- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.msc3677.time_and_day` +- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.msc3767.time_and_day` ## Dependencies None. From 3b638a461c9b3fddc3fac5e776b170513d9097c0 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 12:34:45 +0200 Subject: [PATCH 03/15] fix json formatting Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 3702274888c..2333b92b666 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -23,17 +23,17 @@ Each interval is an object that defines a `time_of_day` tuple and `day_of_week` When both `time_of_day` and `day_of_week` conditions are met for one of the intervals in the`intervals` array the rule evaluates to true. -```json +```json5 { "kind": "dnd_time_and_day", "timezone": "Europe/Berlin", "intervals": [ { - "time_of_day": ['00:00', '09:00'], + "time_of_day": ["00:00", "09:00"], "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri }, { - "time_of_day": ['17:00', '23:59'], + "time_of_day": ["17:00", "23:59"], "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri }, { @@ -44,7 +44,7 @@ When both `time_of_day` and `day_of_week` conditions are met for one of the inte A popular usecase for this condition is overriding default push rules to create a do not disturb behaviour. For example, Wednesday morning focus time rule -```json +```json5 { "rule_id": ".m.rule.master", "default": false, @@ -53,7 +53,7 @@ For example, Wednesday morning focus time rule "kind": "dnd_time_and_day", "intervals": [ { - "time_of_day": ['09:00', '11:00'], + "time_of_day": ["09:00", "11:00"], "day_of_week": [3] // Wednesday }, ], @@ -74,7 +74,7 @@ Some systems (e.g. iOS) have their own DND / focus mode but this is only an opti This also needs to be configured per device. #### `room_member_count` style comparison -```json +```json5 "conditions": [ { "kind": "time_of_day", From 844fb07630aaa244d4c80d18389d02d72898969b Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 18:01:42 +0200 Subject: [PATCH 04/15] make time of day optional with default all day Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 2333b92b666..fa22b263a2b 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -11,14 +11,17 @@ We introduce a push notification [condition](https://spec.matrix.org/v1.2/client This conditions specifies `intervals` and `timezone`. `timezone` is an [Olson formatted timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone format allows for automatic handling of DST. -If not set, UTC will be used. +If not set or invalid UTC will be used. `intervals` is an array of day and time interval configurations. Intervals in the array are an OR condition. Each interval is an object that defines a `time_of_day` tuple and `day_of_week` array. -- `time_of_day` is a tuple of `hh:mm` [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). This condition is met when the server's timezone-adjusted time is between the values of the tuple. Values are inclusive. +- `time_of_day` is a tuple of `hh:mm` [ISO 8601 formatted + times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). + This condition is met when the server's timezone-adjusted time is between the values of the tuple. Values are + inclusive. If `time_of_day` is not set on an interval all times will meet the condition. - `day_of_week` is an array of integers representing days of the week, where 1 = Monday, 7 = Sunday. This condition is met when the server's timezone-adjusted day is included in the array. When both `time_of_day` and `day_of_week` conditions are met for one of the intervals in the`intervals` array the rule evaluates to true. @@ -37,7 +40,8 @@ When both `time_of_day` and `day_of_week` conditions are met for one of the inte "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri }, { - ... + // no time_of_day, all day on Sunday is matched + "day_of_week": [7] // Sunday } }, ``` From 5d28cef3347b7e2b130fd1ff1550ef410f149789 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 18:25:26 +0200 Subject: [PATCH 05/15] add tables Signed-off-by: Kerry Archibald --- .../3767-time-based-notification-filtering.md | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index fa22b263a2b..02559e714f0 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -18,13 +18,27 @@ Intervals in the array are an OR condition. Each interval is an object that defines a `time_of_day` tuple and `day_of_week` array. -- `time_of_day` is a tuple of `hh:mm` [ISO 8601 formatted - times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). - This condition is met when the server's timezone-adjusted time is between the values of the tuple. Values are - inclusive. If `time_of_day` is not set on an interval all times will meet the condition. -- `day_of_week` is an array of integers representing days of the week, where 1 = Monday, 7 = Sunday. This condition is met when the server's timezone-adjusted day is included in the array. +**`dnd_time_and_day` condition definition** -When both `time_of_day` and `day_of_week` conditions are met for one of the intervals in the`intervals` array the rule evaluates to true. +| key | type | value | description | Required | +| ---- | ----| ----- | ----------- | -------- | +| `kind` | string | 'dnd_time_of_day' | | **Required** | +| `timezone` | string | user's [Olson formatted timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | The timezone to use for time comparison. This format allows for automatic DST handling | Optional. Defaults to UTC | +| `intervals` | array | array of time matching intervals (see below) | Intervals are evaluated with an OR condition | **Required** | + +**time matching interval definition** + +| key | type | value | description | Required | +| ---- | ----| ----- | ----------- | -------- | +| `time_of_day` | string[] | tuple of `hh:mm` times | times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | +| `day_of_week` | number[] | array of integers 1-7 | An array of integers representing days of the week, where 1 = Monday, 7 = Sunday | **Required** | + + +- `time_of_day` condition is met when the server's timezone-adjusted time is between the values of the tuple, or when no + `time_of_day` is set on the interval. Values are inclusive. +- `day_of_week` condition is met when the server's timezone-adjusted day is included in the array. + +When both `time_of_day` and `day_of_week` conditions are met for an interval in the `intervals` array the rule evaluates to true. ```json5 { @@ -46,12 +60,12 @@ When both `time_of_day` and `day_of_week` conditions are met for one of the inte }, ``` -A popular usecase for this condition is overriding default push rules to create a do not disturb behaviour. +A primary usecase for this condition is creating 'do not disturb' behaviour. For example, Wednesday morning focus time rule ```json5 { "rule_id": ".m.rule.master", - "default": false, + "default": true, "enabled": true, "conditions": [ "kind": "dnd_time_and_day", @@ -94,13 +108,17 @@ This also needs to be configured per device. As only one rule per `kind` + `rule_id` is allowed and rule conditions are an `AND` this allows only one contiguous range to be defined. This precludes one of the main usecases for the feature - ignoring notifications outside of work/waking hours. #### Device assessment -An alternative version of the `time_and_day` defined above used timezone agnostic times and did not define a timezone. This rule would be assessed only on the device. +An alternative version of the `time_and_day` defined above used timezone agnostic times and did not define a timezone. +This rule would be assessed only on the device. This is not easily achieved on every platform. #### ms offsets for time intervals -Previous versions used ms offsets to represent time of day instead of `hh:mm`. Ms offsets may behave incorrectly on days with a DST jump. +Previous proposals used ms offsets to represent time of day instead of `hh:mm`. Ms offsets may behave incorrectly on +days with a DST jump and are less intuitive. ## Security considerations -- Stores user's timezone on the server. DND periods saved to the server without timezone information would reveal information about a user's approximate timezone anyway. Users who do not wish to store their timezone can set DND periods in UTC. +- Stores user's timezone on the server. DND periods saved to the server without timezone information would reveal + information about a user's approximate timezone anyway. Users who do not wish to store their timezone can set DND + periods in UTC (this option should be available in clients implementing time based notification filtering). ## Unstable prefix From 69e186b7f3c7f53e22cfbf04f0ba4e3734b574d9 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 18:29:26 +0200 Subject: [PATCH 06/15] dnd_time_and_day -> time_and_day Signed-off-by: Kerry Archibald --- .../3767-time-based-notification-filtering.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 02559e714f0..acdfee21213 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -8,25 +8,15 @@ They should also be able to schedule notification levels for a particular day of We introduce a push notification [condition](https://spec.matrix.org/v1.2/client-server-api/#push-rules) `time_and_day` to filter based on time of day and day of week. -This conditions specifies `intervals` and `timezone`. - -`timezone` is an [Olson formatted timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone format allows for automatic handling of DST. -If not set or invalid UTC will be used. - -`intervals` is an array of day and time interval configurations. -Intervals in the array are an OR condition. - -Each interval is an object that defines a `time_of_day` tuple and `day_of_week` array. - **`dnd_time_and_day` condition definition** | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | | `kind` | string | 'dnd_time_of_day' | | **Required** | | `timezone` | string | user's [Olson formatted timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | The timezone to use for time comparison. This format allows for automatic DST handling | Optional. Defaults to UTC | -| `intervals` | array | array of time matching intervals (see below) | Intervals are evaluated with an OR condition | **Required** | +| `intervals` | array | array of time matching intervals (see below) | Intervals representing time periods in which the rule should match. Evaluated with an OR condition | **Required** | -**time matching interval definition** +**Time matching interval definition** | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | @@ -61,7 +51,7 @@ When both `time_of_day` and `day_of_week` conditions are met for an interval in ``` A primary usecase for this condition is creating 'do not disturb' behaviour. -For example, Wednesday morning focus time rule +For example, Wednesday morning focus time rule: ```json5 { "rule_id": ".m.rule.master", From 38740934f24c9e78096471d16b6ba5dc56be563b Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 18:32:29 +0200 Subject: [PATCH 07/15] more tweaks Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index acdfee21213..4019b063e7c 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -8,7 +8,7 @@ They should also be able to schedule notification levels for a particular day of We introduce a push notification [condition](https://spec.matrix.org/v1.2/client-server-api/#push-rules) `time_and_day` to filter based on time of day and day of week. -**`dnd_time_and_day` condition definition** +**`time_and_day` condition definition** | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | @@ -20,8 +20,8 @@ We introduce a push notification [condition](https://spec.matrix.org/v1.2/client | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | -| `time_of_day` | string[] | tuple of `hh:mm` times | times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | -| `day_of_week` | number[] | array of integers 1-7 | An array of integers representing days of the week, where 1 = Monday, 7 = Sunday | **Required** | +| `time_of_day` | string[] | tuple of `hh:mm` time | Tuple representing start and end of a time interval in which the ruule should match. Times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | +| `day_of_week` | number[] | array of integers 1-7 | An array of integers representing days of the week on which the rule should match, where 1 = Monday, 7 = Sunday | **Required** | - `time_of_day` condition is met when the server's timezone-adjusted time is between the values of the tuple, or when no @@ -32,7 +32,7 @@ When both `time_of_day` and `day_of_week` conditions are met for an interval in ```json5 { - "kind": "dnd_time_and_day", + "kind": "time_and_day", "timezone": "Europe/Berlin", "intervals": [ { @@ -44,7 +44,7 @@ When both `time_of_day` and `day_of_week` conditions are met for an interval in "day_of_week": [1, 2, 3, 4, 5] // Monday - Fri }, { - // no time_of_day, all day on Sunday is matched + // no time_of_day, all day is matched "day_of_week": [7] // Sunday } }, @@ -58,7 +58,8 @@ For example, Wednesday morning focus time rule: "default": true, "enabled": true, "conditions": [ - "kind": "dnd_time_and_day", + "kind": "time_and_day", + "timezone": "Europe/Berlin", "intervals": [ { "time_of_day": ["09:00", "11:00"], From de72c825d7402a5a0db697f0b3eb8a68724ba62f Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Thu, 7 Apr 2022 18:32:55 +0200 Subject: [PATCH 08/15] typo Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 4019b063e7c..841ae6c6d71 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -20,7 +20,7 @@ We introduce a push notification [condition](https://spec.matrix.org/v1.2/client | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | -| `time_of_day` | string[] | tuple of `hh:mm` time | Tuple representing start and end of a time interval in which the ruule should match. Times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | +| `time_of_day` | string[] | tuple of `hh:mm` time | Tuple representing start and end of a time interval in which the rule should match. Times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | | `day_of_week` | number[] | array of integers 1-7 | An array of integers representing days of the week on which the rule should match, where 1 = Monday, 7 = Sunday | **Required** | From d98b3df4bd5f856ebd5d8663ef8442ed157cb9c8 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Fri, 8 Apr 2022 10:49:25 +0200 Subject: [PATCH 09/15] word wrap Signed-off-by: Kerry Archibald --- .../3767-time-based-notification-filtering.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 841ae6c6d71..fcd362ea681 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -1,12 +1,15 @@ # MSC3767: Time based notification filtering -Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to be able to manage the level of noisiness from an application based on day and time. +Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to +be able to manage the level of noisiness from an application based on day and time. -Users should be able to configure many periods of notification levels during the day; for example before work, lunch hour, and after work. -They should also be able to schedule notification levels for a particular day of the week; for example a quieter notification setting all day on No Meeting Wednesday, or complete silence over the weekend. +Users should be able to configure many periods of notification levels during the day; for example before work, lunch +hour, and after work. They should also be able to schedule notification levels for a particular day of the week; for +example a quieter notification setting all day on No Meeting Wednesday, or complete silence over the weekend. ## Proposal -We introduce a push notification [condition](https://spec.matrix.org/v1.2/client-server-api/#push-rules) `time_and_day` to filter based on time of day and day of week. +We introduce a push notification [condition](https://spec.matrix.org/v1.2/client-server-api/#push-rules) `time_and_day` +to filter based on time of day and day of week. **`time_and_day` condition definition** @@ -28,7 +31,8 @@ We introduce a push notification [condition](https://spec.matrix.org/v1.2/client `time_of_day` is set on the interval. Values are inclusive. - `day_of_week` condition is met when the server's timezone-adjusted day is included in the array. -When both `time_of_day` and `day_of_week` conditions are met for an interval in the `intervals` array the rule evaluates to true. +When both `time_of_day` and `day_of_week` conditions are met for an interval in the `intervals` array the rule evaluates +to true. ```json5 { @@ -79,8 +83,9 @@ For example, Wednesday morning focus time rule: ## Alternatives #### System -Some systems (e.g. iOS) have their own DND / focus mode but this is only an option if all of your devices are within that vendor ecosystem (here Apple) and doesn't help when you have e.g. an iPad and an Android phone. -This also needs to be configured per device. +Some systems (e.g. iOS) have their own DND / focus mode but this is only an option if all of your devices are within +that vendor ecosystem (here Apple) and doesn't help when you have e.g. an iPad and an Android phone. This also needs to +be configured per device. #### `room_member_count` style comparison ```json5 @@ -96,7 +101,9 @@ This also needs to be configured per device. ] ``` -As only one rule per `kind` + `rule_id` is allowed and rule conditions are an `AND` this allows only one contiguous range to be defined. This precludes one of the main usecases for the feature - ignoring notifications outside of work/waking hours. +As only one rule per `kind` + `rule_id` is allowed and rule conditions are an `AND` this allows only one contiguous +range to be defined. This precludes one of the main usecases for the feature - ignoring notifications outside of +work/waking hours. #### Device assessment An alternative version of the `time_and_day` defined above used timezone agnostic times and did not define a timezone. From 5a2939e99b2ea4b9d7126b3a1f0877352cca9952 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Fri, 8 Apr 2022 11:04:36 +0200 Subject: [PATCH 10/15] update example to weekend Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index fcd362ea681..70f5bf30128 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -49,7 +49,7 @@ to true. }, { // no time_of_day, all day is matched - "day_of_week": [7] // Sunday + "day_of_week": [6, 7] // Weekend } }, ``` From a15aa043a2f457e57f1804755bda92874515ac19 Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Mon, 11 Apr 2022 10:39:31 +0200 Subject: [PATCH 11/15] add reference to msc3768 Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 70f5bf30128..3bcb18c0ef0 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -71,11 +71,18 @@ For example, Wednesday morning focus time rule: }, ], "actions": [ - "dont_notify" + "dont_notify" // See note below ] } ``` +**`dont_notify` and Do Not Disturb behaviour** +`dont_notify` will stop badges from being +updated in the client during 'do not disturb' hours, so the user will not be +able to locate messages that were silenced when they are back online. +`notify_in_app` as proposed in +[MSC3768](https://github.com/matrix-org/matrix-spec-proposals/pull/3768) should +be used. ## Potential issues - If a user changes timezone their push rules will not automatically update. From 498d7bda9dc70ac7e6dcf9c55aae7cea73a35c2c Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Mon, 11 Apr 2022 10:48:47 +0200 Subject: [PATCH 12/15] formatting Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 3bcb18c0ef0..098fca74bab 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -76,11 +76,11 @@ For example, Wednesday morning focus time rule: } ``` -**`dont_notify` and Do Not Disturb behaviour** +##### `dont_notify` and Do Not Disturb behaviour `dont_notify` will stop badges from being updated in the client during 'do not disturb' hours, so the user will not be able to locate messages that were silenced when they are back online. -`notify_in_app` as proposed in +To silence push notifications but allow discovery of missed messages in app, `notify_in_app` as proposed in [MSC3768](https://github.com/matrix-org/matrix-spec-proposals/pull/3768) should be used. From 96c969159c5e8e0037a56ef2bde4576314e132be Mon Sep 17 00:00:00 2001 From: Kerry Archibald Date: Tue, 12 Apr 2022 11:23:55 +0200 Subject: [PATCH 13/15] add 0 = Sunday to day format Signed-off-by: Kerry Archibald --- proposals/3767-time-based-notification-filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/3767-time-based-notification-filtering.md index 098fca74bab..1c59824b475 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/3767-time-based-notification-filtering.md @@ -24,7 +24,7 @@ to filter based on time of day and day of week. | key | type | value | description | Required | | ---- | ----| ----- | ----------- | -------- | | `time_of_day` | string[] | tuple of `hh:mm` time | Tuple representing start and end of a time interval in which the rule should match. Times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | -| `day_of_week` | number[] | array of integers 1-7 | An array of integers representing days of the week on which the rule should match, where 1 = Monday, 7 = Sunday | **Required** | +| `day_of_week` | number[] | array of integers 0-7 | An array of integers representing days of the week on which the rule should match, where 0 = Sunday, 1 = Monday, 7 = Sunday | **Required** | - `time_of_day` condition is met when the server's timezone-adjusted time is between the values of the tuple, or when no From 33c87e4d7235d562b24e5d3a9fb6f5befea30702 Mon Sep 17 00:00:00 2001 From: hanadi92 Date: Wed, 8 May 2024 18:03:26 +0300 Subject: [PATCH 14/15] add specification for day of week numbering --- ...xxxx-time-based-notification-filtering.md} | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) rename proposals/{3767-time-based-notification-filtering.md => xxxx-time-based-notification-filtering.md} (82%) diff --git a/proposals/3767-time-based-notification-filtering.md b/proposals/xxxx-time-based-notification-filtering.md similarity index 82% rename from proposals/3767-time-based-notification-filtering.md rename to proposals/xxxx-time-based-notification-filtering.md index 1c59824b475..8b454f100d5 100644 --- a/proposals/3767-time-based-notification-filtering.md +++ b/proposals/xxxx-time-based-notification-filtering.md @@ -1,4 +1,4 @@ -# MSC3767: Time based notification filtering +# MSC3XXXX: Time based notification filtering Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to be able to manage the level of noisiness from an application based on day and time. @@ -21,10 +21,10 @@ to filter based on time of day and day of week. **Time matching interval definition** -| key | type | value | description | Required | -| ---- | ----| ----- | ----------- | -------- | +| key | type | value | description | Required | +| ---- | ----|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | | `time_of_day` | string[] | tuple of `hh:mm` time | Tuple representing start and end of a time interval in which the rule should match. Times are [ISO 8601 formatted times](https://en.wikipedia.org/wiki/ISO_8601#:~:text=As%20of%20ISO%208601%2D1,minute%20between%2000%20and%2059.). Times are inclusive | Optional. When omitted all times are matched. | -| `day_of_week` | number[] | array of integers 0-7 | An array of integers representing days of the week on which the rule should match, where 0 = Sunday, 1 = Monday, 7 = Sunday | **Required** | +| `day_of_week` | number[] | array of integers 0-6 | An array of integers representing days of the week on which the rule should match, where 0 = Sunday, 1 = Monday, .., 6 = Saturday | **Required** | - `time_of_day` condition is met when the server's timezone-adjusted time is between the values of the tuple, or when no @@ -49,19 +49,20 @@ to true. }, { // no time_of_day, all day is matched - "day_of_week": [6, 7] // Weekend + "day_of_week": [0, 6] // Weekend } -}, + ] +} ``` -A primary usecase for this condition is creating 'do not disturb' behaviour. +A primary use case for this condition is creating 'do not disturb' behaviour. For example, Wednesday morning focus time rule: ```json5 { "rule_id": ".m.rule.master", "default": true, "enabled": true, - "conditions": [ + "conditions": { "kind": "time_and_day", "timezone": "Europe/Berlin", "intervals": [ @@ -69,7 +70,8 @@ For example, Wednesday morning focus time rule: "time_of_day": ["09:00", "11:00"], "day_of_week": [3] // Wednesday }, - ], + ] + }, "actions": [ "dont_notify" // See note below ] @@ -96,7 +98,8 @@ be configured per device. #### `room_member_count` style comparison ```json5 -"conditions": [ +{ + "conditions": [ { "kind": "time_of_day", "is": ">=18000000" // 17:00 NZST, 5:00 UTC @@ -105,8 +108,8 @@ be configured per device. "kind": "time_of_day", "is": "<=75600000" // 9:00 NZST, 21:00 UTC }, - ] +} ``` As only one rule per `kind` + `rule_id` is allowed and rule conditions are an `AND` this allows only one contiguous range to be defined. This precludes one of the main usecases for the feature - ignoring notifications outside of @@ -127,7 +130,7 @@ days with a DST jump and are less intuitive. ## Unstable prefix -- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.msc3767.time_and_day` +- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.mscxxxx.time_and_day` ## Dependencies None. From db186e19b7b8dcd9ed4e4f3d69f8aa800178e0a5 Mon Sep 17 00:00:00 2001 From: hanadi92 Date: Wed, 8 May 2024 18:30:38 +0300 Subject: [PATCH 15/15] update msc number --- ...filtering.md => 4141-time-based-notification-filtering.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-time-based-notification-filtering.md => 4141-time-based-notification-filtering.md} (98%) diff --git a/proposals/xxxx-time-based-notification-filtering.md b/proposals/4141-time-based-notification-filtering.md similarity index 98% rename from proposals/xxxx-time-based-notification-filtering.md rename to proposals/4141-time-based-notification-filtering.md index 8b454f100d5..c9938fad2ba 100644 --- a/proposals/xxxx-time-based-notification-filtering.md +++ b/proposals/4141-time-based-notification-filtering.md @@ -1,4 +1,4 @@ -# MSC3XXXX: Time based notification filtering +# MSC4141: Time based notification filtering Do not disturb / focus features are becoming standard across operating systems and networking products. Users expect to be able to manage the level of noisiness from an application based on day and time. @@ -130,7 +130,7 @@ days with a DST jump and are less intuitive. ## Unstable prefix -- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.mscxxxx.time_and_day` +- While this MSC is not considered stable `time_and_day` should be referred to as `org.matrix.msc4141.time_and_day` ## Dependencies None.