elastic / elastic/docs-content

[Workflows] Document how tzid interacts with dtstart for scheduled workflow triggers

Open
#7,384 1 comment 2 reactions 1 assignee Claimed by @nastasha-solomon View on GitHub
agentic-workflows documentation Team:Docs Visualizations & Analysis Team:SKI
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.