marwan/HH

2026-01-24 15:27:27 +03:00

12 KiB

Raw Blame History

Complaint to Appreciation Conversion Feature

Overview

The Complaint to Appreciation Conversion feature allows PX staff to convert appreciation-type complaints into formal Appreciation records. This feature helps capture positive patient feedback and recognize staff members for excellent service.

Feature Summary

Target Audience: PX Admins and Hospital Admins
Complaint Type: Only works for complaints marked as type "appreciation"
Purpose: Convert positive feedback into a formal Appreciation record
Integration: Links appreciation back to original complaint
Automation: Optional auto-close of complaint after conversion

How It Works

1. When to Use

The "Convert to Appreciation" button appears in the Quick Actions sidebar when:

The complaint type is "appreciation" (not "complaint")
The complaint has NOT already been converted to an appreciation

2. Conversion Process

Click Button: User clicks "Convert to Appreciation" button in Quick Actions sidebar
Open Modal: A modal opens with pre-filled fields
Configure Options:
- Recipient: Select staff member or physician (defaults to assigned staff if available)
- Category: Select appreciation category (defaults to "Patient Feedback Appreciation")
- Message (English): Editable text pre-filled from complaint description
- Message (Arabic): Editable text pre-filled from complaint short_description_ar
- Visibility: Choose who can see the appreciation
- Sender: Choose anonymous or patient as sender
- Close Complaint: Checkbox to auto-close complaint after conversion
Submit: Click "Convert" button to create appreciation
Result:
- Appreciation record is created
- Notification is sent to recipient
- Complaint metadata is updated with appreciation link
- Timeline entry is created for conversion
- Optionally, complaint is closed
- User is redirected to appreciation detail page

Data Flow

From Complaint to Appreciation

Complaint Field	Appreciation Field	Notes
`description`	`message_en`	Can be edited in modal
`short_description_ar`	`message_ar`	Can be edited in modal
`hospital`	`hospital`	Auto-mapped
`department`	`department`	Auto-mapped
`patient`	`sender`	Only if patient user account exists and not anonymous
`staff`	`recipient`	Default recipient (can be changed)

Metadata Linkages

Complaint Metadata (stored in complaint.metadata):

{
  "appreciation_id": "uuid-of-created-appreciation",
  "converted_to_appreciation": true,
  "converted_to_appreciation_at": "2026-01-16T00:30:00Z",
  "converted_by": "uuid-of-user"
}

Appreciation Metadata (stored in appreciation.metadata):

{
  "source_complaint_id": "uuid-of-original-complaint",
  "source_complaint_title": "Original complaint title",
  "converted_from_complaint": true,
  "converted_by": "uuid-of-user",
  "converted_at": "2026-01-16T00:30:00Z"
}

API Endpoints

POST /complaints/api/complaints/{id}/convert_to_appreciation/

Converts a complaint to an appreciation record.

Request Body:

{
  "recipient_type": "user",  // or "physician"
  "recipient_id": "uuid",
  "category_id": "uuid",
  "message_en": "English message text",
  "message_ar": "Arabic message text",
  "visibility": "private",  // "private", "department", "hospital", "public"
  "is_anonymous": true,
  "close_complaint": false
}

Response (201 Created):

{
  "success": true,
  "message": "Complaint successfully converted to appreciation",
  "appreciation_id": "uuid-of-created-appreciation",
  "appreciation_url": "https://domain.com/appreciations/{uuid}/",
  "complaint_closed": false
}

Error Responses:

400 Bad Request:
- "Only appreciation-type complaints can be converted to appreciations"
- "This complaint has already been converted to an appreciation"
- "Recipient user not found"
- "Recipient physician not found"
- "Appreciation category not found"
404 Not Found:
- "Recipient not found"
- "Appreciation category not found"

User Interface

Button Visibility

The "Convert to Appreciation" button shows:

{% if complaint.complaint_type == 'appreciation' and not complaint.metadata.appreciation_id %}
  <!-- Show conversion button -->
{% elif complaint.metadata.appreciation_id %}
  <!-- Show "Converted to Appreciation" alert with link -->
{% endif %}

After Conversion

After a successful conversion, the complaint detail page shows:

Converted Alert: Green alert box in Quick Actions
Appreciation Link: Direct link to the created appreciation
Timeline Entry: New note in timeline showing conversion details
Complaint Status: Optionally changed to "closed"

Recipient Selection:
- Type dropdown: "Staff Member" or "Physician"
- Dynamic list of available recipients
- Defaults to assigned staff member
Category Selection:
- Dropdown of all AppreciationCategory records
- Defaults to "Patient Feedback Appreciation" (code: patient_feedback)
Messages:
- English message (required)
- Arabic message (optional)
- Pre-filled from complaint description
Visibility:
- Private: sender and recipient only
- Department: visible to department members
- Hospital: visible to all hospital staff
- Public: can be displayed publicly
Sender:
- Anonymous: hide patient identity (default)
- Patient: show patient as sender
Close Complaint:
- Checkbox option
- If checked, complaint status changes to "closed"
- Adds status update entry to timeline

