​
Data Import & Bulk Upload Issues

​
Excel Template Upload Problems

Problem: Upload fails with “Invalid file format” or template processing errors. Symptoms:
  • Upload button shows “Processing…” but never completes
  • Error message appears during file processing
  • Missing or incorrectly formatted data in the template
Solutions:
  1. Check File Format
    • Ensure your file is in Excel format (.xlsx or .xls)
    • Avoid using CSV files for bulk import
    • Re-save your file in Excel format if needed
  2. Validate Required Columns
    • Ensure all required columns are present with exact header names
    • Required fields are marked with asterisks (*) in the template
    • Check for typos in column headers
  3. Fix Data Reference Issues
    • Programs: Ensure program names are unique and not empty
    • Courses: Verify course codes are unique and program names exist
    • Course Sections: Confirm course codes and instructor names match existing data
    • Credentials: Check that credential names and course section references are valid
  4. Clean Data Formatting
    • Remove empty rows at the beginning of sheets
    • Ensure no merged cells in data areas
    • Use plain text formatting (avoid rich text or special characters)

​
Conflict Resolution During Import

Problem: Bulk import stops at conflict resolution screen with multiple conflicts. Symptoms:
  • System detects duplicate names or codes
  • Import process requires manual review of each conflict
  • Uncertainty about which option to choose
Solutions:
  1. Understanding Conflict Types
    • Skip Import: Keeps existing data, ignores new data
    • Replace Existing: Overwrites current data with new data
    • Create New: Adds new entry with automatic suffix
  2. Best Practices for Resolution
    • For Programs: Usually safe to skip if existing data is current
    • For Courses: Replace if you’re updating course information
    • For Instructors: Skip to maintain continuity with existing assignments
    • For Course Sections: Create new if teaching multiple sections
  3. Prevention Strategies
    • Export existing data first to check for duplicates
    • Use unique naming conventions (e.g., “Fall 2024” suffixes)
    • Clean up old data before importing new data

​
Skills Processing Issues

​
Syllabus Processing Failures

Problem: Uploaded syllabi fail to process or extract skills incorrectly. Symptoms:
  • Processing job shows “FAILED” status
  • No skills appear after processing completes
  • Processing takes longer than expected (over 30 minutes)
Solutions:
  1. File Format Issues
    • Convert Word documents (.doc/.docx) to PDF before upload
    • Ensure PDF text is selectable (not scanned images)
    • Keep file sizes under 10MB for optimal processing
  2. Content Quality Problems
    • Ensure syllabus contains clear learning outcomes or objectives
    • Add course descriptions if skills extraction is poor
    • Remove non-text elements like large images or tables
  3. Processing Configuration
    • Check your organization’s processing settings in Administration
    • Adjust confidence thresholds if getting too few/many skills
    • Review prompt templates for skill extraction accuracy

​
SOC Skills Mapping Issues

Problem: SOC codes show no skills or require excessive manual review. Symptoms:
  • Manual review queue builds up with many uncertain classifications
  • SOC codes return empty skill lists
  • Processing jobs fail or time out
Solutions:
  1. Configuration Adjustments
    • Lower confidence thresholds for initial skill extraction
    • Review and customize prompt templates for your domain
    • Enable batch processing for large SOC datasets
  2. Data Quality Improvements
    • Ensure SOC codes are current (use 2018 or later versions)
    • Verify SOC descriptions are complete and accurate
    • Remove or fix truncated SOC descriptions
  3. Manual Review Workflow
    • Process high-priority SOCs first (common job codes)
    • Use bulk approval for similar skill patterns
    • Train your team on domain-specific skill recognition

​
Authentication & Access Issues

​
Login Problems

Problem: Cannot log in despite correct credentials. Symptoms:
  • “Invalid credentials” error with known good password
  • Login page redirects back to login after submission
  • Account appears locked or suspended
Solutions:
  1. Password Issues
    • Ensure caps lock is off and correct capitalization
    • Check for extra spaces before or after email/password
    • Try copying and pasting credentials to avoid typos
  2. Account Status Problems
    • Contact your organization administrator to verify account status
    • Check if your invitation link has expired
    • Confirm you’re using the email address from the invitation
  3. Browser Issues
    • Clear browser cache and cookies for Mapademics
    • Disable browser extensions that might interfere
    • Try logging in using an incognito/private browsing window

​
Organization Access Problems

Problem: Cannot see expected data or features after login. Symptoms:
  • Empty program or course lists when data should exist
  • Missing menu items or features
  • “Insufficient permissions” errors
