Troubleshooting Guide

Quick Reference

This guide helps you quickly identify and resolve common LTI integration issues. Issues are organized by user type and include step-by-step solutions.

For Administrators

Tool Installation Issues

"Tool Not Available in Course"

Symptoms: Teachers can't find PrepareBuddy when creating assignments Common Causes: - Tool installed at course level instead of account level - Tool not activated after installation - Incorrect privacy settings

Solutions: 1. Verify Account-Level Installation: - Install PrepareBuddy at institution/account level, not individual courses - Check that tool is enabled and active - Verify tool appears in global tool list

1. Check Privacy Settings:
2. Ensure privacy level is set to "Public"
3. Enable sharing of user name and email

4. Allow grade passback

5. Reactivate Tool:

6. Deactivate and reactivate the PrepareBuddy tool
7. Clear any cached configurations
8. Test with a sample course

"Invalid Consumer Key" Error

Symptoms: Launch fails with authentication error Common Causes: - Consumer key doesn't match between LMS and PrepareBuddy - Typing errors in key or secret - Case sensitivity issues

Solutions: 1. Verify Exact Match: - Compare consumer key character by character - Check for extra spaces or hidden characters - Ensure case sensitivity is correct

1. Request New Credentials:
2. Contact support@preparebuddy.com for new credentials
3. Specify your LMS type and version

4. Update both LMS and PrepareBuddy with new credentials

5. Test Configuration:

6. Use test course to verify setup
7. Check LMS logs for detailed error messages
8. Verify SSL/HTTPS configuration

"Grade Passback Not Working"

Symptoms: Student grades don't appear in LMS gradebook Common Causes: - Grade passback not enabled in LMS configuration - Assignment not configured to accept grades - Network connectivity issues

Solutions: 1. Enable Grade Passback: - Verify "Accept grades from tool" is enabled - Check assignment has points possible set - Ensure submission type is "External Tool"

1. Test Grade Flow:
2. Create test assignment with test student
3. Complete assessment and verify grade appears

4. Check timing (should be within 1 minute)

5. Check Network Configuration:

6. Verify PrepareBuddy can reach your LMS
7. Check firewall settings for outbound connections
8. Ensure HTTPS is properly configured

Configuration Issues

"SSL/HTTPS Problems"

Symptoms: Tool won't launch, security warnings Common Causes: - Mixed HTTP/HTTPS content - Invalid SSL certificates - Incorrect URL configuration

Solutions: 1. Verify HTTPS Configuration: - All URLs must use HTTPS in production - Check SSL certificate validity - Ensure no mixed content warnings

1. Update URLs:
2. Launch URL: https://preparebuddy.com/lti/launch/
3. Config URL: https://preparebuddy.com/lti/config/

4. Verify no HTTP fallbacks

5. Test with Different Browsers:

6. Clear browser cache and cookies
7. Try incognito/private mode
8. Test with multiple browsers

"Custom Parameters Not Working"

Symptoms: Account linking fails, wrong user information Common Causes: - Custom parameters not properly configured - LMS doesn't support specific parameters - Privacy settings block parameter sharing

Solutions: 1. Verify Parameter Syntax: user_email=$Person.email.primary canvas_user_login_id=$Canvas.user.loginId

1. Check LMS Support:
2. Verify your LMS version supports custom parameters
3. Check LMS documentation for correct syntax

4. Test with minimal parameter set first

5. Debug Parameter Passing:

6. Check LMS logs for parameter values
7. Contact PrepareBuddy support for parameter verification
8. Test with default configuration first

For Teachers

Assignment Creation Issues

"External Tool Not Available"

Symptoms: Can't select PrepareBuddy when creating assignments Common Causes: - Tool not installed in course - Insufficient permissions - Course-level configuration needed

Solutions: 1. Check Tool Availability: - Verify PrepareBuddy appears in external tools list - Check with administrator if tool is missing - Ensure you have instructor permissions

