Overview
The tour module automatically detects first-time users and launches a comprehensive introduction covering risksheet identity, grid navigation, column management, filtering, item addition, and risk tracking. Returning users can manually restart the tour at any time via a footer button or help integration.
| Step | Tour Stop | Description |
|---|
| 1 | Risksheet Grid | Introduction to the spreadsheet-style risk analysis view |
| 2 | Column Headers | Explains column groups and severity/occurrence/detection layout |
| 3 | Risk Matrix Cell | Shows how risk levels are calculated and color-coded |
| 4 | Toolbar Actions | Overview of available toolbar operations |
| 5 | Filter Panel | Demonstrates filtering by risk level, status, or assignee |
| 6 | Add New Item | How to create new risk items inline |
| 7 | LiveDoc Sync | Real-time synchronization with Polarion LiveDoc |
| 8 | Export Options | PDF and Excel export capabilities |
Module Configuration
Configuration Object: window.risksheetTourConfig
Page authors can customize tour behavior by setting properties on window.risksheetTourConfig before the risksheet-tour.js script loads.
| Property | Type | Default | Description |
|---|
tourId | string | "risksheet-intro-tour" | Unique identifier for localStorage tour-completion key. Changes this to show tour again for all users (e.g., after major UI updates). Pattern: tour-seen-{tourId} stored in browser localStorage. |
autoStart | boolean | true | Automatically launch intro tour for first-time users. Set false to make tour opt-in only (manual footer button click). |
autoStartDelay | number | 2500 | Milliseconds to wait after page load before auto-starting tour. Allows page rendering and Risksheet initialization to complete. Recommended: 2000–3000ms. |
projectId | string | (auto-detected) | Polarion project ID for constructing widget resource URLs. Auto-detected from URL path (/project/XXX/) or query parameter (?project=XXX). Override if URL detection fails. |
<script>
// Customize tour before loading risksheet-tour.js
window.risksheetTourConfig = {
tourId: "risksheet-intro-tour-v2",
autoStart: true,
autoStartDelay: 3000,
projectId: "TestAuto2"
};
</script>
<script src="/nextedy-automotive-safety/resources/risksheet-tour.js"></script>
Tour Sequences
Full Intro Tour (8 Steps)
Triggered on page load for first-time users. Comprehensive walkthrough covering the complete FMEA risksheet workflow.
| Step # | Title | Target Element | Key Message | FMEA Phase |
|---|
| 1 | Welcome to Risksheet | Risksheet title in top panel (#nxtr-topPanel .rs-green-colored) | “Risksheet is a spreadsheet-like editor for FMEA with 1:1 LiveDoc sync. Changes are bidirectionally synchronized with Polarion.” | Initialization |
| 2 | Risk Analysis Grid | Main grid (#theGrid) | “Failure modes, effects, causes, and risk assessments are displayed in an Excel-like spreadsheet. Click any cell to edit directly. Familiar keyboard navigation and copy/paste work as expected.” | Data Entry |
| 3 | Switch Column Views | Columns button (#btnColumns) | “Use views to switch between columns, showing/hiding data for different FMEA phases: initial risk → define controls → residual risk assessment.” | Navigation |
| 4 | Filter Like Excel | Filter icons on column headers (.wj-elem-filter) | “Click the filter icon on any column header to filter data by values, conditions, or search text—just like in Excel. No Excel installation required.” | Data Analysis |
| 5 | Add New Items | Add buttons (#btnAddLevel0, etc.) | ”Use the Add buttons to create new Items (requirements/functions), Failure Modes, Causes, or Tasks (risk controls). Buttons follow hierarchical levels matching FMEA structure.” | Data Creation |
| 6 | Pre-Mitigation Status (Traffic Light 1) | Traffic light indicator (top-right overlay) | “Green traffic light = pre-mitigation assessment complete (Severity, Occurrence, Detection all filled). Yellow or red indicates missing data.” | Risk Assessment |
| 7 | Post-Mitigation Status (Traffic Light 2) | Traffic light indicator (top-right overlay) | “After defining controls, reassess Occurrence and Detection. Green = post-mitigation assessment complete for all failure modes.” | Control Verification |
| 8 | High-Risk Tracking (Traffic Light 3) | Traffic light indicator (top-right overlay) | “Red traffic light = remaining high-priority risks (Action Priority ‘High’ or RPN > threshold). Green = all residual risks acceptable. Address red items before release.” | Risk Acceptance |
#help-tour-btn). Focused walkthrough covering only traffic light indicators and risk status.
| Step # | Title | Target Element | Key Message |
|---|
| 1 | Traffic Light Overview | Traffic light panel (top-right) | Three lights show FMEA progress: Pre (pre-mitigation complete), Post (post-mitigation complete), High (remaining high-risk items). |
| 2 | Pre/Post Mitigation Status | Traffic light panel | Green = complete, Yellow = partial, Red = incomplete or high-risk. Check fractional counts (e.g., 7/12) to see progress. |
| 3 | Action Required | Traffic light panel | Focus on red lights—they indicate missing data or unacceptable residual risk. Complete assessments or add controls until lights turn green. |
The help button (short tour) provides quick contextual reference for traffic lights. The footer button (full tour) provides comprehensive onboarding. Users can repeat either tour at any time.
Feature Reference
Auto-Detection and localStorage Persistence
The module automatically detects first-time users by checking browser localStorage. On first page load, if the key tour-seen-{tourId} does not exist, the tour auto-starts after autoStartDelay milliseconds. Returning users do not see the tour unless they manually restart it.
| Behavior | localStorage Key | Value | Notes |
|---|
| First visit | tour-seen-{tourId} | (not set) | Auto-start tour after delay |
| Tour completed | tour-seen-{tourId} | "true" | Set on tour exit; persists in browser |
| Different browser | tour-seen-{tourId} | (not set) | Tour shows again (per-browser tracking) |
| Different device | tour-seen-{tourId} | (not set) | Tour shows again (device-specific localStorage) |
Tour state is stored per-browser, not per-user account. Users on different browsers or devices will see the tour again. Private/Incognito mode may not persist localStorage. If localStorage is disabled, the module gracefully disables persistent tracking and launches tours on every page load (unless autoStart: false).
#footerNextedy), positioned next to Nextedy branding. Clicking this button manually restarts the full 8-step intro tour at any time, even after the tour has been marked as completed.
<!-- Injected into page footer -->
<button id="btnRisksheetTour" class="btn btn-default">
▶ Intro Tour
</button>
- User wants to review tour after initial onboarding
- Team leader demonstrates risksheet workflow to new users
- Page updates introduce new tour content (update
tourId to force re-start)
If an element with ID #help-tour-btn exists on the page, the module binds a click handler to launch the short 3-step traffic-lights tour. This provides contextual help without full onboarding.
<!-- Page should include help button; module auto-binds -->
<button id="help-tour-btn" class="btn btn-info" title="Traffic Lights Help">
?
</button>
The short tour is stateless—it does not check localStorage or update tour completion status. Users can click the help button as many times as needed for quick reference.
Driver.js Dynamic Loading
The module automatically loads Driver.js (required tour library) from project widget resources if not already present on the page. Both the JavaScript library and CSS stylesheet are dynamically injected.
| Resource | URL Pattern | Purpose |
|---|
| Driver.js Library | /nextedy-automotive-safety/resources/driver.min.js | Interactive tour overlay and step navigation |
| Driver.js CSS | /nextedy-automotive-safety/resources/driver.min.css | Styling for tour highlights, buttons, and tooltips |
- Module checks if
window.Driver is defined (library already loaded)
- If not found, fetches CSS and JS from widget resources
- Implements fallback polling to wait for script readiness (max 5 seconds)
- Logs errors if Driver.js fails to load; tour gracefully skips
Version Updates:
To update Driver.js library version, replace the page attachments in the Risksheet page widget resources. The module automatically uses the newest version without code changes.
Risksheet-LiveDoc Synchronization Explanation
Tour Step 1 explains the 1:1 relationship between Risksheet and Polarion LiveDoc: every change in Risksheet is automatically synchronized to the underlying LiveDoc work items, and vice versa.
Key Points:
- Changes in Risksheet appear in LiveDoc fields in real-time (no “save” button required)
- Changes to work items in Polarion immediately reflect in Risksheet rows
- 1:1 relationship means one Risksheet row = one work item (except multi-row failure modes with causes/effects)
- Sync works across projects and teams—any user can edit either interface
Grid Editing Introduction
Tour Step 2 highlights the main grid (#theGrid) and explains that it is a direct-edit spreadsheet interface for failure modes, effects, causes, and risk assessments. The grid uses Wijmo FlexGrid engine for Excel-like interaction:
| Capability | Behavior |
|---|
| Keyboard Navigation | Arrow keys move between cells; Tab/Shift+Tab move horizontally; Enter moves down |
| Inline Editing | Click any cell or press F2 to edit directly in-place; no modal dialogs |
| Copy/Paste | Ctrl+C/Ctrl+V work as expected (single cell or ranges) |
| Column Resizing | Drag column border to resize; double-click to auto-fit |
| Column Reordering | Drag column header to reorder; changes persist in risksheet view config |
| Row Grouping | Failure mode rows can have child rows (causes, effects, controls) that expand/collapse |
| Work Item Types | Rows map to work item types: Items (requirements), Failure Modes, Causes, Effects, Tasks (risk controls) |
Column Views and Progressive Workflow
Tour Step 3 introduces the Columns button (#btnColumns), which switches between predefined views showing/hiding columns for different FMEA phases:
| View Name | Columns Shown | FMEA Phase | Use Case |
|---|
| Initial Risk Assessment | systemItemId, failureMode, causes, effects, severity, occurrence, detection | Identification & Analysis | Populate failure modes, causes, effects, and initial risk ratings |
| Pre-Mitigation Summary | systemItemId, failureMode, severity, occurrence, detection, actionPriority | Risk Prioritization | Identify high-priority items requiring controls |
| Controls & Mitigation | systemItemId, failureMode, riskControl, controlType, controllingParameter | Define Controls | Link risk controls and document mitigation strategy |
| Post-Mitigation Assessment | systemItemId, failureMode, severity, occurrenceNew, detectionNew, actionPriorityPost | Residual Risk Re-assessment | Verify that controls reduce risk to acceptable levels |
| Full FMEA (All Columns) | All columns (20+) | Reference | Comprehensive view for documentation and review |
risksheet.json configuration and enable progressive FMEA workflow without overwhelming users with data.
Excel-Like Filtering
Tour Step 4 highlights filter icons on column headers (.wj-elem-filter). Users can filter by values, conditions, or search text using Wijmo FlexGrid’s built-in filtering:
| Filter Type | Description |
|---|
| Column Filters | Filter by specific column values (dropdown selection) |
| Text Search | Free-text search across visible columns |
| Quick Filters | Predefined filter presets (e.g., High Risk, My Items) |
| Combined Filters | Stack multiple filter conditions simultaneously |
- Value List: Select/deselect individual enum values (S1, S2, S3, etc.)
- Conditions: Greater than, less than, contains, equals, etc. for numeric or text columns
- Search: Type text to filter rows where column contains match
Use Cases:
- Show only High action-priority failure modes: filter AP = “H”
- Show only uncontrolled risks: filter riskControl = empty
- Show items needing re-assessment: filter occurrenceNew = empty
Tour Step 5 introduces the Add buttons at the top of the risksheet (#btnAddLevel0, #btnAddLevel1, etc.). These create new work items in the FMEA hierarchy:
| Level | Item Type | Description |
|---|
| Parent | System Element | Top-level grouping (e.g., Subsystem, Component) |
| Child | Failure Mode / Hazard | Risk analysis item linked to parent |
| Grandchild | Control Measure / Action | Mitigation action linked to risk item |
| Button | Creates | Parent | FMEA Role |
|---|
#btnAddLevel0 | Item (Requirement or Function) | None (top-level) | System element or design component being analyzed |
#btnAddLevel1 | Failure Mode | Item | Potential failure in the system element |
#btnAddLevel2a | Cause | Failure Mode | Root cause of failure mode |
#btnAddLevel2b | Effect | Failure Mode | Consequence/impact of failure |
#btnAddLevel2c | Task | Failure Mode | Risk control or mitigation action |
Integration with Velocity Pages
The tour module is embedded in Polarion wiki pages via <script> tags in page XML. Page authors configure tour behavior by setting window.risksheetTourConfig before the script loads:
<!-- In .polarion/pages/widgets/risksheet-config/page.xml -->
<ac:structured-macro ac:name="velocity">
<ac:parameter name="script">
<![CDATA[
#set ( $velocityVersion = $pageService.getPageProperty("velocity-version") )
<script>
window.risksheetTourConfig = {
tourId: "risksheet-intro-tour-v2",
autoStart: true,
autoStartDelay: 2500
};
</script>
<script src="/nextedy-automotive-safety/resources/risksheet-tour.js"></script>
]]>
</ac:parameter>
</ac:structured-macro>
Traffic Lights Integration
The tour references the Risksheet Traffic Lights Module, which displays real-time FMEA completion status. Tour steps 6–8 explain the three-light indicator system:
- Pre-Mitigation Light: Green when pre-mitigation assessment (Severity, Occurrence, Detection) is complete for all failure modes
- Post-Mitigation Light: Green when post-mitigation assessment (revised Occurrence, Detection) is complete for all items
- High-Risk Light: Green when no unacceptable residual risks remain (Action Priority = Low/Medium only)
See Risksheet Traffic Lights Module for detailed configuration and customization.
Best Practices
After significant UI changes (new buttons, reorganized views), increment the tourId to force re-display for all users. For example, change "risksheet-intro-tour" to "risksheet-intro-tour-v2". This clears the localStorage completion flag and shows the updated tour to returning users.
Set autoStartDelay to allow the Risksheet grid to fully render before launching the tour. Recommended: 2500–3500ms. If the delay is too short, tour highlights may target incorrect elements. If too long, users may leave the page before tour starts.
The Driver.js library includes keyboard navigation (arrow keys, Enter to advance, Escape to close). Tour steps are announced via ARIA labels for screen reader users.
