← Back to Documentation Home

User Documentation

Story Editor - Narrative Process Flow Visualization

Last Updated: October 2025 - Unified Story Creation Flow

Overview

The Story Editor provides a narrative-based view of process flows, transforming technical process steps into readable stories that follow a natural language pattern. Stories are now created through a unified modal interface that guides you through the entire flow creation process.

Core Concept

Story Pattern

Every process flow follows this narrative structure:

[condition] {source} {action1} [{dataobject}] [then {action2}] {target}

Examples:

Customer submits Order to Order Management System
Order Management System validates Order then forwards to Warehouse
When timeout occurs: Timer triggers Cleanup then executes by Maintenance Process

Key Principles

1. Unified Story Creation Modal

Stories are created through a single, unified modal that guides you through all steps:

  • Visual Preview: Real-time caption shows how your story will look
  • Smart Validation: Form validates required fields and element types
  • Flexible Creation: Choose existing elements or create new ones inline
  • Auto-positioning: New elements are automatically positioned in the graph

2. Story Elements

Source (Active Elements)

Stories can ONLY be started by active elements:

  • 👤 Actors (users, roles, stakeholders)
  • ⏰ Timers (scheduled events)
  • 🔄 Processes (sub-processes)
  • 🎯 Features (system functions)

Data objects CANNOT start stories - they are passive elements.

Actions

  • Action 1: Primary action from source (required)
    • Examples: "submits", "validates", "processes", "triggers"
  • Then Action (Action 2): Secondary action when dataobject is involved (optional)
    • Examples: "then sends to", "then forwards to", "then delivers to"
    • Only shown when a dataobject is present in the flow

Optional Elements

  • Condition: Prefix condition for the story
    • Examples: "When timeout occurs:", "If order is valid:", "After 5 minutes:"
  • Data Object: Intermediate element in the flow (optional)
    • Can be existing or created inline
  • Target: Destination element (required)
    • Can be any element type
    • Can be existing or created inline

3. Creating vs Selecting Elements

The unified modal allows two modes for dataobjects and targets:

Selecting Existing Elements

  • Use autocomplete dropdown to find existing elements
  • Elements must already exist in the current process
  • If not in process, they will be automatically added

Creating New Elements

  • Click "New Element" to reveal inline creation form
  • Provide element name and type
  • Optionally reference an existing system element
  • New elements are created and added to the process automatically

Features

📖 Story View

  • Narrative Format: Stories displayed as readable sentences
  • Color-Coded Elements:
    • 🔵 Source (blue) - Who/what initiates the action
    • 🟢 Actions (green) - What actions are performed
    • 🟡 Data Object (yellow) - What is being processed (if present)
    • 🟣 Target (purple) - Where it goes/who receives it
  • Order Numbers: Each story has an order number for sequencing
  • Quick Actions: Edit, delete, and view connected objects

✏️ Story Creation

Access via: Top Menu → "Create Story" button

The Unified Modal

  1. Source Display: Shows the currently selected element (must be active element type)
  2. Condition (Optional): Add prefix condition
    • Example: "When timeout occurs:", "If validation succeeds:"
  3. Action (Required): Primary action verb
    • Examples: "submits", "processes", "validates", "triggers"
  4. Data Object (Optional):
    • Select existing from dropdown OR
    • Click "New Element" to create inline
    • When present, "Then Action" field appears
  5. Then Action (Optional): Secondary action when dataobject present
    • Examples: "then sends to", "then forwards to"
  6. Target (Required):
    • Select existing from dropdown OR
    • Click "New Element" to create inline
    • Specify target type (actor, feature, process, etc.)

Visual Caption Preview

As you fill out the form, a live preview shows how your story will appear:

{Condition} {Source} {Action1} [{DataObject}] [then {Action2}] {Target}

🎨 Connected Objects Panel

Click the "Connected Objects" icon on any story to see:

  • Interfaces: What interfaces are used/provided
  • Events: What events are published/subscribed
  • Related Elements: All elements connected in this story
  • Cross-Boundary Connections: Highlighted when elements cross context boundaries