1. Install at Course Level (if needed):
2. Course Settings → Apps → Browse More Apps
3. Search for and install PrepareBuddy

4. Configure with provided credentials

5. Permission Check:

6. Verify you have instructor role
7. Check course-level permissions
8. Contact administrator if needed

"Assignment Won't Save"

Symptoms: Error when trying to save PrepareBuddy assignment Common Causes: - Missing required fields - Point value not set - Tool configuration incomplete

Solutions: 1. Check Required Fields: - Assignment name must be provided - Points possible must be set (not 0) - Submission type must be "External Tool"

1. Verify Tool Selection:
2. Ensure PrepareBuddy is selected as external tool
3. Check tool configuration is complete

4. Try refreshing page and recreating assignment

5. Test with Simple Assignment:

6. Create minimal assignment first
7. Add complexity once basic assignment works
8. Check LMS status page for known issues

Grade Management Issues

"Grades Not Appearing"

Symptoms: Student completes work but grade doesn't sync Common Causes: - Assignment not configured for grade passback - Student didn't complete gradeable activity - Grade sync delay

Solutions: 1. Verify Assignment Configuration: - Check grade passback is enabled - Verify points possible is set - Ensure assignment uses External Tool submission

1. Confirm Student Activity:
2. Student must complete actual assessment, not just browse
3. Check if student finished entire activity

4. Verify student saw completion message

5. Check Timing:

6. Wait 1-2 minutes for sync
7. Refresh gradebook page
8. Contact support if delay exceeds 5 minutes

"Wrong Grades Syncing"

Symptoms: Grades appear but values are incorrect Common Causes: - Score scaling issues - Multiple attempt handling - Percentage vs. point confusion

Solutions: 1. Check Score Scaling: - PrepareBuddy sends percentage scores - LMS scales to assignment point value - Verify assignment points match expected scale

1. Multiple Attempt Policy:
2. Determine if using highest, latest, or average score
3. Check LMS multiple attempt settings

4. Clarify policy with students

5. Manual Grade Verification:

6. Check student's actual PrepareBuddy score
7. Calculate expected LMS grade
8. Contact support if calculation doesn't match

For Students

Access Issues

"Can't Launch Assignment"

Symptoms: Clicking assignment link doesn't work Common Causes: - Browser compatibility issues - Pop-up blockers - Cache/cookie problems

Solutions: 1. Browser Troubleshooting: - Try different browser (Chrome, Firefox, Safari) - Clear browser cache and cookies - Disable browser extensions temporarily

1. Pop-up and Security Settings:
2. Allow pop-ups for your LMS domain
3. Check security settings aren't blocking

4. Try incognito/private browsing mode

5. Network Connectivity:

6. Check internet connection
7. Try different network (mobile hotspot)
8. Contact IT if institutional network blocks access

"Wrong Account or Email Showing"

Symptoms: PrepareBuddy shows different email than expected Common Causes: - Multiple PrepareBuddy accounts - Email mismatch between LMS and PrepareBuddy - Account linking issues

Solutions: 1. Email Verification: - Check what email your LMS uses - Verify your PrepareBuddy account email - Ensure both systems use same email address

1. Account Consolidation:
2. Contact support@preparebuddy.com to merge accounts
3. Provide both email addresses and institution name

4. Wait for account linking confirmation

5. Create New Account:

6. If other solutions don't work, create new PrepareBuddy account
7. Use same email as your LMS
8. Contact support to transfer progress if needed

Performance Issues

"Slow Loading or Timeouts"

Symptoms: PrepareBuddy takes long time to load or times out Common Causes: - Slow internet connection - High server load - Browser performance issues

Solutions: 1. Connection Optimization: - Check internet speed and stability - Close unnecessary browser tabs and programs - Try wired connection instead of WiFi

1. Browser Optimization:
2. Clear browser cache and cookies
3. Disable unnecessary extensions

4. Update browser to latest version

5. Alternative Access:

6. Try accessing during off-peak hours
7. Use mobile app if available
8. Access PrepareBuddy directly (not through LMS)

