Skip to content
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions docs/jobs/state.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,19 +148,32 @@ The input state looks like this:

### Cron triggered runs

On the platform, when a Run is triggered by a cron job, the input state will the
final output state of the **last succesful run** for this workflow. This allows
each subsequent run to _know_ about previous runs—i.e., you can pass information
from one run to another even if they happen days apart.
#### What are cron jobs?
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this appropriate for this section of docs?

We're deep in an explanation of state here. I don't think this is the time or place to explain what a cron job is. We could add a single sentence definition, but otherwise we should link to the full cron docs.

Otherwise I think this is just a distraction from the discussion on this page.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@josephjclark In the link you have shared, the explanation still links to the docs we are currently updating to explain about state in cron jobs.

If readers are being directed to these docs, should we go deeper into state in cron jobs?

Screenshot 2025-10-13 at 21 49 01

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But that's only for state specifically.

"What is a cron job and how does it work" needs to be answered on build/triggers. I think those docs are fine right now but I'm open to discussing improvements.

"What is the input state passed into my cron job" needs to be explained in-depth in jobs/state. This stuff about "the output of the trigger step will be the input to the next step". It might need a concerete worked example to explain it.

build/triggers can have a single-sentence explanation of how state works, then link to jobs/state for more detail

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have explained more about the state in jobs/state with the new discovery of how state works in cronjobs

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hunterachieng this still isn't right :(

The state.md page does NOT explain what Webhook or Kafka triggered runs are. Why are we treating Cron runs differently?

This page is explaining STATE. Not CRON. It assumes you know what a cron triggered run is because why else would you be here?

A single sentence explanation is maybe OK but honestly I think this whole what are cron jobs section needs to go. You can link to build/triggers if you really want.


A **cron job** is a time-based scheduler that automatically runs your workflow at specified intervals. Think of it like setting an alarm clock for your workflow. It will run automatically at the times you configure, whether that's every hour, daily at 9 AM, or on the first day of each month.


#### How cron input state works

When a run is triggered by a cron job, the input state will be the final output state of the **last successful run** for this workflow. This allows each subsequent run to _know_ about previous runs. In other words, you can pass information from one run to another even if they happen days apart.

```js
{
...finalStateOfLastSuccessfulRun,
}
```

If this is the first time the workflow has run, the initial state will simply by
an empty Javascript object: `{}`
**Example scenario**: If your workflow fetches new records and the last run processed records up to ID 1000, the next cron run will start with that information and can fetch records starting from ID 1001.

If this is the first time the workflow has run, the initial state will simply be an empty JavaScript object: `{}`

#### Overriding cron input

You can always **manually run** a cron-triggered workflow with:
- **Empty input**: `{}` - starts fresh without previous state.
- If your manual run succeeds, the next scheduled cron run will start with whatever output state your manual run produced.
- **Custom input**: Your own data to test specific scenarios.
- **Default input**: Uses the same input as the scheduled runs.

## Input & output state for steps

Expand Down