-
Notifications
You must be signed in to change notification settings - Fork 18
docs: update cron trigger runs description #711
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -148,19 +148,31 @@ 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? | ||
|
|
||
| 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** of the first step in the 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. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Didn't we agree this was incorrect? It's the state of the cron step that goes into the next workflow - not the FINAL step. See slack thread and pick up the conversation there if you're not sure. You should be able to easily test the actual behaviour against the app.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @josephjclark For this, I edited as per the slack thread which stated that it picks the next input from the last successful run of the first step |
||
|
|
||
| ```js | ||
| { | ||
| ...finalStateOfLastSuccessfulRun, | ||
| ...finalStateOfLastSuccessfulRunOfStep1, | ||
hunterachieng marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| ``` | ||
|
|
||
| If this is the first time the workflow has run, the initial state will simply by | ||
| an empty Javascript object: `{}` | ||
| **Example scenario**: You have a **daily sync at 9 AM** with a workflow that has 3 steps: (1) fetch patient records, (2) transform data, (3) send to database. On Monday, the **first step** processes records up to ID 1000 and outputs `{ lastProcessedId: 1000 }`. Even though steps 2 and 3 modify the state further, only the **first step's output** gets saved for the next cron run. On Tuesday at 9 AM, the cron job starts again with `{ lastProcessedId: 1000 }` from Monday's first step, so it knows to 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 | ||
hunterachieng marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| You can always manually run a cron-triggered workflow with: | ||
| - **Empty input**: `{}` - starts fresh without previous state. | ||
| - **Custom input**: Your own data to test specific scenarios. | ||
| - **Default input**: Uses the same input as the scheduled runs. | ||
|
|
||
| ## Input & output state for steps | ||
|
|
||
|
|
||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This feels like the main docs? https://docs.openfn.org/documentation/build/triggers#cron-triggers-formerly-timers
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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/triggerscan have a single-sentence explanation of how state works, then link tojobs/statefor more detailThere was a problem hiding this comment.
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/statewith the new discovery of how state works in cronjobsThere was a problem hiding this comment.
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.mdpage 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 jobssection needs to go. You can link tobuild/triggersif you really want.