Timeline Updates

Conversion Entry

When a complaint is converted to appreciation, a timeline entry is created:

ComplaintUpdate.objects.create(
    complaint=complaint,
    update_type='note',
    message=f"Converted to appreciation (Appreciation #{appreciation.id})",
    created_by=request.user,
    metadata={
        'appreciation_id': str(appreciation.id),
        'converted_from_complaint': True,
        'close_complaint': close_complaint
    }
)

Status Change Entry (if closing)

If the complaint is closed during conversion, a separate status change entry is created:

ComplaintUpdate.objects.create(
    complaint=complaint,
    update_type='status_change',
    message="Complaint closed after converting to appreciation",
    created_by=request.user,
    old_status='open',
    new_status='closed'
)

Audit Logging

All conversion actions are logged via AuditService:

AuditService.log_from_request(
    event_type='complaint_converted_to_appreciation',
    description=f"Complaint converted to appreciation: {appreciation.message_en[:100]}",
    request=request,
    content_object=complaint,
    metadata={
        'appreciation_id': str(appreciation.id),
        'close_complaint': close_complaint,
        'is_anonymous': is_anonymous
    }
)

Default Category

The "Patient Feedback Appreciation" category is created automatically by running:

python manage.py create_patient_feedback_category

This category has:

Code: patient_feedback
Name (EN): "Patient Feedback Appreciation"
Name (AR): "تقدير ملاحظات المرضى"
Hospital: None (system-wide)
Icon: bi-heart
Color: #388e3c (green)
Order: 100

JavaScript Functions

loadAppreciationCategories()

Loads appreciation categories from API and populates the category dropdown. Selects "Patient Feedback Appreciation" by default.

loadAppreciationRecipients()

Loads recipient options based on recipient type:

"user": Loads hospital staff
"physician": Loads physicians from hospital

convertToAppreciation()

Validates form data and submits conversion request to API:

Validates required fields
Shows loading state
Handles success/error responses
Redirects to appreciation detail page on success

Use Cases

Use Case 1: Quick Conversion

Patient submits positive feedback about Dr. Ahmed
Complaint is created with type "appreciation"
PX Admin reviews the complaint
PX Admin clicks "Convert to Appreciation"
Default settings are acceptable, checkbox checked to close complaint
Click "Convert"
Appreciation is created and sent to Dr. Ahmed
Complaint is closed
PX Admin is redirected to appreciation detail page

Use Case 2: Customized Conversion

Patient submits positive feedback about Nurse Fatima
Complaint is created with type "appreciation"
PX Admin reviews and wants to customize the message
PX Admin clicks "Convert to Appreciation"
Changes recipient to different staff member
Edits English and Arabic messages for better phrasing
Changes visibility to "hospital" to showcase the appreciation
Keeps "Anonymous" sender option
Leaves "Close complaint" unchecked
Click "Convert"
Appreciation is created with custom settings
Complaint remains open for further processing
PX Admin is redirected to appreciation detail page

Permissions

Only users with edit permissions on the complaint can convert it to appreciation:

PX Admins
Hospital Admins
Department Managers (for their department)

Error Handling

Validation Errors

Not an appreciation complaint: Clear error message explaining only appreciation-type complaints can be converted
Already converted: Prevents duplicate conversions, shows appreciation link
Invalid recipient: Validates recipient exists and is accessible
Invalid category: Validates category ID is valid
Missing message: Validates English message is provided

Network Errors

Failed API calls show alert with error details
Button is re-enabled for retry
No data loss on error

Future Enhancements

Potential improvements for the feature:

Bulk Conversion: Convert multiple appreciation-type complaints at once
Auto-Conversion: Automatically convert appreciation-type complaints after N days
Email Preview: Preview appreciation email before sending
Recipient Recommendations: AI-suggested recipients based on complaint content
Template Messages: Pre-configured message templates for common scenarios
Conversion History: Track all conversion attempts with reasons
Undo Conversion: Ability to reverse a conversion (delete appreciation, restore complaint)

Testing

Test Scenarios

Basic Conversion:
- Create appreciation-type complaint
- Click convert button
- Accept defaults
- Verify appreciation created
- Verify complaint metadata updated
Custom Conversion:
- Edit all fields
- Change recipient
- Edit messages
- Verify custom values saved
Close Complaint:
- Enable close checkbox
- Verify complaint status changes to "closed"
- Verify status update timeline entry
Keep Complaint Open:
- Disable close checkbox
- Verify complaint status unchanged
- Verify only conversion timeline entry
Already Converted:
- Convert a complaint
- Try to convert again
- Verify error message
- Verify appreciation link shown
Wrong Complaint Type:
- Create regular "complaint" type
- Verify no convert button
- Attempt API call directly
- Verify error response

Support

For issues or questions about the Complaint to Appreciation Conversion feature:

Check the Audit Log for conversion events
Review complaint metadata for appreciation_id
Verify appreciation record exists
Check timeline for conversion entries
Review browser console for JavaScript errors
Check Django logs for API errors

12 KiB Raw Blame History