Skip to content

From submission to closure (end-to-end lifecycle)

This page describes the typical lifecycle of an occurrence, from a citizen report to resolution and closure.

1) Submission (Citizen)

  • Citizen submits a report with a location and category.
  • The system attaches it to a municipality based on geographic boundary.
  • The system checks for duplicates based on municipality policy.

2) Intake and triage (Staff)

Staff typically: - Confirms category and information quality. - Adds internal notes if needed. - Assigns the occurrence to an operator/team (or accepts the auto-assignment).

3) Communication (Staff ↔ Citizen)

Depending on municipal configuration, staff may send: - A confirmation message (“We received your report”) - Status updates (“Work scheduled”, “Resolved”)

Messages can be standardized using templates.

4) Workflow state changes (Staff)

Municipalities can configure custom workflow states (FixMyStreet-style). - Staff move the occurrence from one state to another (only allowed transitions are permitted). - The system keeps status in sync with the workflow state group (e.g., open/in_progress/resolved/closed).

5) Priorities and SLAs (Manager + Staff)

Municipalities can define priorities that set expectations for: - First response target - Resolution target

When enabled, the system automatically computes due dates and tracks breaches.

6) Escalations (Manager)

If escalation rules are enabled: - The system checks SLA status periodically. - It can notify stakeholders by email and/or websocket alerts.

7) External routing (Optional)

Some categories may be routed to external systems: - Email - Open311 endpoint - Webhook endpoint

Routing can also be paused (queuing deliveries) for operational reasons.

8) Resolution and closure (Staff)

When the issue is resolved: - Staff set the workflow state / status accordingly. - Resolution timestamps are stored. - Citizens may receive a final update.

Behind the scenes (grounded in code)

  • Intake/triage happens through staff APIs and/or Django Admin; public creation uses OccurrenceViewSet.public_submit.
  • Custom states + transitions: OccurrenceState / OccurrenceStateTransition and OccurrenceViewSet.transition_state.
  • Templates + auto responses: ResponseTemplate / AutoResponseRule and WorkflowPolicyService.apply_auto_response.
  • SLAs: PriorityLevel and WorkflowPolicyService.calculate_sla_deadlines.
  • Escalations: EscalationRule and Celery periodic task check_sla_breaches in apps/occurrences/tasks.py.
  • Routing: CategoryRouting and WorkflowPolicyService.route_occurrence.
  • Duplicates: DuplicateDetectionSettings, OccurrenceLink.