"Features Not Working Properly"

Symptoms: Some PrepareBuddy features don't work in LMS Common Causes: - iframe restrictions - JavaScript conflicts - Mobile compatibility issues

Solutions: 1. Launch in New Window: - Look for "Launch in new window" option - Open PrepareBuddy in separate tab - Complete work in standalone window

1. Browser Compatibility:
2. Try desktop browser instead of mobile
3. Update browser to latest version

4. Enable JavaScript if disabled

5. Direct Access:

6. Access PrepareBuddy directly at preparebuddy.com
7. Log in with your account credentials
8. Complete work outside LMS if necessary

Advanced Troubleshooting

For IT Staff

Log Analysis

LMS Logs to Check: - LTI launch requests and responses - Authentication failures - Grade passback attempts - Network connectivity errors

PrepareBuddy Logs (available on request): - Launch success/failure rates - Grade sync attempts and results - Account linking activities - Performance metrics

Network Configuration

Firewall Requirements: - Allow outbound HTTPS (443) to preparebuddy.com - Enable inbound connections for grade passback - Whitelist PrepareBuddy IP addresses if needed

Load Balancer Configuration: - Ensure session affinity for LTI launches - Configure proper timeout values - Monitor for SSL termination issues

Database Issues

Common Database Problems: - Connection pool exhaustion - Slow query performance - Transaction conflicts

Monitoring Points: - LTI launch success rates - Grade passback success rates - User session duration - Error rates by time of day

Security Troubleshooting

OAuth Signature Validation

Common Issues: - Clock synchronization problems - URL encoding differences - Parameter ordering issues

Debug Steps: 1. Verify server time synchronization 2. Check OAuth parameter encoding 3. Validate signature calculation 4. Test with known good parameters

SSL/TLS Issues

Certificate Problems: - Expired certificates - Intermediate certificate missing - Cipher suite compatibility

Resolution Steps: 1. Verify certificate chain 2. Check certificate expiration 3. Test with SSL analysis tools 4. Update cipher suite configuration

Escalation Procedures

Level 1 Support (Self-Service)

• Check this troubleshooting guide
• Try basic browser troubleshooting
• Test with different devices/networks

Level 2 Support (Institution)

• Contact your LMS administrator
• Check institutional IT resources
• Verify network and security settings

Level 3 Support (PrepareBuddy)

Email Support: support@preparebuddy.com Include in your request: - Description of issue and steps to reproduce - Screenshots or error messages - LMS type and version - Browser and operating system - Student/teacher usernames (not passwords)

Phone Support: 1-800-PREPARE (1-800-773-7273) For urgent issues affecting multiple users

Emergency Escalation

For system-wide outages or security issues: - Email: emergency@preparebuddy.com - Phone: 1-800-PREPARE (mention emergency) - Include: Institution name, number of affected users, business impact

Prevention and Monitoring

Regular Maintenance

• Monthly: Test LTI integration with sample assignments
• Semester Start: Verify all courses can access PrepareBuddy
• After Updates: Test integration after LMS updates
• Peak Times: Monitor performance during high-usage periods

Monitoring Tools

• LMS Analytics: Track assignment usage and success rates
• Browser Console: Check for JavaScript errors
• Network Monitoring: Monitor connection quality and speed
• User Feedback: Collect and track user-reported issues

Best Practices

• Documentation: Keep configuration documentation updated
• Testing Environment: Maintain test environment for troubleshooting
• Communication: Establish clear escalation procedures
• Training: Ensure staff know how to troubleshoot common issues

Success Metrics

A well-functioning LTI integration should show: - 95%+ Launch Success Rate: Students can consistently access assignments - <10 Second Grade Sync: Grades appear quickly in LMS - <5% Support Tickets: Few users need help with access - Real Account Usage: Students see their actual email addresses - Cross-Platform Compatibility: Works consistently across all browsers and devices

Regular monitoring of these metrics helps identify issues before they impact users significantly.