Workflow Troubleshooting

Can you view the workflow?
│
├─ NO → [Access/Permission Issues](#cant-access-workflow)
│
└─ YES → Can you transition event state?
    │
    ├─ NO (button disabled) → [Validation Errors](#validation-errors-blocking-state-transitions)
    ├─ NO (button missing) → [Permission Issues](#insufficient-permissions)
    │
    └─ YES → Does state transition succeed?
        │
        ├─ NO (error message) → [Transition Failed](#transition-failed-errors)
        ├─ NO (no response) → [System Issue](#system-not-responding)
        │
        └─ YES → Data showing correctly?
            │
            ├─ NO → [Data Sync Issues](#data-not-updating)
            └─ YES → All good!

1. Go to Dashboard → Events
2. Check if event appears in "My Events" list
3. If not listed:
   - Contact admin to add you as organizer
   - Or ask current organizer to delegate

1. Go to Settings → Profile → View Role
2. Verify you have ORGANIZER role assigned to this event
3. If wrong role, contact admin to update

1. Go to Dashboard → Events → All Events
2. Search for event by number or name
3. If not found:
   - Event may be archived (click "Show Archived")
   - Event may be deleted (contact admin to restore)
   - You may have wrong event number

1. Contact event's primary organizer
2. Request they add you as co-organizer:
   - Event → Settings → Organizers → Add Organizer
3. After being added, refresh page
4. "Advance" button should now appear

1. Email admin with justification
2. Include:
   - Your current role
   - Events you need access to
   - Why you need workflow edit permission
3. Admin will review and update role if appropriate

Validation: Must have selected event topic(s)
Error: "At least one topic must be selected"

Solution:
1. Go to Phase A → Topic Selection
2. Click "View Topic Heat Map" to review historical coverage
3. Select 1-4 topics for the event
4. Click "Save Topic Selection"
5. Event automatically transitions to TOPIC_SELECTION state

Validation: Must have identified speaker candidates (minimum threshold)
Error: "Minimum 8 speaker candidates required (current: 5)"

Solution:
1. Go to Phase A → Speaker Brainstorming
2. Add more speaker candidates:
   - Search existing speaker database
   - Or add new speaker profiles
3. Each speaker added starts in the IDENTIFIED state (also where Epic 7 self-nominations enter)
4. Once threshold reached, event can transition to SPEAKER_IDENTIFICATION

Tip: Threshold is configurable per event type (default: 10 for full-day, 6 for afternoon, 4 for evening)

Validation: Minimum publishable speakers with quality-reviewed content
Error: "Insufficient publishable speakers: 7/10 required"

Solution:
1. Review speaker workflow progress in Phase B Kanban board
2. For each speaker:
   - Promote chosen candidate: CONTACTED → READY (provisions User + SPEAKER role + Cognito; organizer-only)
   - Invite the speaker: READY → INVITED (subject to the slot-capacity gate)
   - Speaker accepts: INVITED → ACCEPTED
   - Collect content: ACCEPTED → CONTENT_SUBMITTED
   - Review quality (Phase C): CONTENT_SUBMITTED → QUALITY_REVIEWED
3. A speaker becomes publishable (derived flag is_publishable) when QUALITY_REVIEWED AND session.startTime exists (is_slot_assigned)
4. Once minimum publishable speakers reached, can transition to SLOT_ASSIGNMENT

Note: Minimum is 10 publishable speakers for full-day events, 6 for afternoon, 4 for evening

Validation: All quality-reviewed speakers assigned to time slots (i.e. publishable)
Error: "4 quality-reviewed speakers not assigned to slots"

Solution:
1. Go to Phase D → Slot Assignment
2. Drag quality-reviewed speakers to available time slots
3. Resolve any conflicts (double-booking, speaker unavailability)
4. System auto-saves slot assignments
5. Click "Publish Agenda" when all quality-reviewed speakers are assigned (is_publishable)
6. Event transitions to AGENDA_PUBLISHED state

Validation: Speaker cannot become publishable (is_publishable)
Error: Speaker is QUALITY_REVIEWED but has no slot, or has a slot but is not yet QUALITY_REVIEWED

Cause: is_publishable is a derived flag (there is NO confirmed state). It requires BOTH:
- Speaker status = QUALITY_REVIEWED
- Session has startTime (is_slot_assigned)

Solution:
1. If QUALITY_REVIEWED but no slot:
   - Go to Phase D → Slot Assignment
   - Assign speaker to time slot
   - Speaker becomes publishable when the slot is saved (is_slot_assigned → true)

2. If has slot but not yet QUALITY_REVIEWED:
   - Go to Phase C → Quality Review
   - Review and approve speaker content (CONTENT_SUBMITTED → QUALITY_REVIEWED)
   - Speaker becomes publishable once approved

Note: Order doesn't matter - whichever completes second flips is_publishable to true

1. Review validation error message carefully
2. Look for red border or asterisk (*) on fields
3. Red error text usually indicates specific issue
4. Hover over disabled transition button for hint

1. Fill in highlighted fields or complete required actions
2. Click "Save" or "Update" button if editing entity
3. Verify red errors disappear
4. State transition button should enable

1. Open browser console (F12 → Console)
2. Click state transition button
3. Console may show detailed validation errors
4. Screenshot and send to support if unclear

1. Click state transition button again (may be temporary glitch)
2. If error persists, proceed to next step

1. Refresh page (F5 or Ctrl+R)
2. Verify all your changes are still saved
3. Review validation errors (may have changed)
4. Try transition again

If error mentions "conflict" or "modified":
1. Someone else edited event while you were working
2. Refresh page to get latest state
3. Re-apply your changes if needed
4. Advance again

Tip: Platform shows "Currently editing: [Name]" badge at top if others are working on same event

If error mentions "timeout" or "network":
1. Check internet connection
2. Verify status page: https://status.batbern.ch
3. Wait 1 minute and retry
4. If persists, contact support

1. Wait up to 2 minutes (complex transitions may take time)
2. Watch browser status bar (bottom-left) for network activity
3. Check browser console (F12 → Console) for errors

1. Refresh page (do NOT click transition button again while spinning)
2. Check if state transitioned despite no confirmation
3. If still at same state, click transition button again

1. Check if browser frozen (can you switch tabs?)
2. If frozen:
   - Force close browser (Task Manager on Windows, Force Quit on Mac)
   - Reopen and log back in
   - Platform auto-saves, so progress should be preserved
3. If not frozen but stuck:
   - Open browser console (F12)
   - Look for JavaScript errors
   - Screenshot and send to support

Platform save patterns:
- Entity edits (companies, speakers, events): Manual save required (click "Save" button)
- Event state transitions: Automatic save (no separate save button)
- Speaker state updates: Immediate save when changed (Kanban drag-and-drop)
- Slot assignments: Auto-save after 2 seconds

If you edited entity, ensure you clicked "Save" before navigating away.

1. Hard refresh: Ctrl+Shift+R (Cmd+Shift+R on Mac)
2. Clears cache and reloads from server
3. Verify if your changes are present
4. If not present, changes were never saved (see next step)

Look for indicators:
- "Saving..." → Changes being saved
- "Saved ✓" → Changes persisted successfully
- "Failed to save" → Error, see browser console for details

If "Failed to save":
1. Check browser console (F12 → Console)
2. Common errors:
   - "Session expired" → Log in again
   - "Permission denied" → Verify role
   - "Network error" → Check connection
3. Re-apply changes and save again

1. Look at filter panel (usually top-right)
2. Clear all filters (click "Reset" or "Clear All")
3. Change status filter to "All Statuses"
4. Expand date range to "All Time"

Speakers move between Kanban columns based on their individual workflow state (8-state model):
- Phase A (Setup): Speakers in "Identified" column
- Phase B (Outreach): Moves to "Contacted", "Ready", "Invited", "Accepted", "Content Submitted" columns
- Phase C (Quality): Moves to "Quality Reviewed" column
- Phase D (Assignment): "Quality Reviewed" speakers with an assigned slot are publishable (is_publishable) and visible in slot assignment view
- (A speaker who declines lands in the terminal "Declined" state)

Solution: Click through different phase views (A-D) to find speakers in their current state.

1. Toggle "Show Archived" checkbox (if available)
2. Go to Settings → Audit Log to see recent deletions
3. If accidentally deleted, contact admin to restore

1. Event → Edit Event modal
2. Check "Override workflow validation" checkbox (if available)
3. Select desired state from "Event State" dropdown
4. Provide reason (required for audit trail)
5. Click "Save Changes"
6. Event reverts to selected state, but data from later states is preserved

Note: This is typically only needed for cancelled/rescheduled events

Most data can be edited without reverting event state:
- Speakers: Can update individual speaker states at any time (Kanban drag-and-drop)
- Topics: Can add/remove even after AGENDA_PUBLISHED (requires re-publish)
- Content: Upload new versions, speakers can revise submissions
- Slots: Can reassign speakers even after publishing

Only the high-level event state is locked forward. Speaker states are independent.

Individual speakers CAN move backwards through states:
- QUALITY_REVIEWED → CONTENT_SUBMITTED (request revisions)
- Removing a slot assignment clears the derived is_slot_assigned / is_publishable flags (the workflow state stays QUALITY_REVIEWED — there is no confirmed state to revert)
- A speaker who pulls out at any point moves to the terminal DECLINED state (replaces the old withdrew/drop-out outcomes)

This is done via:
1. Phase B Kanban board: Drag speaker to an earlier valid column, or mark as DECLINED
2. Phase C Quality drawer: Click "Request Revisions" instead of "Approve"
3. Phase D Slot assignment: Remove speaker from slot (clears is_slot_assigned / is_publishable; no state write)

1. Go to Dashboard → Events → [Event]
2. Look at "Event State" badge (top-right)
3. Verify state matches expected workflow position
4. Check for validation errors preventing next transition

1. Event → Settings → Status
2. Check "Archived" checkbox status
3. If archived, unarchive to make editable again

Use Edit modal override:
1. Event → Edit Event
2. Check "Override workflow validation" checkbox
3. System allows manual state selection
4. Select correct state if corrupted
5. Provide reason in notes
6. Save changes

Warning: Only use if state is genuinely incorrect. Most "stuck" issues are validation failures.

Event may be stuck if speaker states prevent progression:
1. SPEAKER_IDENTIFICATION → SLOT_ASSIGNMENT requires minimum publishable speakers
2. Go to Phase B/C to review speaker workflow progress
3. Check how many speakers are in each state:
   - IDENTIFIED, CONTACTED, READY, INVITED, ACCEPTED, CONTENT_SUBMITTED, QUALITY_REVIEWED (and terminal DECLINED)
4. Ensure minimum threshold of publishable speakers reached (QUALITY_REVIEWED AND assigned to a slot)
5. Event can only progress when speaker requirements met

Contact support with:
- Event number
- Current event state (badge text)
- Screenshot of validation errors
- Browser console errors (F12 → Console)
- Recent actions taken before getting stuck
- Speaker state counts (how many in each state)