elastic / elastic/docs-content
[Workflows] Document how tzid interacts with dtstart for scheduled workflow triggers
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
## Description
The scheduled workflow trigger docs should clarify how `rrule.tzid` is applied when `dtstart` includes an explicit timezone, especially when the timestamp uses `Z`.
A user expected this configuration to run at 4:00 PM America/Chicago:
```yaml
triggers:
- type: scheduled
with:
rrule:
freq: DAILY
interval: 1
tzid: America/Chicago
dtstart: 2026-05-11T16:00:00Z
```
Instead, it fires at 11:00 AM Central because `2026-05-11T16:00:00Z` is parsed as 4:00 PM UTC. `tzid: America/Chicago` controls the recurrence timezone, but does not reinterpret a `Z` timestamp as local time.
## Context
Slack discussion: https://elasticstack.slack.com/archives/C08V1LBRA8Z/p1784124464138809?thread_ts=1784065062.352939&cid=C08V1LBRA8Z
## Current Behavior
The docs do not clearly explain the interaction between `dtstart`, explicit timestamp offsets, `Z`, and `tzid`. This can lead users to assume that `tzid` reinterprets `dtstart` as local time.
## Proposed Solution
Update the scheduled workflow trigger RRULE documentation to:
- Explain that `dtstart` is parsed according to the timezone or offset in the timestamp first.
- Clarify that `Z` means UTC.
- Explain that `tzid` controls recurrence calculation and keeps future runs aligned to that timezone, including DST behavior.
- Add an example for scheduling a workflow at 4:00 PM America/Chicago, such as:
- `dtstart: 2026-05-11T21:00:00Z`
- or `dtstart: 2026-05-11T16:00:00-05:00`
- with `tzid: America/Chicago`
- Consider adding a short note or warning near the scheduled trigger RRULE docs.
## Impact
This will make scheduled workflow examples less ambiguous and help users avoid timezone-related scheduling mistakes.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.