Scheduled Action Interval first run date calculation

antonio.perez · August 12, 2024, 2:18pm

I think this issue answers both of your questions,

[ Documentation request ] Schedules: Add more details about `phase`

opened 04:41PM - 02 Jan 24 UTC

# Brief description The Schedules documentation mention that a schedule spec may… be defined as "a simple interval, like "every 30 minutes" (aligned to start at the Unix epoch, and optionally including a phase offset)". The "alignment to Unix epoch" and "phase offset" concepts mentioned here are difficult to understand for some users, and it is non-obvious to most users how this `phase` parameter has to be calculated so that an interval spec fires exactly at a predetermined date and time (i.e. they are very likely to do this by trial and error). We should provide some more explanation regarding these concepts, and add an example of how to calculate the phase based on a predetermined date and time. # Your recommended content Extracted this from a recent [Slack conversation](https://temporalio.slack.com/archives/C046BRWDV2R/p1703701880291939?thread_ts=1703687861.823299&cid=C046BRWDV2R). This needs some polishing, but I think the technical content and the example should be included in documentation. > Timestamps are measured in seconds (or actually, milliseconds, but let say seconds for simplicity) since January 1st 1970. > > Now, 7 days is 604,800 seconds. 5 days is 432,000. > > The schedule fires when the following holds: > ``` > ((currentTimestampUTC - phase) % interval) == 0 > ``` > > So for example, using an interval of 7 days and a phase of 0, that equation holds on December 28th 2023, at midnight UTC: > ``` > ((1703721600 - 0) % 604800) = 0 > ``` > > For an interval of 5 days and a phase of 0, it holds for December 29th 2023: > ``` > ((1703808000 - 0) % 432000) = 0 > ``` > > User: What value would you recommend I use for phase so that it actually starts in 5 days or 7 days when that’s the value set ? > > You will need to calculate that by yourself. Take the timestamp of any moment where you want your schedule to execute, then calculate the following: > ``` > referenceTimestampUTC % interval = phase > ``` > > For example, if I want a schedule that will fire every 7 days, including Jan 1st 2024 at midnight UTC, I would do: > ``` > UNIX Timestamp of 2024-01-01T00:00:00 UTC => 1704067200 > Interval of 7 days => 604800 > > phase = 1704067200 % 604800 => 345600 > ``` > > So I set my schedule interval to 604800s (7 days) and phase to 345600s (4 days), and I get: > (image showing upcoming schedule execution on Jan 1st, 2024, then Jan 8th...)

Let me know if it helps,
Antonio

Topic		Replies	Views
Clarification of Temporal Schedule behaviour while using ScheduleInterval Community Support	1	204	October 23, 2024
Schedules API Support Monthly and Weekly Intervals Community Support feature-request	1	64	July 20, 2025
How to combine interval and calendar spec in Temporal Schedule? Community Support java-sdk	3	1038	June 7, 2023
Generate a list of upcoming runs for a schedule outside of Temporal context Community Support typescript-sdk	0	20	November 22, 2024
Simple Scheduling in Java-sdk Community Support java-sdk	8	2379	July 10, 2023

Scheduled Action Interval first run date calculation

Related topics