## Overview

The Forms Wizard Analysis widget checks whether the Forms Wizard has all the necessary configurations to be able to run. It serves as a validation and quality assurance tool for Forms Wizard administrators. It automatically analyzes wizard configuration and displays validation results, highlighting both successful checks and potential problems that could prevent the wizard from functioning correctly. The widget helps administrators catch configuration errors early in the wizard design process and provides real-time feedback as configuration changes are made.

The widget can only be embedded on pages of type `cf.cplace.formsWizard.wizard` (the Forms Wizard configuration page).

## Validation Checks

The widget performs seven core validation checks:

1. **Start Step Validation** - Verifies a start step is configured
2. **Step Reachability** - Ensures all configured steps can be reached during wizard execution
3. **Final Step Validation** - Confirms at least one final step is configured
4. **Leaf Node Validation** - Checks that all steps without next steps are marked as final steps
5. **Final Step Integrity** - Verifies that final steps do not have next steps configured
6. **External Access Configuration** - Validates external access settings when the wizard is configured for external use
7. **Skip Configuration Validation** - Validates "skip to" step configurations

Results display in a list format with visual indicators showing valid checks (styled with `valid` CSS class) and invalid checks (styled with `invalid` CSS class).

## Use Cases

### Wizard Configuration Validation

An administrator configuring a new Forms Wizard to guide users through a multi-step process (e.g., employee onboarding, project approval, or data collection) places the widget on the wizard's configuration page. As they configure steps and navigation, the widget continuously validates the setup and immediately highlights any structural issues such as missing start steps, disconnected steps, final steps with incorrect next steps, or missing final step definitions.

### Pre-Activation Quality Check

Before activating a wizard and making it available to end users, an administrator reviews the widget to verify all validation checks pass. This prevents activating a broken wizard that could fail to start due to missing start steps, trap users in unreachable steps, have incomplete navigation flows, or lack proper completion endpoints.

### Troubleshooting Wizard Issues

When a wizard is not working as expected, administrators add or review the widget to diagnose structural issues. The detailed error messages pinpoint exactly which steps or configurations are problematic, such as "Some steps are not reachable (not reachable steps: EmployeeReview, FinalApproval)" or "Some final steps have next steps (final steps with next steps: SubmissionComplete)".

### External Wizard Configuration

When setting up a wizard for external users (non-authenticated users or users from external systems), the widget validates that external access is properly configured, ensuring an external access user is set when required. This prevents runtime errors when external users attempt to execute the wizard.

### Complex Navigation Validation

For wizards with conditional branching, skip logic, or complex navigation paths between steps, the widget validates that all navigation configurations are valid, ensuring skip configurations point to valid steps, all paths eventually lead to a final step, and no circular references or infinite loops exist in the navigation.

### Wizard Maintenance and Updates

When updating an existing wizard by adding new steps or modifying the navigation flow, the widget provides continuous validation feedback during modifications, helping administrators maintain a valid configuration throughout the update process. This is especially valuable when reorganizing steps or changing the navigation structure.

## Design Considerations

### When to Use This Widget

Always include the Forms Wizard Analysis widget on wizard configuration pages to provide continuous validation feedback. It should be a standard component of the wizard configuration interface, typically used alongside the Wizard Activation widget to create a complete configuration and activation workflow.

### Real-Time Updates

The widget automatically refreshes its analysis when step relationships are modified, step configurations are updated, or the wizard configuration changes. This provides immediate feedback during the configuration process without requiring manual refresh actions.

### Error Prevention

The widget helps prevent common wizard configuration errors including:
- **Structural errors**: Missing start/end points, disconnected steps
- **Navigation errors**: Invalid skip configurations, unreachable steps
- **Logic errors**: Final steps with next steps, non-final leaf nodes
- **Access errors**: Missing external access configuration

## Common Pitfalls

- **Ignoring partial validation success**: Even if some checks pass, address all validation errors before making the wizard available to users
- **Activating before validation**: Never activate a wizard for end users without reviewing the widget's output and ensuring all validations pass
- **Not monitoring after changes**: After modifying an existing wizard, always review the analysis results to ensure changes didn't introduce new issues

## Related Widgets

### Wizard Configuration Widget Set

The Forms Wizard Analysis widget is part of a comprehensive widget ecosystem for configuring and managing Forms Wizards:

- **Wizard Activation Widget** (`cf.cplace.formsWizard.wizardActivation`) - Controls wizard activation state, typically used alongside the Analysis widget to prevent activation when analysis shows invalid configuration
- **Step Manager Widget** (`cf.cplace.formsWizard.stepManager`) - Manages the list of wizard steps, creates, edits, and orders steps in the wizard flow
- **Wizard Localizations Widget** (`cf.cplace.formsWizard.wizardLocalizations`) - Manages localized text for wizard UI elements, provides multi-language support for wizards

### Typical Page Layout

On a Forms Wizard configuration page, you would typically find:
- Step Manager Widget - To manage the list of steps
- Wizard Analysis Widget - To validate the configuration
- Wizard Activation Widget - To activate/deactivate the wizard
- Wizard Localizations Widget - To configure multi-language support

## Alternative Approaches

For basic wizard configuration without complex validation needs, you might rely solely on the Step Manager Widget. However, for production wizards or complex multi-step processes, the Analysis widget is essential for ensuring configuration quality and preventing runtime errors.