helpdesk_rating_five_stars/USER_GUIDE.md

# Helpdesk Rating Five Stars - User Guide

## Table of Contents

1. [Introduction](#introduction)
2. [For Customers](#for-customers)
3. [For Helpdesk Agents](#for-helpdesk-agents)
4. [For Helpdesk Managers](#for-helpdesk-managers)
5. [For System Administrators](#for-system-administrators)
6. [Frequently Asked Questions](#frequently-asked-questions)

---

## Introduction

The Helpdesk Rating Five Stars module enhances Odoo's Helpdesk application by replacing the standard 3-emoticon rating system with an intuitive 5-star rating system. This guide explains how to use the new rating system for different user roles.

### What's New?

- **5 Stars Instead of 3 Emoticons**: More granular feedback options
- **Interactive Star Widget**: Click or hover to select rating
- **Email Star Links**: One-click rating directly from email
- **Better Analytics**: More precise satisfaction metrics
- **Accessible Design**: Keyboard navigation and screen reader support

---

## For Customers

### How to Rate a Ticket via Email

1. **Receive Rating Request**: After your ticket is closed, you'll receive an email asking for feedback
2. **See Five Stars**: The email contains 5 clickable star icons (⭐⭐⭐⭐⭐)
3. **Click Your Rating**: Click on the star that represents your satisfaction level:
   - ⭐ = Very Dissatisfied
   - ⭐⭐ = Dissatisfied
   - ⭐⭐⭐ = Neutral
   - ⭐⭐⭐⭐ = Satisfied
   - ⭐⭐⭐⭐⭐ = Very Satisfied
4. **Confirmation**: You'll be redirected to a thank you page confirming your rating

### How to Rate a Ticket via Web Form

1. **Access Rating Form**: Click the "Rate this ticket" link in your email or portal
2. **See Interactive Stars**: The web form displays 5 interactive stars
3. **Hover to Preview**: Move your mouse over the stars to preview your rating
4. **Click to Select**: Click on the star you want to select
5. **Submit**: Click the submit button to save your rating
6. **Confirmation**: You'll see a confirmation message

### Changing Your Rating

If you change your mind about your rating:

1. Click the rating link again (from the same email)
2. Select a different star rating
3. Your previous rating will be updated (not duplicated)

### Keyboard Navigation

For accessibility, you can use your keyboard:

- **Tab**: Navigate to the star rating widget
- **Arrow Keys**: Move between stars (left/right)
- **Enter**: Select the highlighted star
- **Tab**: Move to submit button

### Mobile Devices

The star rating works great on mobile:

- Stars are sized for easy touch interaction
- Tap any star to select your rating
- Works on all modern smartphones and tablets

---

## For Helpdesk Agents

### Viewing Ratings in Ticket Form

1. **Open a Ticket**: Navigate to Helpdesk → Tickets → [Select Ticket]
2. **Find Rating Section**: Scroll to the rating section in the form
3. **See Star Display**: Ratings appear as filled stars:
   - Example: ⭐⭐⭐⭐☆ = 4-star rating
   - Empty stars (☆) show unselected ratings

### Viewing Ratings in List View

1. **Navigate to Tickets**: Go to Helpdesk → Tickets
2. **Rating Column**: Look for the rating column in the list
3. **Compact Display**: Ratings show as stars in compact format
4. **Sort by Rating**: Click the rating column header to sort
5. **Filter by Rating**: Use filters to show tickets by rating level

### Viewing Ratings in Kanban View

1. **Switch to Kanban**: Click the kanban view icon
2. **Ticket Cards**: Each ticket card shows its rating
3. **Visual Feedback**: Quickly identify satisfaction levels
4. **Drag and Drop**: Organize tickets while seeing ratings

### Understanding Rating Values

| Stars | Rating Value | Customer Satisfaction |
|-------|--------------|----------------------|
| ⭐ | 1 | Very Dissatisfied |
| ⭐⭐ | 2 | Dissatisfied |
| ⭐⭐⭐ | 3 | Neutral |
| ⭐⭐⭐⭐ | 4 | Satisfied |
| ⭐⭐⭐⭐⭐ | 5 | Very Satisfied |

### Best Practices

- **Follow Up on Low Ratings**: Reach out to customers with 1-2 star ratings
- **Learn from High Ratings**: Identify what worked well in 5-star tickets
- **Track Your Performance**: Monitor your average rating over time
- **Request Feedback**: Encourage customers to rate their experience

---

## For Helpdesk Managers

### Viewing Rating Statistics

1. **Navigate to Reports**: Go to Helpdesk → Reporting → Ratings
2. **Dashboard Overview**: See average ratings, trends, and distributions
3. **0-5 Scale**: All statistics now use the 5-star scale
4. **Filter Options**: Filter by team, agent, time period, or rating value

### Analyzing Rating Trends

**Average Rating Calculation**:
- Based on 0-5 scale (not 0-3)
- Example: Average of 4.2 stars = High satisfaction
- Compare periods to track improvement

**Rating Distribution**:
- See how many tickets received each rating (1-5 stars)
- Identify patterns in customer satisfaction
- Spot areas needing improvement

### Filtering and Grouping

**Filter by Rating**:
1. Click "Filters" in the rating report
2. Select rating range (e.g., 4-5 stars for satisfied customers)
3. View filtered results

**Group by Dimension**:
- Group by Team: Compare team performance
- Group by Agent: Identify top performers
- Group by Time: Track trends over weeks/months
- Group by Ticket Type: Analyze satisfaction by issue type

### Exporting Rating Data

1. **Navigate to Ratings**: Go to Helpdesk → Reporting → Ratings
2. **Apply Filters**: Set desired filters and grouping
3. **Export**: Click the export button
4. **Choose Format**: Select Excel, CSV, or PDF
5. **Rating Values**: Export includes 0-5 scale values

### Setting Performance Goals

**Recommended Targets**:
- **Average Rating**: Aim for 4.0+ stars
- **5-Star Percentage**: Target 60%+ of ratings at 5 stars
- **Low Rating Rate**: Keep 1-2 star ratings below 10%
- **Response Time**: Faster response correlates with higher ratings

### Team Performance Review

**Monthly Review Process**:
1. Export rating data for the month
2. Calculate team and individual averages
3. Identify top performers (highest ratings)
4. Identify improvement areas (low ratings)
5. Provide feedback and coaching
6. Set goals for next month

---

## For System Administrators

### Installation

See the [README.md](README.md) file for detailed installation instructions.

**Quick Steps**:
1. Copy module to addons directory
2. Restart Odoo server
3. Update apps list
4. Install module
5. Verify migration completed

### Post-Installation Verification

**Check Migration**:
1. Review Odoo server logs for migration messages
2. Verify existing ratings were converted
3. Test rating submission (email and web)
4. Check backend views display stars correctly

**Verify Components**:
- [ ] Email templates show 5 stars
- [ ] Web form displays interactive widget
- [ ] Backend views show star ratings
- [ ] Reports use 0-5 scale
- [ ] Mobile responsive design works
- [ ] Keyboard navigation functions

### Configuration Options

**Email Template Customization**:
1. Go to Settings → Technical → Email → Templates
2. Search for "Helpdesk Rating Request"
3. Edit template content and styling
4. Keep star links intact (required for functionality)
5. Test email sending

**Star Icon Customization**:
1. Edit `static/src/scss/rating_stars.scss`
2. Modify star styles or replace with custom icons
3. Restart Odoo server
4. Clear browser cache
5. Verify changes in frontend

**Base URL Configuration**:
1. Go to Settings → General Settings
2. Set "Web Base URL" correctly
3. Ensure URL is accessible from internet (for email links)
4. Test rating links from email

### Monitoring and Maintenance

**Check Logs**:
```bash
# View Odoo logs
tail -f /var/log/odoo/odoo-server.log

# Filter for rating-related logs
grep -i "rating" /var/log/odoo/odoo-server.log
```

**Database Queries**:
```sql
-- Check rating distribution
SELECT rating, COUNT(*) 
FROM rating_rating 
WHERE rating > 0 
GROUP BY rating 
ORDER BY rating;

-- Check average rating
SELECT AVG(rating) 
FROM rating_rating 
WHERE rating > 0;

-- Check recent ratings
SELECT id, rating, create_date 
FROM rating_rating 
WHERE rating > 0 
ORDER BY create_date DESC 
LIMIT 10;
```

**Performance Monitoring**:
- Monitor database query performance
- Check static file serving
- Verify email sending queue
- Monitor server resource usage

### Troubleshooting

**Stars Not Displaying**:
1. Clear browser cache
2. Check browser console for JavaScript errors
3. Verify static files are served correctly
4. Restart Odoo server
5. Check file permissions

**Email Links Not Working**:
1. Verify base URL in settings
2. Check rating token validity
3. Review server logs for errors
4. Test controller route accessibility
5. Check email template syntax

**Migration Issues**:
1. Check server logs for migration errors
2. Verify database permissions
3. Check for data integrity issues
4. Consider uninstall/reinstall if needed
5. Contact support for assistance

### Security Considerations

**Token Security**:
- Tokens expire after 30 days (default)
- Tokens are cryptographically secure
- One token per rating request
- Validate tokens on every submission

**Access Control**:
- Public access for rating submission (token-based)
- Restricted modification for backend users
- Audit logging for rating changes
- Role-based permissions enforced

**Input Validation**:
- All rating values validated server-side
- SQL injection prevented through ORM
- XSS prevention in templates
- CSRF protection enabled

### Backup and Recovery

**Before Installation**:
```bash
# Backup database
pg_dump -U odoo -d production_db > backup_before_rating_module.sql

# Backup filestore
tar -czf filestore_backup.tar.gz /path/to/odoo/filestore
```

**Rollback Procedure**:
1. Uninstall module from Apps menu
2. Restore database from backup if needed
3. Restart Odoo server
4. Verify system functionality

### Upgrading

**Future Upgrades**:
1. Backup database before upgrade
2. Download new module version
3. Replace module files
4. Restart Odoo server
5. Update module from Apps menu
6. Review changelog for breaking changes
7. Test functionality thoroughly

---

## Frequently Asked Questions

### General Questions

**Q: What happens to my existing ratings?**  
A: All existing ratings are automatically migrated from the 0-3 scale to the 0-5 scale during installation. The mapping is: 0→0, 1→3, 2→4, 3→5.

**Q: Can customers change their rating?**  
A: Yes, if a customer clicks the rating link again, their previous rating will be updated (not duplicated).

**Q: Do I need to configure anything after installation?**  
A: No, the module works out of the box. All existing functionality is automatically updated.

**Q: Is the module compatible with other Odoo apps?**  
A: Yes, the module maintains full API compatibility with Odoo's rating system and works with all standard modules.

### Customer Questions

**Q: How do I rate a ticket?**  
A: Click on any of the 5 stars in the rating request email, or use the web form to select your rating.

**Q: What if I accidentally click the wrong star?**  
A: You can click the rating link again and select a different rating. Your previous rating will be updated.

**Q: Can I rate a ticket without logging in?**  
A: Yes, rating links use secure tokens so you don't need to log in.

**Q: What do the stars mean?**  
A: 1 star = Very Dissatisfied, 2 stars = Dissatisfied, 3 stars = Neutral, 4 stars = Satisfied, 5 stars = Very Satisfied.

### Agent Questions

**Q: Where can I see ratings in the backend?**  
A: Ratings appear in ticket form views, list views, and kanban views as star icons.

**Q: How do I filter tickets by rating?**  
A: Use the filter options in the ticket list view to filter by rating value (1-5 stars).

**Q: Can I manually add a rating?**  
A: Yes, if you have the appropriate permissions, you can create or modify ratings in the backend.

### Manager Questions

**Q: How are average ratings calculated?**  
A: Average ratings are calculated using the 0-5 scale. For example, if you have ratings of 3, 4, and 5, the average is 4.0.

**Q: Can I export rating data?**  
A: Yes, you can export rating data from the reporting views in Excel, CSV, or PDF format.

**Q: How do I compare team performance?**  
A: Use the rating report and group by team to compare average ratings across teams.

### Administrator Questions

**Q: How long does migration take?**  
A: Migration time depends on the number of existing ratings. Typically, it takes a few seconds to a few minutes.

**Q: Can I customize the star icons?**  
A: Yes, you can edit the SCSS file to customize star appearance or replace with custom icons.

**Q: What if migration fails?**  
A: Check the server logs for errors. You may need to fix data issues and reinstall the module.

**Q: Is the module secure?**  
A: Yes, the module implements token-based authentication, server-side validation, and follows Odoo security best practices.

---

## Support

For additional support:

- **Documentation**: Review the README.md and index.html files
- **Logs**: Check Odoo server logs for error messages
- **Administrator**: Contact your Odoo system administrator
- **Source Code**: Consult the module source code for technical details

---

**Version**: 1.0  
**Last Updated**: 2024-11-25  
**Module**: helpdesk_rating_five_stars