helpdesk_rating_five_stars/INSTALL.md

Installation Guide - Helpdesk Rating Five Stars

Quick Installation

Prerequisites

Before installing, ensure you have:

• ✅ Odoo 18.0 or higher installed
• ✅ Helpdesk module installed and configured
• ✅ Database backup (recommended)
• ✅ Administrator access to Odoo

Installation Steps

1. Copy Module Files

Copy the module to your Odoo addons directory:

# For standard addons directory
sudo cp -r helpdesk_rating_five_stars /opt/odoo/addons/

# For custom addons directory
sudo cp -r helpdesk_rating_five_stars /opt/odoo/custom/addons/

Set proper permissions:

sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars
# or
sudo chown -R odoo:odoo /opt/odoo/custom/addons/helpdesk_rating_five_stars

2. Update Odoo Configuration

Edit your odoo.conf file to include the addons path:

[options]
addons_path = /opt/odoo/addons,/opt/odoo/custom/addons

3. Restart Odoo Server

# Using systemd
sudo systemctl restart odoo

# Or using service
sudo service odoo restart

# Or if running manually
./odoo-bin -c /etc/odoo/odoo.conf

4. Update Apps List

1. Log in to Odoo as Administrator
2. Navigate to Apps menu
3. Click Update Apps List (top-right menu)
4. Click Update in the confirmation dialog
5. Wait for the list to refresh

5. Install the Module

1. In the Apps menu, remove the "Apps" filter
2. Search for "Helpdesk Rating Five Stars"
3. Click the Install button
4. Wait for installation to complete (usually 10-30 seconds)
5. You'll see a success notification

6. Verify Installation

Check that the module is working:

• Go to Helpdesk → Tickets
• Open any ticket with a rating
• Verify stars are displayed instead of emoticons
• Check that email templates show 5 stars
• Test rating submission from a test email

Detailed Installation

For Development Environment

# Clone or copy module
cd /path/to/odoo/custom/addons
cp -r /path/to/helpdesk_rating_five_stars .

# Install in development mode
./odoo-bin -c odoo.conf -d your_database -i helpdesk_rating_five_stars --dev=all

# With test mode
./odoo-bin -c odoo.conf -d test_database -i helpdesk_rating_five_stars --test-enable --stop-after-init

For Production Environment

# 1. Backup database first!
pg_dump -U odoo -d production_db > backup_$(date +%Y%m%d).sql

# 2. Copy module
sudo cp -r helpdesk_rating_five_stars /opt/odoo/addons/
sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars

# 3. Restart Odoo
sudo systemctl restart odoo

# 4. Install via web interface (recommended)
# Or via command line:
./odoo-bin -c /etc/odoo/odoo.conf -d production_db -i helpdesk_rating_five_stars --stop-after-init

For Docker Environment

# Add to your Dockerfile
COPY helpdesk_rating_five_stars /mnt/extra-addons/helpdesk_rating_five_stars

# Or mount as volume in docker-compose.yml
volumes:
  - ./helpdesk_rating_five_stars:/mnt/extra-addons/helpdesk_rating_five_stars

Then:

# Rebuild and restart container
docker-compose down
docker-compose up -d

# Install module
docker-compose exec odoo odoo -d your_database -i helpdesk_rating_five_stars --stop-after-init

Post-Installation

Verify Migration

Check that existing ratings were migrated:

-- Connect to database
psql -U odoo -d your_database

-- Check rating distribution
SELECT rating, COUNT(*) as count
FROM rating_rating
WHERE rating > 0
GROUP BY rating
ORDER BY rating;

-- Expected results: ratings should be in 1-5 range
-- Old 0-3 ratings should be converted to 0, 3, 4, 5

Check Server Logs

# View recent logs
tail -n 100 /var/log/odoo/odoo-server.log

# Look for migration messages
grep -i "rating migration" /var/log/odoo/odoo-server.log

# Check for errors
grep -i "error" /var/log/odoo/odoo-server.log | grep -i "rating"

Test Functionality

1. Test Email Rating:

   • Create a test ticket
   • Close the ticket
   • Send rating request email
   • Click a star in the email
   • Verify rating is recorded

