Define the migration scope
Write down what is moving, where it is going, and which behavior must survive. “Move the question bank” is too vague for acceptance.
Record the following details:
- Source platform and export mechanism
- QTI version or proprietary format
- Number of banks, items, tests, pools, and shared stimuli
- Interaction and question types
- Scoring patterns and partial-credit rules
- Assets, stylesheets, math, media, and external links
- Accessibility metadata and support materials
- Local taxonomies, ownership, lifecycle, and analytics identifiers
- Destination authoring and delivery systems
Keep the original packages unchanged. Migration output should be reproducible from a named source artifact and converter version.
Reasons to migrate
Migrate when a required destination cannot use the source format reliably, your institution needs an exit archive, an authoring workflow changes, or legacy content blocks accessibility and maintenance work.
Do not convert content solely to claim a newer version. If your current authoring and delivery systems exchange the required QTI 2.x profile without loss, you may keep that path while you pilot QTI 3. The QTI 2 versus QTI 3 comparison provides the decision criteria.
Set a measurable result. For example, require a QTI 3 archive that imports into two named systems, preserves required metadata and scoring, and passes your institution’s accessibility review.
Account for version differences
QTI 1.2, QTI 2.x, the Accessible Portable Item Protocol (APIP), and QTI 3 do not share a single element-for-element model. QTI 3 consolidates QTI and APIP work, uses current web-oriented element naming, and expands shared presentation vocabulary and accessibility-related structures.
Profile differences matter as much as version differences. A source may use only a basic subset, or it may depend on custom processing, local metadata, proprietary classes, and extensions. Inventory the corpus before choosing a mapping strategy.
Define acceptable changes
Some source content does not map cleanly to QTI 3. Your institution must decide which changes are acceptable and which require repair or rejection.
Record those decisions before bulk conversion. For example, you might allow a local display label to move into a documented extension while rejecting any change to correct responses, scoring, reading order, accessible names, or media alternatives.
Classify each field or behavior by using one of the following actions:
- Preserve exactly
- Map to a QTI 3 equivalent
- Preserve as a documented extension
- Transform with review
- Omit with an explicit warning
- Block migration
Do not let the converter make policy silently.
Profile the source content
Sample files often contain only the easiest items. Analyze the full corpus before estimating effort.
Group content by structural signature: interaction type, response declaration, processing rule, asset pattern, namespace, extension, and source version. Count each group. Pull representative items from common groups and every rare or high-risk group.
Inspect malformed content separately. Old systems may import files they would never export cleanly. Decide whether the migration tool repairs known source defects, preserves them for another step, or stops.
Build an explicit mapping
Map source constructs to QTI 3 semantics before mapping element names. QTI 1.2, QTI 2.x, APIP, and vendor formats can express similar ideas through different structures.
For every mapping, document the following details:
- Source signature
- QTI 3 target
- Identifier policy
- Response and outcome types
- Scoring transformation
- Content and asset handling
- Accessibility handling
- Diagnostics
- Automated fixtures
- Review requirement
Version the mapping rules. A migration completed with rule set 1.4 should remain explainable after rule set 1.5 ships.
Preserve identity and provenance
When source item identifiers are valid and unique, preserve them. If an identifier must change, generate a new one and record the relationship in a crosswalk.
The crosswalk should include source system, source bank, source identifier, destination identifier, source checksum, converter version, migration date, and disposition. Keep it outside candidate-facing content.
Do not put personal data into generated identifiers or diagnostic messages.
Move assets as package content
Download source-managed assets while access still exists. Normalize unsafe or ambiguous paths, but keep a record of each rewrite. Package-relative references are easier to transfer than authenticated source URLs.
Check the following asset properties:
- Missing files and broken references
- Duplicate names with different content
- Filename case differences
- Path traversal
- Unsupported or mislabeled media types
- Images that contain essential text
- Caption and transcript relationships
- Cascading Style Sheets (CSS) that assume a source application shell
Generate a manifest of original and migrated asset checksums. This catches silent corruption and supports later audits.
Conversion can preserve known alternatives and support materials, but it cannot invent the author’s intent. Flag images without useful alternatives, sensory-only instructions, uncaptioned media, unclear link text, visual reading order, inaccessible tables, and interactions without a keyboard path.
Route those items to an accessibility and content review. Record whether the reviewer preserved, repaired, replaced, or retired the item. Then test the repaired item in the destination player with the assistive-technology combinations in your institutional support policy.
If candidates lose an accessible way to answer an item, do not label its migration successful.
Convert response processing carefully
Visual similarity can hide scoring changes. Compare declarations, correct responses, mapping tables, thresholds, template references, outcome values, and custom conditions.
Create test vectors for each of the following response states:
- Unanswered
- Correct
- Incorrect
- Partially correct
- Extra choices
- Minimum and maximum responses
- Invalid input
- Restored attempt state where relevant
When possible, run the source system and record expected outcomes. Then run the migrated item through the target processor. Differences belong in the exception register.
Record unsupported content
Custom interactions, scripts, vendor extensions, complex adaptive behavior, and test-level navigation may not have a safe automatic mapping.
Use one of the following dispositions:
- Converted automatically
- Converted with warning
- Converted for author review
- Retained in source form
- Not converted
If the converter replaces an unsupported interaction with a screenshot or unscored text, do not label the item successful without an explicit institutional decision.
Validate in stages
Use gates so failures remain diagnosable:
- Parse and inventory the source.
- Convert one item to QTI 3.
- Check XML and schema validity.
- Run semantic and supported-profile checks.
- Compare declarations and scoring fixtures.
- Render and operate the item with keyboard and assistive technology.
- Package the item and its assets.
- Import the package into the destination.
- Deliver and score it in the destination workflow.
- Reconcile counts, identifiers, assets, outcomes, and exceptions.
Schema validation belongs near the start. Destination testing belongs near the end. Neither replaces the other.
Run a representative pilot
Choose a pilot by risk and frequency, not convenience. It should include common items, rare interactions, partial credit, math, media, accessibility support, large packages, and known source defects.
Have content owners review meaning and scoring. Have accessibility specialists review candidate operation. Have platform teams test import, editing, delivery, export, and restoration. Record the destination build and configuration.
Begin bulk conversion after the team approves the mapping rules and the process for handling exceptions.
Reconcile the bulk run
Reconcile the following counts at each step:
- Packages read
- Items discovered
- Items converted
- Items blocked
- Assets found and missing
- Warnings by code
- Destination imports
- Destination items
Totals should reconcile with named exceptions. A dashboard that says “99.4% successful” is not enough when the missing 0.6% contains high-stakes exams.
Keep an exception register
Each exception needs the source item, diagnostic code, plain-language explanation, severity, owner, chosen action, and final disposition. Group repeat failures so one mapping fix can be rerun across affected items.
Do not leave warnings only in temporary logs. Export a report that content teams can filter and annotate.
Plan the cutover and exit
Define when the source becomes read-only, who handles last-minute changes, which system owns identifiers after cutover, and how rollback works.
After acceptance, export a clean QTI 3 archive from the destination and validate it independently. Keep that export as part of the migration record and test the exit process before closing the project.
