Overview
Mapademics supports various data formats for importing academic information. Understanding these formats ensures successful data migration and ongoing system integration.Bulk Import Formats
Excel Files (.xlsx)
Recommended format for bulk data imports.- File size limit: 10 MB maximum
- Sheet structure: Must use the official Mapademics template
- Character encoding: UTF-8 supported
- Special characters: Automatically sanitized during import
CSV Files (.csv)
Alternative format for bulk imports when Excel is not available.- Delimiter: Comma-separated values
- Text qualifier: Double quotes for fields containing commas
- Character encoding: UTF-8 required
- Header row: Must match template column names exactly
Syllabus Document Formats
PDF Files
Primary format for syllabus processing and skills extraction.- File size: Up to 25 MB per document
- Text extraction: OCR applied to scanned documents
- Language support: English language content optimized
- URL accessibility: Must be publicly accessible via HTTPS
Supported URL Formats
- Direct PDF links (https://example.com/syllabus.pdf)
- Cloud storage links (Google Drive, Dropbox, OneDrive)
- Learning Management System links
- University portal document links
Password-protected or authentication-required URLs cannot be processed. Ensure syllabus URLs are publicly accessible.
Data Structure Requirements
Field Types and Validation
Text Fields
Text Fields
Standard text fields (names, descriptions, codes):
- Names: 255 characters maximum (programs, courses, instructors, credentials)
- Descriptions: No length limit in database, but recommended under 2000 characters
- Course/Program codes: 50 characters maximum, alphanumeric characters recommended
- CIP codes: 6-digit format (XX.XXXX) for program classification
- Special characters: Automatically escaped
- HTML: Stripped during processing
- Leading/trailing spaces: Automatically trimmed
- Instructor details: No database limit, stored as TEXT
- Section descriptions: No database limit, stored as TEXT
- Markdown: Basic formatting preserved
- Line breaks: Maintained in display
Email Addresses
Email Addresses
Format validation:
- Must follow standard email format (user@domain.com)
- Case insensitive matching
- International domains supported
- Validation occurs during import
- Optional field - instructors can be imported without email addresses
- Email addresses can be shared across different instructor records
- Duplicate emails within same record are not allowed
- Stored as VARCHAR(255) in database
URLs
URLs
Syllabus URLs:
- Must begin with https:// or http://
- Must point to accessible PDF documents
- Shortened URLs (bit.ly, tinyurl) are resolved automatically
- Invalid URLs are flagged during validation
- HTTP 200 status code required
- Content-Type must be application/pdf
- File size under 25 MB
Reference Fields
Reference Fields
Cross-sheet references:
- Case-sensitive exact matching
- Leading/trailing spaces ignored
- Must exist in referenced sheet
- Validated during import process
- Course sections reference course codes from Courses sheet
- Course sections reference instructor names from Instructors sheet
- Credential relationships reference both credentials and sections
Template Structure
Required Sheets
The bulk import template includes six specific sheets with exact naming requirements:- “Programs” - Academic programs and degree offerings
- “Courses” - Individual courses within programs
- “Instructors” - Faculty and teaching staff (optional)
- “Course Sections” - Specific sections of courses (optional)
- “Credentials Definitions” - Stackable credentials and certificates (optional)
- “Credentials and Course Sections” - Relationships between credentials and sections (optional)
Sheet names are case-sensitive and must match exactly. Programs and Courses sheets are required; others are optional but recommended.
Field Specifications Reference
The following table provides a complete reference of all supported fields across all import sheets:| Sheet | Field Name | Type | Required | Max Length | Validation Rules |
|---|---|---|---|---|---|
| Programs | Name* | Text | ✓ | 255 chars | Must be unique within organization |
| Programs | Code | Text | ✗ | 50 chars | Alphanumeric recommended |
| Programs | CIP Code | Text | ✗ | 10 chars | Format: XX.XXXX (6-digit standard) |
| Programs | Description | Text | ✗ | Unlimited | Plain text, HTML stripped |
| Courses | Name* | Text | ✓ | 255 chars | No uniqueness requirement |
| Courses | Course Code* | Text | ✓ | 50 chars | Must be unique within organization |
| Courses | Description | Text | ✗ | Unlimited | Plain text, HTML stripped |
| Courses | Program Names | Text | ✗ | Unlimited | Comma-separated, must exist in Programs |
| Instructors | Name* | Text | ✓ | 255 chars | Duplicates allowed |
| Instructors | ✗ | 255 chars | Valid email format | ||
| Instructors | Details | Text | ✗ | Unlimited | Supports long descriptions |
| Course Sections | Section Name* | Text | ✓ | 255 chars | Must be unique within each course |
| Course Sections | Course Code* | Text | ✓ | 50 chars | Must exist in Courses sheet |
| Course Sections | Instructor Name | Text | ✗ | 255 chars | Must exist in Instructors sheet |
| Course Sections | Description | Text | ✗ | Unlimited | Section-specific information |
| Course Sections | Syllabus URL | URL | ✗ | Unlimited | Must be accessible HTTPS PDF link |
| Credentials Definitions | Name* | Text | ✓ | 255 chars | Must be unique within organization |
| Credentials Definitions | Code | Text | ✗ | 50 chars | Optional identifier |
| Credentials Definitions | Description | Text | ✗ | Unlimited | Credential details |
| Credentials and Course Sections | Credential Name* | Text | ✓ | 255 chars | Must exist in Credentials Definitions |
| Credentials and Course Sections | Course Code* | Text | ✓ | 50 chars | Must exist in Courses sheet |
| Credentials and Course Sections | Section Name* | Text | ✓ | 255 chars | Must exist in Course Sections sheet |
Column Headers and Field Requirements
Programs Sheet
Programs Sheet
Required columns:
Name*- Program name (required, unique within organization)
Code- Program identifier/abbreviationCIP Code- 6-digit Classification of Instructional Programs codeDescription- Program description
- Program names must be unique within your organization
- CIP codes should follow standard format (XX.XXXX)
- Blank rows are automatically skipped
Courses Sheet
Courses Sheet
Required columns:
Name*- Course name (required)Course Code*- Unique course identifier (required)
Description- Course descriptionProgram Names- Comma-separated list of program names this course belongs to
- Course codes must be unique within your organization
- Referenced program names must exist in Programs sheet
- Multiple programs can be referenced using comma separation
Instructors Sheet
Instructors Sheet
Required columns:
Name*- Instructor full name (required, allows duplicates)
Email- Instructor email address (standard format)Details- Additional instructor information
- Instructor names can be duplicated (multiple instructors with same name allowed)
- Email format validation applied if provided
- Details field supports unlimited text length
Course Sections Sheet
Course Sections Sheet
Required columns:
Section Name*- Section identifier (required)Course Code*- Must match a course code from Courses sheet (required)
Instructor Name- Must match an instructor name from Instructors sheetDescription- Section-specific descriptionSyllabus URL- Direct link to PDF syllabus document
- Section names must be unique within each course
- Course codes must exist in Courses sheet
- Instructor names must exist in Instructors sheet (if provided)
- Syllabus URLs must be accessible HTTPS links to PDF files
Credentials Definitions Sheet
Credentials Definitions Sheet
Required columns:
Name*- Credential name (required, unique)
Code- Credential code/abbreviationDescription- Credential description
- Credential names must be unique within organization
- Codes are optional but recommended for tracking
Credentials and Course Sections Sheet
Credentials and Course Sections Sheet
Required columns:
Credential Name*- Must match a credential from Credentials Definitions sheetCourse Code*- Must match a course code from Courses sheetSection Name*- Must match a section name within the specified course
- All three fields are required for valid relationships
- References must exist in their respective sheets
- Creates many-to-many relationships between credentials and course sections
- Required fields marked with asterisk (*) cannot be empty
- Optional fields can be left blank
- Custom columns are ignored during import
- Column order can be rearranged without issues
- Column headers support both “Name*” and “Name” formats
Import Processing Order
Data is imported in the following sequence to maintain referential integrity:1
Programs Creation
Programs are created first since they’re referenced by courses.
All program names become available for course references.
2
Courses Creation
Courses are created with references to existing programs.
Course codes become available for section references.
3
Instructors Creation
Instructors are created independently (no dependencies).
Instructor names become available for section references.
4
Course Sections Creation
Course sections are created with references to courses and instructors.
Section names become available for credential relationships.
5
Credentials Creation
Stackable credentials are created independently.
Credential names become available for section relationships.
6
Credential-Section Relationships
Many-to-many relationships are established between credentials and course sections.
All relationships are validated and created successfully.
Data Quality Guidelines
Consistency Requirements
- Naming conventions: Use consistent capitalization and spacing
- Code formats: Maintain consistent patterns for course codes and program codes
- Case sensitivity: All reference matching is case-sensitive
- Whitespace handling: Leading and trailing spaces are automatically trimmed
- Date formats: Use ISO 8601 format (YYYY-MM-DD) when applicable
Validation Best Practices
- Unique identifiers:
- Program names must be unique within organization
- Course codes must be unique within organization
- Credential names must be unique within organization
- Section names must be unique within each course
- Instructor names can be duplicated (same person, multiple records allowed)
- Complete relationships: Verify all referenced items exist in their respective sheets
- Cross-sheet references:
- Courses → Programs: Program names in “Program Names” column
- Course Sections → Courses: Course codes must match exactly
- Course Sections → Instructors: Instructor names must match exactly
- Credentials and Course Sections → All: Must reference existing credentials, courses, and sections
- Data integrity: Cross-check information across multiple sheets for accuracy
Common Data Issues
Run the import validation before executing to catch these issues early. The system will show you exactly which references are missing or invalid.
Encoding Problems
Encoding Problems
Symptoms: Special characters appear as � or are missing
Solution: Save files with UTF-8 encoding, avoid copy-pasting from PDFs
Reference Mismatches
Reference Mismatches
Symptoms: “Item not found” errors during import
Solution:
- Verify exact spelling and capitalization of referenced names/codes
- Check that referenced items exist in their respective sheets
- Ensure course codes in “Course Sections” sheet match those in “Courses” sheet
- Verify instructor names in “Course Sections” sheet match those in “Instructors” sheet
Format Inconsistencies
Format Inconsistencies
Symptoms: Some items import while similar ones fail
Solution: Standardize data formats within each column
Solution: Standardize data formats within each column
Empty Required Fields
Empty Required Fields
Symptoms: Rows are skipped during import
Solution:
- Ensure all required fields (marked with *) contain values
- Check for blank cells in Name and Course Code columns
- Remove completely empty rows from sheets
Duplicate Key Conflicts
Duplicate Key Conflicts
Symptoms: Import shows conflicts that need resolution
Solution:
- Choose resolution strategy: Skip, Replace, or Create New
- Program names: Must be unique, conflicts occur with existing programs
- Course codes: Must be unique, conflicts occur with existing courses
- Instructor names: Duplicates allowed, conflicts are informational only
Conflict Resolution System
When importing data that conflicts with existing records, you’ll be presented with resolution options:Skip Import
Skip the conflicting item
- Leaves existing data unchanged
- Recommended for testing imports
- Conflicting item is not imported
Replace Existing
Update the existing record
- Overwrites existing data with new values
- Preserves the original database ID
- Use when updating existing records
Create New
Create a duplicate with suffix
- Creates new record with “(2)” suffix
- Preserves both old and new data
- Useful when records are actually different
Conflict resolution is applied per entity type. You can skip programs while replacing courses in the same import.
Conflict Detection Rules
| Entity Type | Conflict Key | Behavior |
|---|---|---|
| Programs | Name | Exact match, case-sensitive |
| Courses | Course Code | Exact match, case-sensitive |
| Instructors | Name | Exact match, case-sensitive (but duplicates allowed) |
| Course Sections | Section Name + Course Code | Combined key match within same course |
| Credentials | Name | Exact match, case-sensitive |
Advanced Import Features
Syllabus Processing Integration
When course sections include syllabus URLs, the system automatically:1
Validate URLs
Checks that syllabus URLs are accessible and point to PDF files.
2
Queue for Processing
Valid syllabi are queued for AI-powered skills extraction.
This happens in the background after the main import completes.
3
Extract Skills
AI processes the syllabus content to identify learning outcomes and skills.
4
Attach to Sections
Extracted skills are automatically attached to the respective course sections.
Bulk Import Audit Trail
Every bulk import operation creates a complete audit record:- Import ID: Unique identifier for tracking
- File Information: Original filename and upload timestamp
- Processing Summary: Total items processed, created, updated, and skipped
- Detailed Results: Per-entity breakdown of all operations
- Error Log: Complete list of failed items with error descriptions
- Conflict Resolutions: Record of all user decisions during import
You can view the complete import history and re-examine results from previous imports in the bulk import history section.
Future Format Support
Planned Integrations
- Student Information Systems (SIS) - Direct API connections
- Learning Management Systems - Canvas, Blackboard, Moodle
- HR Systems - Employee directory integration for instructor data
API Data Formats
When the Mapademics API launches, it will support:- JSON - Primary format for API requests and responses
- XML - Alternative format for legacy system integration
- GraphQL - Flexible querying for complex data relationships
Contact support if you need assistance with data format conversion or have questions about upcoming integration capabilities.
Related Resources
- Bulk Data Import Guide - Complete import process walkthrough
- Data Model Reference - Detailed field specifications
- Troubleshooting Import Errors - Common issues and solutions