Skip to content

[DON'T MERGE] docs: Refactor Workflow documentation #539

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.

Sign up for GitHub

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

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[DON'T MERGE] docs: Refactor Workflow documentation #539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9274bea
Refactor Workflow documentation.
mehmettokgoz Sep 22, 2025
f30107b
WIP
mehmettokgoz Sep 26, 2025
b1a5565
fix: rm llm page/error, add missing label param
CahidArda Sep 29, 2025
5290b81
fix: add section about workflow stuck
CahidArda Sep 29, 2025
d3dfdb4
fix: flow control types
CahidArda Sep 29, 2025
4d6d035
fix: fmt, links, params
CahidArda Sep 29, 2025
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
8 changes: 8 additions & 0 deletions _snippets/qstash-common-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,3 +117,11 @@ We will strip this prefix and forward the header to the callback destination.

example: "Upstash-Failure-Callback-Forward-My-Header: my-value" -> "My-Header: my-value"
</ParamField>

<ParamField header="Upstash-Label" type="string" >
Assign a label to the message for filtering

Multiple messages can have the same label

Example: "Upstash-Label: user-signup"
</ParamField>
2 changes: 1 addition & 1 deletion _snippets/qstash-message-type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,5 +59,5 @@
</ResponseField>

<ResponseField name="label" type="string">
The label of the message assigned by the user.
The label of the message assigned in publish request
</ResponseField>
2 changes: 1 addition & 1 deletion _snippets/qstash/waiter.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<ResponseField name="Waiter" type="">
<ResponseField name="Waiter" type="object">
<Expandable>
<ResponseField name="url" type="string" required>
URL to call upon notify
Expand Down
274 changes: 274 additions & 0 deletions _snippets/workflow/logs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,274 @@
<ResponseField name="runs" type="Array">
<Expandable>
<ResponseField name="workflowRunId" type="string">
The ID of the workflow run.
</ResponseField>

<ResponseField name="workflowUrl" type="string">
The URL address of the workflow endpoint.
</ResponseField>

<ResponseField name="workflowState" type="string">
The current state of the workflow run at this point in time

| Value | Description |
| -------------- | -------------------------------------------------------------- |
| `RUN_STARTED` | The workflow has started to run and currently in progress. |
| `RUN_SUCCESS` | The workflow run has completed succesfully. |
| `RUN_FAILED` | Some errors has occured and workflow failed after all retries. |
| `RUN_CANCELED` | The workflow run has canceled upon user request. |

</ResponseField>

<ResponseField name="workflowCreatedAt" type="number">
The Unix timestamp (in milliseconds) when the workflow run started.
</ResponseField>

<ResponseField name="workflowRunCompletedAt" type="string">
The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.
</ResponseField>

<ResponseField name="label" type="string">
The label of the run assigned by the user on trigger.
</ResponseField>

<ResponseField name="failureFunction" type="FailureFunction">
The details of the failure callback message, if a failure function was defined for the workflow.

<Expandable defaultClosed>
<ResponseField name="messageId" type="string">
The ID of the failure callback message
</ResponseField>

<ResponseField name="url" type="string">
The URL address of the failure function
</ResponseField>

<ResponseField name="state" type="string">
The state of the failure callback

| Value |
| --------------------- |
| `CALLBACK_INPROGRESS` |
| `CALLBACK_SUCCESS` |
| `CALLBACK_FAIL` |

</ResponseField>

<ResponseField name="failHeaders" type="string">
The HTTP headers of the message that triggered the failure function.
</ResponseField>

<ResponseField name="failStatus" type="string">
The HTTP response status of the message that triggered the failure function.
</ResponseField>

<ResponseField name="failResponse" type="string">
The response body of the message that triggered the failure function.
</ResponseField>

<ResponseField name="dlqId" type="string">
The DLQ ID of the workflow run.
</ResponseField>

<ResponseField name="responseBody" type="string">
Response body of the failure function/url.
When [failure function](https://upstash.com/docs/workflow/basics/serve#failurefunction) is used, this contains
the returned message from the failure function.
</ResponseField>

<ResponseField name="responseHeaders" type="array">
Reponse headers of the failure function/url. This is valuable when the call to run the failure function/url is rejected
because of a platform limit.
</ResponseField>

<ResponseField name="responseStatus" type="int">
Reponse status of the failure function/url. This is valuable when the call to run the failure function/url is rejected
because of a platform limit.
</ResponseField>

<ResponseField name="errors" type="array">
A call to failure url/function can be retried as `maxRetries` time. This array contains errors of all retry
attempts.

<Expandable>
<ResponseField name="status" type="int">
Response status of the endpoint that caused the error
</ResponseField>

<ResponseField name="headers" type="array">
Response Headers of the endpoint that caused the error
</ResponseField>

<ResponseField name="body" type="string">
Response Body of the endpoint that caused the error if available
</ResponseField>

<ResponseField name="error" type="string">
An error message that happened before/after calling the user's endpoint.
</ResponseField>

<ResponseField name="time" type="int64">
The time of the error happened in Unix time milliseconds
</ResponseField>

</Expandable>
</ResponseField>

<ResponseField name="maxRetries" type="string">
Max number of retries configured when seeing an error.
</ResponseField>
</Expandable>
</ResponseField>

<ResponseField name="steps" type="Array">

<Expandable defaultOpen>
<ResponseField name="type" type="string" >

The type of grouped steps

| Value | Description |
| ------------ | ---------------------------------------------------------------- |
| `sequential` | Indicates only one step is excuted sequentially |
| `parallel` | Indicates multiple steps being executed in parallel. |
| `next` | Indicates there is information about currently executing step(s) |

</ResponseField>

<ResponseField name="steps" type="Array">
<Expandable defaultClosed>
<ResponseField name="stepId" type="number" >
The ID of the step which increases monotonically.
</ResponseField>

<ResponseField name="stepName" type="string" >
The name of the step. It is specified in workflow by user.
</ResponseField>

<ResponseField name="stepType" type="string" >
Execution type of the step which indicates type of the context function.

| Value | Function |
| ------------ | -------------------------------------------- |
| `Initial` | The default step which created automatically |
| `Run` | context.run() |
| `Call` | context.call() |
| `SleepFor` | context.sleepFor() |
| `SleepUntil` | context.sleepUntil() |
| `Wait` | context.waitForEvent() |
| `Notify` | context.notify() |
| `Invoke` | context.invoke() |
</ResponseField>

<ResponseField name="messageId" type="string" >
The ID of the message associated with this step.
</ResponseField>

<ResponseField name="out" type="string" >
The output returned by the step
</ResponseField>

<ResponseField name="concurrent" type="string" >
The total number of concurrent steps that is running alongside this step
</ResponseField>

<ResponseField name="state" type="string" >
The state of this step at this point in time

| Value |
| --------------- |
| `STEP_SUCCESS` |
| `STEP_RETRY` |
| `STEP_FAILED` |
| `STEP_CANCELED` |
</ResponseField>

<ResponseField name="createdAt" type="string" >
The unix timestamp in milliseconds when the message associated with this step has created.
</ResponseField>

<ResponseField name="nextDeliveryTime" type="number">
The unix timestamp in milliseconds when this step will be retried.
This is set only when the step state is `STEP_RETRY`
</ResponseField>

**The following fields are set only when a specific type of step is executing. These fields are not available for all step types.**

<ResponseField name="sleepFor" type="string" >
The duration in milliseconds which step will sleep. Only set if stepType is `SleepFor`.
</ResponseField>

<ResponseField name="sleepUntil" type="string" >
The unix timestamp (in milliseconds) which step will sleep until. Only set if stepType is `SleepUntil`.
</ResponseField>

<ResponseField name="waitEventId" type="string" >
The event id of the wait step. Only set if stepType is `Wait`.
</ResponseField>

<ResponseField name="waitTimeoutDeadline" type="string" >
The unix timestamp (in milliseconds) when the wait will time out.
</ResponseField>

<ResponseField name="waitTimeoutDuration" type="string">
The duration of timeout in human readable format (e.g. 120s, 1m, 1h).
</ResponseField>

<ResponseField name="waitTimeout" type="string" >
Set to true if this step is cause of a wait timeout rather than notifying the waiter.
</ResponseField>

<ResponseField name="callUrl" type="string">
The URL of the external address. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callMethod" type="string">
The HTTP method of the request sent to the external address. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callHeaders" type="string">
The HTTP headers of the request sent to the external address. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callBody" type="string">
The body of the request sent to the external address. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callResponseStatus" type="number">
The HTTP status returned by the external call. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callResponseBody" type="string">
The body returned by the external call. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="callResponseHeaders" type="array">
The HTTP headers returned by the external call. Available only if stepType is `Call`.
</ResponseField>

<ResponseField name="invokedWorkflowRunId" type="string">
The ID of the invoked workflow run if this step is an invoke step.
</ResponseField>

<ResponseField name="invokedWorkflowUrl" type="string">
The URL address of the workflow server of invoked workflow run if this step is an invoke step.
</ResponseField>

<ResponseField name="invokedWorkflowCreatedAt" type="number">
The Unix timestamp (in milliseconds) when the invoked workflow was started if this step is an invoke step.
</ResponseField>

<ResponseField name="invokedWorkflowRunBody" type="string">
The body passed to the invoked workflow if this step is an invoke step.
</ResponseField>

<ResponseField name="invokedWorkflowRunHeaders" type="string">
The HTTP headers passed to invoked workflow if this step is an invoke step.
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
</Expandable>
</ResponseField>
6 changes: 3 additions & 3 deletions _snippets/workflow/workflow-dlq-message-type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,13 @@
Flow control key (if set).
</ResponseField>
<ResponseField name="rate" type="integer">
Rate limit (if set).
Flow control rate limit (if set).
</ResponseField>
<ResponseField name="parallelism" type="integer">
Parallelism (if set).
Flow control parallelism (if set).
</ResponseField>
<ResponseField name="period" type="integer">
Period (if set).
Flow control period (if set).
</ResponseField>
<ResponseField name="responseStatus" type="integer">
HTTP response status code of the last failed delivery attempt.
Expand Down
Loading