Common Issues

This guide addresses the most frequently encountered issues with the Drag & Drop extension and provides step-by-step solutions for quick problem resolution.

Installation and Setup Issues

Extension Not Appearing After Installation

Symptoms: - Extension shows as "Installed" in Extension Management - FactBox not visible on supported pages - No drag-and-drop functionality available

Possible Causes and Solutions:

1. Permission Set Not Assigned

Problem: User lacks required permissions
Solution: 
- Navigate to Users page in Business Central
- Select affected user
- Add "QTEAM DRAG AND DROP" permission set
- Sign out and sign back in to refresh permissions

2. Q-Team App Authenticator Missing

Problem: Required dependency not installed
Solution:
- Check Extension Management for "Q-Team App Authenticator"
- If missing, install from AppSource (SaaS) or manually (On-Premise)
- Verify both extensions show "Installed" status

3. Browser Cache Issues

Problem: Cached page layouts preventing FactBox display
Solution:
- Clear browser cache and cookies
- Refresh Business Central page (Ctrl+F5)
- Try different browser for comparison
- Sign out and sign back in

4. Page Layout Conflicts

Problem: Existing customizations interfering with FactBox
Solution:
- Reset page personalization: Settings > Personalize > Reset
- Check for conflicting page extensions
- Contact administrator for custom modification review

License Activation Problems

Symptoms: - Extension installed but functionality not working - Error messages about license validation - Q-Team Authenticator not responding

Possible Causes and Solutions:

1. Internet Connectivity Issues (On-Premise)

Problem: Server cannot connect to Q-Team license validation
Solution:
- Test connectivity: ping q-teamsolutions.com from server
- Check firewall rules for outbound HTTPS (port 443)
- Verify proxy configuration if applicable
- Contact network administrator for access configuration

2. License Registration Failure

Problem: License not properly registered with Q-Team
Solution:
- Verify free license registration at Q-Team Solutions website
- Check email for license confirmation
- Contact Q-Team support for license status verification
- Ensure Business Central license includes required Q-Team modules (On-Premise)

3. User License Limitations

Problem: User license type not supported
Solution:
- Verify user has Essential, Premium, or Team Member license
- External user licenses not supported for file attachments
- Contact administrator for license upgrade if needed

Functional Issues

Drag-and-Drop Not Working

Symptoms: - Files cannot be dragged onto FactBox area - No visual feedback during drag operations - Drop events not triggering

Possible Causes and Solutions:

1. Browser Compatibility Issues

Problem: Browser lacks drag-and-drop support
Solution:
- Update browser to latest version
- Switch to supported browser (Edge, Chrome, Firefox)
- Disable browser extensions that might interfere
- Test in incognito/private browsing mode

2. JavaScript Disabled or Blocked

Problem: JavaScript required for drag-and-drop disabled
Solution:
- Enable JavaScript in browser settings
- Whitelist Business Central domain in security settings
- Disable JavaScript-blocking browser extensions
- Check corporate firewall for JavaScript filtering

3. File System Access Restricted

Problem: Browser security preventing file access
Solution:
- Check browser permissions for file access
- Disable strict security policies temporarily for testing
- Try files from different locations (desktop vs. network drives)
- Contact IT for browser policy configuration

4. Control Add-in Loading Issues

Problem: JavaScript components not loading properly
Solution:
- Check browser console for JavaScript errors
- Clear browser cache and reload page
- Disable browser extensions interfering with content loading
- Try different network connection for testing

File Upload Failures

Symptoms: - Files appear to upload but don't appear in attachments - Error messages during upload process - Upload starts but never completes

Possible Causes and Solutions:

1. File Size Limitations

Problem: Files exceed maximum allowed size
Solution:
- Check file size against recommended limits (50MB max)
- Compress large files before uploading
- Split large documents into smaller files
- Contact administrator for size limit adjustment

2. File Type Restrictions

Problem: File type not supported or blocked
Solution:
- Verify file type in supported formats list
- Rename file with proper extension if needed
- Convert to supported format (e.g., PDF)
- Check corporate security policies for file type restrictions

3. Network Connectivity Issues

Problem: Network interruption during upload
Solution:
- Check internet connection stability
- Try upload during off-peak hours
- Use wired connection instead of WiFi
- Contact network administrator for bandwidth issues

4. Server Storage Issues

Problem: Database storage full or restricted
Solution:
- Contact administrator to check database storage capacity
- Review document retention policies for cleanup
- Monitor Document Attachment table growth
- Plan for storage expansion if needed

Performance Issues

Symptoms: - Slow response when dragging files - Extended upload times - Browser freezing during file operations

Possible Causes and Solutions:

1. Large File Processing

Problem: Files too large for efficient processing
Solution:
- Optimize file sizes before upload
- Upload files individually rather than in batches
- Schedule large uploads during off-peak hours
- Consider alternative storage for very large files

2. Network Bandwidth Limitations

Problem: Insufficient bandwidth for file uploads
Solution:
- Test upload speed with network speed test
- Schedule uploads during low-traffic periods
- Use wired connection for large file uploads
- Contact network administrator for bandwidth allocation

3. Browser Resource Constraints

Problem: Browser running out of memory or CPU
Solution:
- Close unnecessary browser tabs and applications
- Restart browser before large upload operations
- Increase browser memory allocation if possible
- Use dedicated browser session for Business Central

4. Business Central Server Performance

Problem: Server overloaded or under-resourced
Solution:
- Contact administrator to monitor server performance
- Schedule uploads during server maintenance windows
- Review concurrent user load during upload times
- Plan server resource upgrades if needed

User Experience Issues

Visual Interface Problems

Symptoms: - FactBox appears but looks incorrect - Missing visual feedback during drag operations - Layout issues on different screen sizes

Possible Causes and Solutions:

1. CSS Loading Issues

Problem: Stylesheets not loading properly
Solution:
- Clear browser cache and restart
- Disable browser extensions affecting CSS
- Check browser console for CSS loading errors
- Try different browser for comparison

2. Display Resolution Issues

Problem: Interface not optimized for screen size
Solution:
- Adjust browser zoom level (90-110%)
- Use supported screen resolution (minimum 1024x768)
- Check FactBox sizing in page customization
- Contact administrator for page layout optimization

3. Browser Zoom and Scaling

Problem: Browser zoom affecting interface layout
Solution:
- Reset browser zoom to 100% (Ctrl+0)
- Adjust Windows display scaling if applicable
- Use browser's standard zoom levels
- Avoid extreme zoom settings for optimal experience

Accessibility Issues

Symptoms: - Interface not accessible with screen readers - Keyboard navigation not working properly - Color contrast issues

Possible Causes and Solutions:

1. Screen Reader Compatibility

Problem: Screen reader not recognizing drag-drop interface
Solution:
- Use alternative click-to-browse functionality
- Enable browser accessibility features
- Contact Q-Team support for accessibility enhancements
- Consider alternative document attachment methods

2. Keyboard Navigation Issues

Problem: Cannot navigate interface with keyboard only
Solution:
- Use Tab key to navigate to FactBox area
- Use Enter key to activate file browser
- Enable browser accessibility mode
- Contact administrator for accessibility configuration

Advanced Troubleshooting

Diagnostic Information Collection

Performance Diagnostics:

1. Browser Information:
   - Browser type and version
   - Operating system details
   - JavaScript console error messages
   - Network tab timing information

2. Business Central Environment:
   - Extension version information
   - User permission set assignments
   - Page customization details
   - Error log entries

3. File Information:
   - File sizes and types being uploaded
   - Upload timing and failure patterns
   - Network connectivity details
   - Server performance metrics

Log Analysis

Browser Console Errors:

Common JavaScript Errors:
- "FileReader not supported" → Browser compatibility issue
- "Access denied" → File system permissions issue  
- "Network error" → Connectivity or server issue
- "Out of memory" → File too large for browser processing

Business Central Telemetry (SaaS):

Key Metrics to Monitor:
- Extension load times and errors
- File upload success/failure rates
- User activity patterns and adoption
- Performance impact on overall system

Escalation Procedures

When to Contact Q-Team Support: - Extension installation failures after following documentation - License activation issues not resolved by standard procedures - Functionality completely unavailable across multiple users - Performance issues affecting business operations

When to Contact Microsoft Support: - Business Central platform issues unrelated to Drag & Drop - Underlying permission or security configuration problems - Database or connectivity issues affecting multiple extensions

When to Contact Internal IT Support: - Network connectivity and firewall configuration - Browser policy and security configuration - Server resource and performance issues - User training and change management support

Prevention Strategies

Proactive Monitoring: - Regular extension functionality testing - User feedback collection and analysis - Performance baseline monitoring - Update and maintenance scheduling

User Education: - Comprehensive training on proper usage procedures - Clear documentation of supported file types and sizes - Regular communication of best practices - Feedback mechanisms for user issues and suggestions

System Maintenance: - Regular browser and Business Central updates - Periodic extension functionality verification - Database maintenance and optimization - Security policy review and updates

This troubleshooting guide provides comprehensive solutions for the most common issues encountered with the Drag & Drop extension. For issues not covered in this guide, contact Q-Team Solutions support with detailed diagnostic information for specialized assistance.