Features:

  • Auto-Update: Panel updates when you select different stories
  • Navigation: Click any element to jump to it in the graph
  • Edit Access: Click edit icon to modify the story
  • Modern UI: Subtle colors (blue-50, purple-50, green-50), 467px width

✂️ Story Management

  • Edit: Click edit icon to modify existing story
    • Button text changes to "Speichern" (Save) in edit mode
    • All fields pre-filled with current values
  • Delete: Remove stories with confirmation
  • Reorder: Drag stories to change sequence (coming soon)
  • Duplicate: Copy story structure (coming soon)

Use Cases

1. Process Documentation

Transform technical process diagrams into readable documentation:

Story 1: Customer Order Flow
Customer submits Order to Order Management System

Story 2: Order Processing
Order Management System validates Order then forwards to Warehouse

Story 3: Inventory Update
Warehouse picks Order then updates to Inventory System

2. Complex Data Flows

Document flows with intermediate data processing:

When order received: Payment Service processes Payment then sends to Order System
Order System validates Payment Data then forwards to Fulfillment

3. Conditional Flows

Use conditions to clarify when flows execute:

If payment approved: Payment Gateway creates Receipt then delivers to Customer
When timeout occurs: Timer triggers Cleanup then executes by Maintenance Process
After 24 hours: Scheduler sends Reminder to Customer Service

4. Stakeholder Communication

  • Review flows in natural language
  • Share with non-technical stakeholders
  • Use for training and onboarding
  • Facilitate process improvement discussions

Future Enhancements

Phase 2: Advanced Features

  • Drag & Drop Reordering: Reorganize stories by dragging
  • Duplicate Stories: Copy existing story structure
  • Story Templates: Pre-defined patterns for common flows
  • Batch Operations: Update multiple stories at once

Phase 3: Story Analysis

  • Story Validation: Check for incomplete or orphaned flows
  • Flow Coverage: Highlight unconnected elements
  • Complexity Metrics: Analyze story complexity and depth
  • Story Export: Export to Markdown, PDF, or Word

Phase 4: Collaborative Features

  • Story Comments: Add notes and discussions
  • Story Versions: Track changes over time
  • Story Approval: Workflow for process sign-off
  • Story Comparison: Diff between process versions

Troubleshooting

Story Not Saving

  • Check browser console for errors
  • Ensure source is an active element type (actor/timer/process/feature)
  • Verify target is selected or created
  • Check database connection status

Elements Not Appearing

  • If selecting existing elements, they must exist in the database
  • New elements are created automatically - check process elements list
  • Elements added to process are fetched from database, not Cytoscape graph
  • Refresh the view if elements don't appear immediately

Connected Objects Panel Not Updating

  • Panel auto-updates when you select different stories
  • If stuck, close and reopen the panel
  • Check that story has valid sourceElementId and targetElementId

Button Text Issues

  • Edit mode: Button should say "Speichern"
  • Create mode: Button should say "Create Story"
  • If incorrect, check that existingStory parameter is passed correctly

Related Documentation

Technical Architecture

Data Model

Story {
  _id: string,                 // Story ID
  elementType: 'story',        // Type identifier
  processId: string,           // Parent process ID
  sourceElementId: string,     // Source element (actor/timer/process/feature)
  targetElementId: string,     // Target element (any type)
  label: string,               // Story label (typically action1)
  order: number,               // Display order (10, 20, 30...)
  
  // Optional fields
  condition: string,           // Prefix condition ("When...", "If...")
  action1: string,             // Primary action verb
  action2: string,             // Secondary action (when dataobject present)
  dataObjectId: string,        // Intermediate dataobject ID
  
  // Metadata
  createdAt: timestamp,
  updatedAt: timestamp,
  version: number
}

UI Components

ConnectedObjectsModal (js/ui/ConnectedObjectsModal.js)

  • Purpose: Display all connections for selected story
  • Features:
    • Queries interfaces, events, and direct connections
    • Filters boundary-crossing connections
    • Auto-updates on selection change
    • Modern UI with subtle colors (467px width)
  • Z-index: 40 (above buttons at 35)

