HH/apps/observations

Observations App

Staff observation reporting module for Al Hammadi Hospital.

Overview

This app allows any staff member at Al Hammadi to report issues they notice. Reporting can be anonymous (no login required), but the user may optionally provide Staff ID and Name.

PX360 staff will triage the observation and route it to the responsible department and/or create an action in the PX Action Center.

Features

• Anonymous Reporting: No login required for submission
• Optional Identification: Staff can optionally provide their ID and name
• Tracking System: Unique tracking codes for public status lookup
• Full Lifecycle Management: Status tracking from NEW to CLOSED
• Department Routing: Assign observations to responsible departments
• Action Center Integration: Convert observations to PX Actions
• Notification System: Automated notifications for triage team and assignees
• Bilingual Support: English and Arabic category names

Routes

Public Routes (No Login Required)

Route	Method	Description
/observations/new/	GET/POST	Submit new observation
/observations/submitted/<tracking_code>/	GET	Success page with tracking code
/observations/track/	GET	Track observation by code

Internal Routes (Login Required)

Route	Method	Description
/observations/	GET	List all observations with filters
/observations/<id>/	GET	Observation detail with timeline
/observations/<id>/triage/	POST	Triage observation
/observations/<id>/status/	POST	Change observation status
/observations/<id>/note/	POST	Add internal note
/observations/<id>/convert-to-action/	GET/POST	Convert to PX Action

Category Management (Permission Required)

Route	Method	Description
/observations/categories/	GET	List categories
/observations/categories/create/	GET/POST	Create category
/observations/categories/<id>/edit/	GET/POST	Edit category
/observations/categories/<id>/delete/	POST	Delete category

Permissions

Permission	Description
observations.view_observation	Can view observations
observations.triage_observation	Can triage observations
observations.manage_categories	Can manage observation categories

Models

ObservationCategory

• name_en, name_ar: Bilingual names
• description: Category description
• icon: Bootstrap icon class
• sort_order: Display order
• is_active: Active status

Observation

• tracking_code: Unique code (e.g., OBS-ABC123)
• category: FK to ObservationCategory
• title: Optional short title
• description: Required detailed description
• severity: LOW, MEDIUM, HIGH, CRITICAL
• location_text: Where the issue was observed
• incident_datetime: When the issue occurred
• reporter_staff_id, reporter_name, reporter_phone, reporter_email: Optional reporter info
• status: NEW, TRIAGED, ASSIGNED, IN_PROGRESS, RESOLVED, CLOSED, REJECTED, DUPLICATE
• assigned_department: FK to Department
• assigned_to: FK to User
• action_id: Link to PX Action if converted

ObservationAttachment

• observation: FK to Observation
• file: Uploaded file
• filename, file_type, file_size: File metadata

ObservationNote

• observation: FK to Observation
• note: Note text
• created_by: FK to User
• is_internal: Internal-only flag

ObservationStatusLog

• observation: FK to Observation
• from_status, to_status: Status transition
• changed_by: FK to User
• comment: Optional comment

Workflow

1. Submission: Staff submits observation via public form (anonymous or identified)
2. Notification: PX360 triage team receives notification
3. Triage: Staff triages observation, assigns department/owner
4. Assignment: Assigned user receives notification
5. Resolution: Issue is resolved and closed
6. Action Center: Optionally convert to PX Action for formal tracking

Installation

1. Add to INSTALLED_APPS in settings:

LOCAL_APPS = [
    ...
    'apps.observations',
]

2. Add URL configuration:

urlpatterns = [
    ...
    path('observations/', include('apps.observations.urls')),
]

3. Run migrations:

python manage.py makemigrations observations
python manage.py migrate

4. Seed default categories:

python manage.py seed_observation_categories

Management Commands

seed_observation_categories

Seeds default observation categories with bilingual names.

# Seed categories (update existing)
python manage.py seed_observation_categories

# Clear and reseed
python manage.py seed_observation_categories --clear

Testing

Run tests:

python manage.py test apps.observations

Integration

Action Center

Observations can be converted to PX Actions via the "Convert to Action" feature. This creates a linked action with:

• Title derived from observation
• Description with observation details
• Priority mapped from severity
• Link back to original observation

Notifications

The app integrates with apps.notifications to send:

• New observation alerts to PX Admin group
• Assignment notifications to assigned users
• Resolution notifications to stakeholders

Templates

Templates are located in templates/observations/:

• public_new.html: Public submission form
• public_success.html: Success page with tracking code
• public_track.html: Public tracking page
• observation_list.html: Internal list view
• observation_detail.html: Internal detail view
• convert_to_action.html: Convert to action form
• category_list.html: Category management list
• category_form.html: Category create/edit form

API Endpoints

AJAX Helper

• GET /observations/api/users-by-department/?department_id=<id>: Get users for a department

Security

• Public forms include honeypot field for spam protection
• Internal views require authentication
• Category management requires specific permission
• RBAC filtering based on user's hospital/department