From bc7722178f47f112da5656dc435c2296839e9871 Mon Sep 17 00:00:00 2001 From: kschneider84 <77678452+kschneider84@users.noreply.github.com> Date: Thu, 20 Aug 2026 10:59:42 +0200 Subject: [PATCH 1/3] Add new study expressions --- content/docs/study-rules-editor/study-rules.mdx | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/content/docs/study-rules-editor/study-rules.mdx b/content/docs/study-rules-editor/study-rules.mdx index cb46efd..bc3f52f 100644 --- a/content/docs/study-rules-editor/study-rules.mdx +++ b/content/docs/study-rules-editor/study-rules.mdx @@ -330,19 +330,29 @@ Some expressions return numbers and dates that can e.g. be used for comparisons. #### 1. **Get ISO week for timestamp** * **Meaning:** Returns the ISO week number for a given timestamp. -* **Use Case:** Helpful when rules depend on the calendar week (e.g., weekly schedules or reporting). +* **Use Case:** Helpful when rules depend on the calendar week (e.g., weekly schedules or reporting). Use it whenever a rule needs a stable weekly boundary, for example, to query responses submitted since the beginning of the current week. * **How it works:** Provide a timestamp. -#### 2. **Get timestamp for next occurrence of an ISO week** +#### 2. **Get timestamp for start of ISO week** +* **Meaning:** Calculates the timestamp for the start of the ISO week containing a given timestamp. +* **Use Case:** Useful when rules need to reference the exact beginning of a calendar week, e.g., for weekly reporting periods. +* **How it works:** Optionally provide a timestamp; the expression returns the timestamp for the start of its ISO week. If no timestamp is provided, the current timestamp is used. + +#### 3. **Get timestamp for next occurrence of an ISO week** * **Meaning:** Calculates the timestamp for the next occurrence of a specified ISO week number. * **Use Case:** Useful for scheduling events or reminders based on calendar weeks. * **How it works:** Provide an ISO week number (e.g., 42), and the expression returns the timestamp for the start of that week in the current or next year. -#### 3. **Get timestamp for next occurrence of a start of month** +#### 4. **Get timestamp for next occurrence of a start of month** * **Meaning:** Returns the timestamp for the next start of a specified month. * **Use Case:** Ideal for monthly scheduling, e.g., sending out surveys at the beginning of each month. * **How it works:** Specify the month (e.g., March), and the expression calculates the timestamp for the next occurrence of the first day of that month. +#### 5. **Get timestamp difference** +* **Meaning:** Calculates the difference between two timestamps. +* **Use Case:** Useful for measuring durations, e.g., time elapsed since the last submission or time remaining until a deadline. +* **How it works:** Provide two timestamps; the expression returns the difference in seconds between them. The result can be negative if the first timestamp is earlier than the second. + ### Response Checkers From 0387a3c634810965b8132ce1cd98f5ec2e115533 Mon Sep 17 00:00:00 2001 From: kschneider84 <77678452+kschneider84@users.noreply.github.com> Date: Wed, 26 Aug 2026 08:19:46 +0200 Subject: [PATCH 2/3] Improve and specify date helper expressions descriptions --- content/docs/study-rules-editor/study-rules.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/docs/study-rules-editor/study-rules.mdx b/content/docs/study-rules-editor/study-rules.mdx index bc3f52f..9611c64 100644 --- a/content/docs/study-rules-editor/study-rules.mdx +++ b/content/docs/study-rules-editor/study-rules.mdx @@ -330,28 +330,28 @@ Some expressions return numbers and dates that can e.g. be used for comparisons. #### 1. **Get ISO week for timestamp** * **Meaning:** Returns the ISO week number for a given timestamp. -* **Use Case:** Helpful when rules depend on the calendar week (e.g., weekly schedules or reporting). Use it whenever a rule needs a stable weekly boundary, for example, to query responses submitted since the beginning of the current week. +* **Use Case:** Helpful when rules depend on the calendar week (e.g., weekly schedules or reporting). * **How it works:** Provide a timestamp. #### 2. **Get timestamp for start of ISO week** * **Meaning:** Calculates the timestamp for the start of the ISO week containing a given timestamp. -* **Use Case:** Useful when rules need to reference the exact beginning of a calendar week, e.g., for weekly reporting periods. -* **How it works:** Optionally provide a timestamp; the expression returns the timestamp for the start of its ISO week. If no timestamp is provided, the current timestamp is used. +* **Use Case:** Useful whenever a rule needs a stable weekly boundary, e.g., to query responses submitted since the beginning of the current week. +* **How it works:** Optionally provide a timestamp. If no timestamp is provided, the current timestamp is used. #### 3. **Get timestamp for next occurrence of an ISO week** * **Meaning:** Calculates the timestamp for the next occurrence of a specified ISO week number. * **Use Case:** Useful for scheduling events or reminders based on calendar weeks. -* **How it works:** Provide an ISO week number (e.g., 42), and the expression returns the timestamp for the start of that week in the current or next year. +* **How it works:** Provide an ISO week number (e.g., 42) and optionally a reference timestamp. If no reference timestamp is provided, the current timestamp is used. Since not every year has an ISO week 53, requesting week 53 can resolve to a year several years in the future rather than the current or next year. #### 4. **Get timestamp for next occurrence of a start of month** * **Meaning:** Returns the timestamp for the next start of a specified month. * **Use Case:** Ideal for monthly scheduling, e.g., sending out surveys at the beginning of each month. -* **How it works:** Specify the month (e.g., March), and the expression calculates the timestamp for the next occurrence of the first day of that month. +* **How it works:** Specify the month (e.g., March) and optionally a reference timestamp. If no reference timestamp is provided, the current timestamp is used. If the reference time falls within the specified month (except for its exact first instant, midnight on the 1st), the next occurrence a year later is returned. #### 5. **Get timestamp difference** -* **Meaning:** Calculates the difference between two timestamps. +* **Meaning:** Calculates the difference between two timestamps, in seconds. * **Use Case:** Useful for measuring durations, e.g., time elapsed since the last submission or time remaining until a deadline. -* **How it works:** Provide two timestamps; the expression returns the difference in seconds between them. The result can be negative if the first timestamp is earlier than the second. +* **How it works:** Provide two timestamps. The result can be negative if the first timestamp is earlier than the second. ### Response Checkers From 96e26f40ee0862d910316040077cba95a0cb5122 Mon Sep 17 00:00:00 2001 From: kschneider84 <77678452+kschneider84@users.noreply.github.com> Date: Thu, 27 Aug 2026 10:07:26 +0200 Subject: [PATCH 3/3] Add infos about timezone configurations --- content/docs/study-rules-editor/study-rules.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/docs/study-rules-editor/study-rules.mdx b/content/docs/study-rules-editor/study-rules.mdx index 9611c64..28b38d0 100644 --- a/content/docs/study-rules-editor/study-rules.mdx +++ b/content/docs/study-rules-editor/study-rules.mdx @@ -238,6 +238,8 @@ Use these when you want rules to trigger only if study data falls inside or outs Some expressions return numbers and dates that can e.g. be used for comparisons. Note that Dates are always represented in **Unix timestamp format**, which means they are also integer numbers. +Since a Unix timestamp itself has no timezone, any expression that derives calendar-based information from it (e.g., the start of a day, week, or month) does so using the **local timezone of the server process** running the study engine, not the participant's timezone. + ### Variables #### 1. **Date picker**