2. Test Web Rating:

   • Access rating form via link
   • Hover over stars (should highlight)
   • Click a star to select
   • Submit the form
   • Verify confirmation page

3. Test Backend Display:

   • Open ticket with rating
   • Verify stars display correctly
   • Check list view shows stars
   • Check kanban view shows stars

4. Test Reports:

   • Go to Helpdesk → Reporting → Ratings
   • Verify average uses 0-5 scale
   • Test filtering by rating
   • Export data and verify values

Troubleshooting Installation

Module Not Found

Problem: Module doesn't appear in Apps list

Solution:

# Check module is in addons path
ls -la /opt/odoo/addons/helpdesk_rating_five_stars

# Check odoo.conf has correct addons_path
cat /etc/odoo/odoo.conf | grep addons_path

# Restart Odoo
sudo systemctl restart odoo

# Update apps list again

Installation Fails

Problem: Error during installation

Solution:

# Check server logs
tail -f /var/log/odoo/odoo-server.log

# Common issues:
# - Missing dependencies: Install helpdesk, rating, mail, web modules first
# - Permission errors: Check file ownership and permissions
# - Database errors: Check PostgreSQL logs

Migration Errors

Problem: Existing ratings not converted

Solution:

# Check migration logs
grep -i "migration" /var/log/odoo/odoo-server.log

# Manually run migration if needed
# (Contact administrator or see hooks.py)

# Verify database state
psql -U odoo -d your_database -c "SELECT rating, COUNT(*) FROM rating_rating GROUP BY rating;"

Stars Not Displaying

Problem: Stars don't show in backend

Solution:

# Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

# Check static files are served
curl http://your-odoo-url/helpdesk_rating_five_stars/static/src/js/rating_stars.js

# Restart Odoo with assets rebuild
./odoo-bin -c odoo.conf -d your_database --dev=all

# Check browser console for errors
# Open browser DevTools (F12) and check Console tab

Uninstallation

If you need to uninstall the module:

Via Web Interface

1. Go to Apps menu
2. Remove "Apps" filter
3. Search for "Helpdesk Rating Five Stars"
4. Click Uninstall
5. Confirm uninstallation

Note: Ratings will remain in 0-5 scale after uninstallation. They will not be automatically converted back to 0-3.

Via Command Line

./odoo-bin -c odoo.conf -d your_database -u helpdesk_rating_five_stars --stop-after-init

Complete Removal

# Uninstall module first (via web or command line)

# Remove module files
sudo rm -rf /opt/odoo/addons/helpdesk_rating_five_stars

# Restart Odoo
sudo systemctl restart odoo

Upgrade

To upgrade to a newer version:

# 1. Backup database
pg_dump -U odoo -d production_db > backup_before_upgrade.sql

# 2. Replace module files
sudo rm -rf /opt/odoo/addons/helpdesk_rating_five_stars
sudo cp -r helpdesk_rating_five_stars_new_version /opt/odoo/addons/helpdesk_rating_five_stars
sudo chown -R odoo:odoo /opt/odoo/addons/helpdesk_rating_five_stars

# 3. Restart Odoo
sudo systemctl restart odoo

# 4. Upgrade module
./odoo-bin -c odoo.conf -d production_db -u helpdesk_rating_five_stars --stop-after-init

# 5. Test functionality

Support

For installation support:

• Documentation: See README.md and USER_GUIDE.md
• Logs: Check /var/log/odoo/odoo-server.log
• Administrator: Contact your Odoo system administrator
• Community: Odoo community forums

Checklist

Use this checklist to ensure proper installation:

• Prerequisites verified (Odoo 18, Helpdesk installed)
• Database backed up
• Module files copied to addons directory
• File permissions set correctly
• Odoo configuration updated
• Odoo server restarted
• Apps list updated
• Module installed successfully
• Migration completed (check logs)
• Email templates show 5 stars
• Backend views show stars
• Reports use 0-5 scale
• Test rating submission works
• Mobile responsive design verified
• Keyboard navigation tested
• No errors in server logs
• No errors in browser console

---

Installation Time: 5-10 minutes
Difficulty: Easy
Required Access: Administrator

Version: 1.0
Last Updated: 2024-11-25