Update flow docs. #5646
Update flow docs. #5646
Conversation
There was a problem hiding this comment.
Pull Request Overview
This pull request comprehensively updates the flow documentation to improve clarity, usability, and coverage. The changes focus on rewriting core guides with step-by-step instructions, adding flow inheritance documentation for sub-organizations, and introducing a new troubleshooting section. The updates follow a more task-oriented approach with clearer action-first writing and better organization.
Key changes:
- Major rewrite of flow builder guides with improved structure and step-by-step instructions
- Introduction of troubleshooting guide for common Flow Builder errors
- Updated sample scenarios across all flow types with clearer verification methods
Reviewed Changes
Copilot reviewed 8 out of 31 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| en/includes/guides/flows/trouble-shooting.md | New troubleshooting guide documenting common Flow Builder validation errors and their solutions |
| en/includes/guides/flows/self-registration.md | Rewritten to use Magic Link verification instead of SMS OTP, with simplified step-by-step instructions and expanded reference section |
| en/includes/guides/flows/password-recovery.md | Updated sample use case to use SMS OTP, streamlined instructions, and added flow completion properties reference |
| en/includes/guides/flows/invited-user-registration.md | Changed from SMS OTP to Email OTP verification with clearer configuration steps and new reference section |
| en/includes/guides/flows/index.md | Improved overview with clearer descriptions and added "Next steps" section for better navigation |
| en/includes/guides/flows/build-a-flow.md | Major rewrite with expanded explanations of flow elements, inheritance for sub-organizations, and improved structure |
| en/identity-server/next/mkdocs.yml | Added troubleshooting guide to navigation structure |
| en/identity-server/next/docs/guides/flows/trouble-shooting.md | Include file pointer for troubleshooting content |
en/identity-server/next/mkdocs.yml
Outdated
| - Self Registration: guides/flows/self-registration.md | ||
| - Password Recovery: guides/flows/password-recovery.md | ||
| - Invited User Registration: guides/flows/invited-user-registration.md | ||
| - Troubleshooting: guides/flows/trouble-shooting.md |
There was a problem hiding this comment.
file name should be one word. troubleshooting.md
| If you disable a customized flow, your users will automatically continue with the default experience until you’re ready to publish it again. | ||
|
|
||
| ## Reference: Flow elements | ||
| ## Flow inheritance for sub organizations |
There was a problem hiding this comment.
This needs to move from this doc to the organizations section. We have a separate section in Organizations to explain how inheritance work. This info is irrelevant to the flow doc.
There was a problem hiding this comment.
| When using a connection based sign up option (such as Google or Microsoft), configure the authorized redirect URL as: `https://accounts.asgardeo.io/t/{tenant-domain}/accounts/register` | ||
| When using a connection based sign up option (such as Google or Microsoft), configure the authorized redirect URL as: `https://{is_host}/t/{tenant-domain}/accounts/register` | ||
|
|
||
| ## Reference |
There was a problem hiding this comment.
The flow completion properties shouldn't come as a reference. Let's make this a step (before enabling a flow step).
Step x : Configure flow completion properties
Improved some sections in the intro and added extra info on the flow behavior when enabled/disabled
minor improvements to the troubleshooting doc
2 participants
Related Issues
Flowsare inherited by child orgs and ability to override them in child orgs is missing product-is#25326This pull request updates and expands the documentation for user flows in the identity server, focusing on clarity, usability, and new features. The changes include major rewrites for the flow builder guides, improved organization and navigation, and more practical, step-by-step instructions for building and customizing flows. The documentation now better explains flow inheritance, provides updated sample scenarios, and introduces a troubleshooting section.
Documentation improvements and expanded guides:
build-a-flow.mdto clarify the flow builder's purpose, add step-by-step instructions for creating, enabling, and inheriting flows, and provide detailed explanations of flow elements (steps, widgets, components). Flow inheritance for sub-organizations is now documented, including how to customize or revert flows for child orgs.index.mdto provide a clearer overview of flows, improve descriptions of user journeys, and add a "Next steps" section for easier navigation to relevant guides.invited-user-registration.mdto use email OTP for identity verification (instead of SMS), clarify instructions for building the flow, and update screenshots and sample scenarios for accuracy and security.password-recovery.mdfor improved readability.Navigation and structure:
mkdocs.yml, making it easier for users to find help when encountering issues with flows.