Solutions:
  1. Role Verification
    • Confirm your user role with your organization administrator
    • Check if you need additional permissions for specific features
    • Ensure you’re in the correct organization if you have multiple accounts
  2. Data Visibility Issues
    • Verify data wasn’t accidentally archived or deleted
    • Check filter settings that might hide relevant content
    • Confirm organization setup is complete

​
Performance & Browser Issues

​
Slow Loading or Timeouts

Problem: Pages load slowly or show timeout errors. Symptoms:
  • Long loading times for reports or data tables
  • Timeout errors during bulk operations
  • Unresponsive interface during background jobs
Solutions:
  1. Browser Optimization
    • Recommended Browsers: Chrome 100+, Firefox 100+, Safari 15+, Edge 100+
    • Close unnecessary browser tabs to free up memory
    • Update your browser to the latest version
    • Enable JavaScript if disabled
  2. Network Issues
    • Check your internet connection speed
    • Try refreshing the page if it appears to hang
    • Avoid large operations during peak network usage times
  3. Large Dataset Handling
    • Use filters to limit data displayed in large tables
    • Process data in smaller batches when possible
    • Allow background jobs to complete before starting new ones

​
Widget Display Issues

Problem: Embedded widgets don’t display correctly or show errors. Symptoms:
  • Widget shows blank or error message
  • Styling conflicts with host website
  • Widget doesn’t resize properly on mobile devices
Solutions:
  1. Embedding Code Issues
    • Verify the iframe embed code is complete and unmodified
    • Check that the organization ID in the URL is correct
    • Ensure no special characters were corrupted during copy/paste
  2. Website Compatibility
    • Confirm your website allows iframe embedding
    • Check Content Security Policy (CSP) settings
    • Test widget on a simple HTML page to isolate issues
  3. Styling Problems
    • Use the widget customization options to match your site’s theme
    • Test widget appearance on different screen sizes
    • Contact support if advanced styling customization is needed

​
Background Jobs & Processing

​
Job Status Monitoring

Problem: Background jobs appear stuck or show unclear status. Symptoms:
  • Jobs show “PROCESSING” status for extended periods
  • No progress updates during long-running operations
  • Jobs fail without clear error messages
Solutions:
  1. Normal Processing Times
    • Syllabus Processing: 5-15 minutes per course section
    • Bulk Import: 10-30 minutes depending on data size
    • SOC Mapping: 15-45 minutes for large batches
  2. Monitoring Tools
    • Check the Background Jobs page in Administration for detailed status
    • Look for real-time progress indicators (green connection status)
    • Review job logs for specific error details
  3. When Jobs Fail
    • Wait 5 minutes and refresh before assuming failure
    • Check if you can restart failed jobs from the administration panel
    • Contact support with the specific job ID if issues persist

​
WebSocket Connection Issues

Problem: Real-time updates don’t work, requiring page refreshes to see progress. Symptoms:
  • Red “Disconnected” status indicator
  • No live updates during background processing
  • Must manually refresh to see job completion
Solutions:
  1. Browser Settings
    • Ensure WebSockets are enabled in your browser
    • Disable browser extensions that might block WebSocket connections
    • Check if your organization’s firewall allows WebSocket connections
  2. Network Configuration
    • Contact your IT team if using corporate networks with restrictions
    • Try from a different network (mobile hotspot) to test connectivity
    • Verify Ably WebSocket service isn’t blocked

​
Data Quality & Validation

​
Missing or Incomplete Skills Data

Problem: Courses or jobs show no skills or incomplete skill information. Symptoms:
  • Course sections display empty skill lists
  • Reports show gaps in skills coverage
  • Skills mapping appears incomplete
Solutions:
  1. Processing Status Check
    • Verify syllabus processing jobs completed successfully
    • Check if content was uploaded for all course sections
    • Review processing logs for any errors
  2. Content Quality Issues
    • Ensure uploaded content contains skill-related information
    • Add more detailed course descriptions or learning outcomes
    • Reprocess with adjusted AI confidence settings
  3. Manual Data Entry
    • Add skills manually if automated extraction fails
    • Use the skills library to maintain consistency
    • Review and approve uncertain AI classifications

​
Getting Additional Help

If you continue experiencing issues after trying these solutions:
  1. Contact Information
    • Email: support@mapademics.com
    • Include specific error messages, job IDs, or screenshots when reporting issues
  2. Information to Provide
    • Your organization name
    • Browser type and version
    • Steps to reproduce the problem
    • Any error messages you received
  3. Escalation Process
    • Critical issues: Contact support immediately
    • Feature requests: Submit through your organization administrator
    • Training needs: Ask about available training resources