Add Flow Execution API documentation and update requirements #5692
Conversation
WalkthroughThe changes introduce new Flow Execution API documentation with guides on running user journeys via POST /flow/execute, document flow components returned by the API, add navigation entries to the mkdocs configuration, and relax the mkdocs-include-markdown-plugin version constraint from exact 6.0.0 to >=6.0.0 in two requirements files. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for the Flow Execution API, enabling developers to programmatically execute flows built in the Flow Builder from their custom client applications.
Key changes:
- Added two new documentation pages explaining the Flow Execution API and its component structure
- Updated the flows index page to reference the new API documentation
- Modified dependency versions in requirements.txt files to allow newer versions of mkdocs-include-markdown-plugin
Reviewed Changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| en/includes/guides/flows/index.md | Added introductory paragraph linking to the new Flow Execution API documentation |
| en/includes/guides/flows/flow-execution-api.md | New guide explaining how to use the Flow Execution API to run user journeys |
| en/includes/guides/flows/flow-execution-components.md | New guide documenting the component structure returned by the Flow Execution API |
| en/identity-server/next/docs/guides/flows/flow-execution-api.md | Include file that references the shared flow-execution-api documentation |
| en/identity-server/next/docs/guides/flows/flow-execution-components.md | Include file that references the shared flow-execution-components documentation |
| en/identity-server/next/mkdocs.yml | Added navigation entries for the two new documentation pages |
| en/identity-server/next/requirements.txt | Changed mkdocs-include-markdown-plugin version from exact to minimum version constraint |
| en/asgardeo/requirements.txt | Changed mkdocs-include-markdown-plugin version from exact to minimum version constraint |
| Building with starter templates, widgets, and other components provides complete control over how users interact with the application, all without writing complex code. | ||
|
|
||
| ## Start building flows | ||
| For specific examples of building flows, refer to [Self-registration]({{base_path}}/guides/flows/self-registration/), [Password recovery]({{base_path}}/guides/flows/password-recovery/), and [Invited user registration]({{base_path}}/guides/flows/invited-user-registration/). To execute the flows from a custom client application, see [Use the Flow Execution API]({{base_path}}/guides/flows/flow-execution-api/) and explore the view schema in [Understand Flow Execution components]({{base_path}}/guides/flows/flow-execution-components/). |
There was a problem hiding this comment.
This sentence exceeds the 20-25 word guideline and is difficult to scan. Split into two separate sentences or use a bulleted list to improve readability.
| @@ -0,0 +1,222 @@ | |||
| # Use the Flow Execution API | |||
|
|
|||
| Use the Flow Execution API to run user journeys that you design in the Flow Builder of {{product_name}} directly from your client application. The API returns every step in the flow so that you can render the right experience without embedding the hosted Flow Runner UI. | |||
There was a problem hiding this comment.
The first sentence exceeds the 20-25 word guideline. Consider splitting it: 'Use the Flow Execution API to run user journeys that you design in the Flow Builder. The API lets you execute flows directly from your client application.'
| ## Before you begin | ||
|
|
||
| - [Build and enable the flow]({{base_path}}/guides/flows/build-a-flow/) that you want to expose through your app. | ||
| - Decide how your client persists the `flowId` between requests. Treat it as sensitive data because anyone with the `flowId` can continue the flow. |
There was a problem hiding this comment.
This sentence exceeds the 20-25 word guideline. Split into two sentences: 'Decide how your client persists the flowId between requests. Treat it as sensitive data. Anyone with the flowId can continue the flow.'
| } | ||
| ``` | ||
|
|
||
| - `flowId` uniquely identifies the execution instance. Persist it securely and include it in every subsequent call to the API. |
There was a problem hiding this comment.
This sentence exceeds the 20-25 word guideline. Split into two sentences: 'flowId uniquely identifies the execution instance. Persist it securely. Include it in every subsequent call to the API.'
| - `flowId` uniquely identifies the execution instance. Persist it securely and include it in every subsequent call to the API. | ||
| - `flowStatus` indicates the current status of the flow. Valid values are `INCOMPLETE` and `COMPLETE`. | ||
| - `type` determines how your client should proceed. The `data` object contains the payload that is specific to the `type`. | ||
| - `components` describe the UI blueprint for the step. See [Understand Flow Execution components]({{base_path}}/guides/flows/flow-execution-components/) for details. |
There was a problem hiding this comment.
Avoid using passive verb 'describe'. Rewrite as: 'components provide the UI blueprint for the step.'
| When you receive `type: "REDIRECTION"`: | ||
|
|
||
| 1. Redirect the user agent to `data.url`. | ||
| 2. Handle the callback at the `returnUrl` that you registered in Flow Builder. The callback contains the `flowId` (and any provider-specific data such as `code` or `state`). |
There was a problem hiding this comment.
This sentence exceeds the 20-25 word guideline. Split into two sentences: 'Handle the callback at the returnUrl that you registered in Flow Builder. The callback contains the flowId and any provider-specific data such as code or state.'
|
|
||
| ### Handle internal prompts | ||
|
|
||
| For `type: "INTERNAL_PROMPT"`, inspect `data.requiredParams` to determine the values you must provide. This type is typically used for steps such as sending a magic link or triggering an action. |
There was a problem hiding this comment.
The second sentence exceeds the 20-25 word guideline. Rewrite more concisely: 'This type handles steps such as sending a magic link or triggering an action.'
|
|
||
| The API signals the outcome in `flowStatus`. | ||
|
|
||
| - `COMPLETE`: The flow finished successfully. The `data` object contains the outcome of the flow (for example, a `userId` or `resetTicket`). Use it to move the application forward. |
There was a problem hiding this comment.
This contains multiple sentences that together exceed the guideline. Break into separate bullet points or shorter sentences for better scannability.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
en/asgardeo/requirements.txt (1)
6-17: Note: Pre-existing duplicate dependencies detected.Lines 6 and 10 both pin
mkdocs-redirects==1.2.0, and lines 11 and 17 both pinmkdocs-exclude==1.0.2. While not introduced by this PR, consider cleaning these up in a follow-up.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
en/asgardeo/requirements.txt(1 hunks)en/identity-server/next/docs/guides/flows/flow-execution-api.md(1 hunks)en/identity-server/next/docs/guides/flows/flow-execution-components.md(1 hunks)en/identity-server/next/mkdocs.yml(1 hunks)en/identity-server/next/requirements.txt(1 hunks)en/includes/guides/flows/flow-execution-api.md(1 hunks)en/includes/guides/flows/flow-execution-components.md(1 hunks)en/includes/guides/flows/index.md(1 hunks)
🧰 Additional context used
🪛 GitHub Actions: Markdown Lint
en/includes/guides/flows/flow-execution-api.md
[error] 116-116: markdownlint MD056: Table column count [Expected: 4; Actual: 5; Too many cells, extra data will be missing] in en/includes/guides/flows/flow-execution api.md:116
🪛 GitHub Check: lint
en/includes/guides/flows/flow-execution-api.md
[failure] 116-116: Table column count
en/includes/guides/flows/flow-execution-api.md:116:235 MD056/table-column-count Table column count [Expected: 4; Actual: 5; Too many cells, extra data will be missing] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md056.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: broken-link-checker
- GitHub Check: Vale style check
🔇 Additional comments (8)
en/identity-server/next/docs/guides/flows/flow-execution-components.md (1)
1-1: Clean include pattern for content reuse.The thin wrapper approach with relative include is appropriate for this documentation structure.
en/asgardeo/requirements.txt (1)
15-15: Verify version compatibility for mkdocs-include-markdown-plugin.This mirrors the same version constraint relaxation in en/identity-server/next/requirements.txt. Ensure compatibility before merging.
en/identity-server/next/docs/guides/flows/flow-execution-api.md (1)
1-1: Clean include pattern for content reuse.Consistent with the flow-execution-components.md wrapper pattern.
en/includes/guides/flows/index.md (1)
16-16: Well-integrated documentation links.The new paragraph naturally extends the "Start building flows" section and uses consistent template variable patterns. Link paths align with navigation structure updates.
en/identity-server/next/mkdocs.yml (1)
719-720: Navigation entries properly positioned.The two new Flow Execution guides are correctly placed in the Flows section between existing guides and the Troubleshooting entry. Paths reference the newly added documentation files.
en/includes/guides/flows/flow-execution-components.md (1)
1-67: Well-structured and comprehensive Flow Execution components documentation.The documentation clearly explains component structure, identifier mapping, action handling, and validation rules with practical JSON examples. Tables and code blocks enhance readability.
en/includes/guides/flows/flow-execution-api.md (2)
1-111: Comprehensive and well-organized Flow Execution API documentation.The documentation covers the complete flow lifecycle with clear examples, proper sectioning, and helpful next steps. The curl examples are practical and the response structure is well explained.
119-192: Clear subsection guidance for different response types.The documentation correctly explains how to handle each response type (VIEW, REDIRECTION, WEBAUTHN, INTERNAL_PROMPT) with practical JSON examples and implementation guidance.
| jinja2==3.1.6 | ||
| mkdocs-glightbox==0.3.4 | ||
| mkdocs-include-markdown-plugin==6.0.0 | ||
| mkdocs-include-markdown-plugin>=6.0.0 |
There was a problem hiding this comment.
🧩 Analysis chain
Verify version compatibility for mkdocs-include-markdown-plugin.
Relaxing the constraint from ==6.0.0 to >=6.0.0 allows any version at 6.0.0 or later. Without an upper bound, this could introduce incompatibilities if future versions introduce breaking changes. The new documentation files depend on this plugin's include functionality.
🌐 Web query:
What are the latest versions of mkdocs-include-markdown-plugin and their release notes?
💡 Result:
Latest release: v7.2.0 — released Sep 28, 2025. Change summary: "Add new argument order to sort multiple inclusions." [1][2]
Previous notable release: v7.1.8 — released Sep 26, 2025. Change summary: "Escape substitution placeholders to prevent malformed output in edge cases" (security/bug fix). [1][3]
Sources:
- GitHub releases (mondeja/mkdocs-include-markdown-plugin). [1]
- PyPI release page for mkdocs-include-markdown-plugin (shows uploaded files). [2]
References:
[1] https://github.com/mondeja/mkdocs-include-markdown-plugin/releases (v7.2.0, v7.1.8).
[2] https://pypi.org/project/mkdocs-include-markdown-plugin/ (release files).
[3] GHSA/CVE advisory and release note on GitHub (v7.1.8 fix).
I need to verify whether there are breaking changes between v6.0.0 and v7.x.x, since the major version bump suggests potential incompatibilities.
🏁 Script executed:
#!/bin/bash
# Check GitHub API for release notes between v6.0.0 and v7.2.0
curl -s 'https://api.github.com/repos/mondeja/mkdocs-include-markdown-plugin/releases?per_page=50' | \
python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Recent releases:')
for release in data[:20]:
print(f\" {release['tag_name']}: {release['name'] or release['body'][:100]}\")
" 2>/dev/null || echo "API query completed"Length of output: 356
🏁 Script executed:
#!/bin/bash
# Get full release notes for v7.0.0 to check for breaking changes
curl -s 'https://api.github.com/repos/mondeja/mkdocs-include-markdown-plugin/releases/tags/v7.0.0' | \
python3 -c "
import json, sys
data = json.load(sys.stdin)
print('v7.0.0 Release Notes:')
print(data.get('body', 'No release notes available'))
" 2>/dev/nullLength of output: 1241
Specify an upper version bound for mkdocs-include-markdown-plugin to prevent breaking changes.
v7.0.0 introduced breaking changes including comments turned off by default (previously true) and indented code block formatting requirements that must conform to CommonMark specification. The relaxed constraint >=6.0.0 allows installation of v7.x.x, which could break documentation builds if those features are relied upon.
Recommend either:
- Change constraint to
>=6.0.0,<7.0.0to pin to v6.x releases, or - Verify the new documentation is compatible with v7.x and update the constraint accordingly
🤖 Prompt for AI Agents
In en/identity-server/next/requirements.txt at line 14, the dependency
mkdocs-include-markdown-plugin is allowed as ">=6.0.0" which permits v7.x and
its breaking changes; restrict the version range to prevent accidental upgrade
to v7 (e.g., change to ">=6.0.0,<7.0.0") unless you've audited and updated docs
to be compatible with v7, in which case explicitly set the tested v7 constraint
or keep a tighter pinned range.
| | `type` | When you receive it | Expected client action | Typical data fields | | ||
| |--------|---------------------|------------------------|---------------------| | ||
| | `VIEW` | The server needs the user to interact with a UI form, list, or confirmation step. | Render the view described in `data.components`, capture user input, and send it back with the provided action identifier. | `components`, `requiredParams` | | ||
| | `REDIRECTION` | A third-party system must complete part of the flow (for example, identity verification or payment). | Redirect the browser or web view to `data.url` and resume the flow from your callback endpoint. | `url` | | ||
| | `WEBAUTHN` | The user must complete a WebAuthn ceremony. | Call `navigator.credentials.{create|get}` with the information in `data.publicKeyCredentialCreation` or `data.publicKeyCredentialRequest`, then submit the encoded response. | `publicKeyCredentialCreation` | | ||
| | `INTERNAL_PROMPT` | The client app, not the end user, must respond. | Call the API with the requested parameters. | `requiredParams` | |
There was a problem hiding this comment.
BLOCKER: Fix markdown lint error MD056 - table column count mismatch.
The pipeline reports that line 116 has 5 cells but only 4 columns are defined in the header. The table appears to have 4 columns visually, but the linter is detecting a mismatch. This must be resolved before merge.
Verify the table format and ensure all row cells match the header column count:
| `type` | When you receive it | Expected client action | Typical data fields |
|--------|---------------------|------------------------|---------------------|
| `VIEW` | ... | ... | ... |
| `REDIRECTION` | ... | ... | ... |
| `WEBAUTHN` | ... | ... | ... |
| `INTERNAL_PROMPT` | ... | ... | ... |Ensure there are exactly 4 pipe-separated cells in each row.
🧰 Tools
🪛 GitHub Actions: Markdown Lint
[error] 116-116: markdownlint MD056: Table column count [Expected: 4; Actual: 5; Too many cells, extra data will be missing] in en/includes/guides/flows/flow-execution api.md:116
🪛 GitHub Check: lint
[failure] 116-116: Table column count
en/includes/guides/flows/flow-execution-api.md:116:235 MD056/table-column-count Table column count [Expected: 4; Actual: 5; Too many cells, extra data will be missing] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md056.md
🤖 Prompt for AI Agents
en/includes/guides/flows/flow-execution-api.md lines 112-117: the WEBAUTHN table
row is being parsed as 5 cells because the code span
navigator.credentials.{create|get} contains an unescaped pipe; fix the row so
each row has exactly four pipe-separated cells by removing or escaping the pipe
inside the code span (e.g., use "create or get" or replace '|' with | or
otherwise ensure the code cell contains no unescaped '|'), then verify all other
rows have exactly four cells.
1 participant
$subject
Summary by CodeRabbit
Documentation
Chores