Skip to content

Occurrences – Overview

The Occurrences vertical enables citizen issue reporting and municipal response management. It implements a FixMyStreet-style workflow with configurable states, SLAs, templates, and external routing.

What you can do with this module

  • Citizen Reporting: Allow citizens to submit issues with location, category, and description.
  • Triage & Assignment: Staff can review, categorize, and assign incoming reports.
  • Workflow Management: Configure custom states and transitions for your process.
  • Communication: Use templates for consistent citizen communication.
  • SLA Tracking: Set response and resolution targets with breach alerts.
  • External Routing: Route certain categories to email, Open311, or webhooks.
  • Duplicate Detection: Identify and link similar reports.

Key concepts

Occurrences

Individual reports/issues submitted by citizens or created by staff. Each occurrence has: - Location (geographic point) - Category/type - Description and optional attachments - Status and workflow state - Assignment and history

Occurrence Types

Categories that classify issues (e.g., "Pothole", "Streetlight", "Graffiti"). Types can: - Be assigned to specific departments - Have custom priorities and SLAs - Trigger specific routing rules

Workflow States

Custom states that describe where an occurrence is in your process: - Received → Scheduled → In Progress → Resolved → Closed - Configurable per municipality - Transitions can be role-restricted

Templates

Pre-defined messages for consistent communication: - Acknowledgment templates - Status update templates - Resolution templates - Auto-response rules for automation

Priorities & SLAs

Define response expectations: - First response target (hours) - Resolution target (hours) - Escalation rules for breaches

User roles

Role Responsibilities
Citizen Submit reports, track status, receive updates
Staff/Operator Triage, assign, update, communicate
Manager Configure SLAs, monitor compliance, set escalations
Administrator Configure workflows, templates, routing

Where to start

  • Submitting issues: Go to Occurrences → Citizen workflow → Submit & track
  • Managing reports: Go to Occurrences → Staff workflow → Triage & manage
  • Configuring workflows: Go to Occurrences → Administrator setup
  • Understanding the lifecycle: Go to Occurrences → From your report to resolution

Feature flags

The Occurrences module has configurable features: - Templates: Response templates for staff - Custom states: Beyond basic open/closed - SLA tracking: Priority-based deadlines - Escalations: Breach notifications - Routing: External system integration - Duplicate detection: Similar report linking

See Reference → Feature flags for details.

Behind the scenes (grounded in code)

  • Models: apps/occurrences/models.py (Occurrence, OccurrenceType, OccurrenceState, etc.)
  • Workflow policy: apps/occurrences/services/workflow_policy.py
  • Public submission: apps/occurrences/views.py → public_submit
  • Admin UI: apps/occurrences/admin.py using Unfold
  • Background tasks: apps/occurrences/tasks.py (SLA checks, escalations)
  • WebSocket: apps/occurrences/consumers.py for real-time updates