Story Creation Form (index.html - Unified Step Modal)

  • Location: #unified-step-modal
  • Key Fields:
    • step-condition: Optional condition
    • step-action-1: Primary action (required)
    • step-action-2: Secondary action (shown when dataobject present)
    • dataobject-input: Autocomplete for dataobject selection
    • target-input: Autocomplete for target selection
  • Inline Forms:
    • inline-dataobject-form: Create new dataobject
    • inline-target-form: Create new target
  • Dynamic Behavior:
    • Action2 field only visible when dataobject selected/created
    • Button text changes: "Create Story" → "Speichern" in edit mode
    • Real-time caption preview updates as you type

Story Creation Flow

  1. User Interaction:

    • Click "Create Story" button (requires active element selected)
    • OR right-click element → "Create Story"

  2. Modal Display (_showUnifiedStepForm):

    • Pre-fills source from selected element
    • Sets up autocomplete for dataobject and target
    • Configures inline creation forms
    • Attaches event listeners

  3. Form Validation:

    • Source must be active element type
    • Action1 required
    • Target required (existing or new)
    • Action2 shown only when dataobject present

  4. Story Creation (_createStoryFromFormData):

    • Validates all fields
    • Creates new elements if needed (dataobject, target)
    • Adds elements to process if not already present
    • Creates story document with all fields
    • Updates graph rendering
    • Refreshes story editor if open

  5. Element Addition Logic:

    • Checks if element exists in process.elements
    • If missing and existing: fetches from database using findElementById()
    • If missing and new: creates element and adds to process
    • Saves updated process with new elements
    • Note: Uses database lookup, NOT Cytoscape, to support off-screen elements

Story Grouping Algorithm

  1. Parse all edges from process
  2. Identify story starts (active element → data object)
  3. Find continuation edges (data object → target) with stepNumber + 1
  4. Group stories by stepNumber
  5. Mark parallel flows (same stepNumber) with "Meanwhile"

Drag & Drop Implementation

  • HTML5 Drag and Drop API
  • Visual feedback during drag
  • Automatic DOM reordering
  • Post-drop renumbering option

Best Practices

Story Organization

  1. Start with primary flow (step 10, 20, 30...)
  2. Add parallel flows at same step numbers
  3. Use meaningful increments (10s for main, 5s for sub-steps)
  4. Group related stories visually

Naming Conventions

  • Actions: Use present tense verbs ("submits", "validates", "processes")
  • Then Actions: Use transfer verbs ("sends to", "forwards to", "updates")
  • Elements: Use clear, business-friendly names

Process Flow Design

  • Keep main story flows simple (3-5 steps)
  • Use parallel flows for notifications, logging, etc.
  • Avoid complex branching in single stories
  • Break complex processes into sub-stories

Keyboard Shortcuts

(Future)

  • Ctrl+E: Edit selected story
  • Ctrl+D: Delete selected story
  • Ctrl+↑/↓: Move story up/down
  • Ctrl+S: Save changes
  • Esc: Cancel editing

Testing the Story Editor

Access

  1. Open a process in Korgraph
  2. Click the 📖 Story Editor button in the top toolbar
  3. View your process flows as stories

Initial View

  • If process has no steps: Empty state with guidance
  • If process has steps: Organized story groups
  • Parallel flows: Grouped with "Meanwhile" prefix

Interaction

  • Drag handles (⋮⋮) to reorder stories
  • Click sequences to see associated edges
  • Use toolbar for bulk operations

Feedback & Iteration

This is a testing version - your feedback is valuable!

What to Test

  • Story readability and clarity
  • Grouping logic (parallel flows)
  • Drag & drop experience
  • Visual design and information density

Next Iterations

Based on feedback, we'll add:

  • Editing capabilities
  • Story creation from scratch
  • Advanced grouping options
  • Export and sharing features

Note: This is an experimental feature for testing purposes. The goal is to make process flows more accessible and easier to understand through narrative visualization.