{"id":18544606,"url":"https://github.com/instructure/qtimigrationtool","last_synced_at":"2025-04-09T19:30:47.571Z","repository":{"id":810271,"uuid":"1352312","full_name":"instructure/QTIMigrationTool","owner":"instructure","description":"Source code and software for converting QTI version 1.x data into QTI 2.0 content packages.","archived":false,"fork":false,"pushed_at":"2022-05-17T12:36:22.000Z","size":282,"stargazers_count":11,"open_issues_count":3,"forks_count":21,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-04-14T20:26:02.484Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/instructure.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-02-10T20:58:15.000Z","updated_at":"2023-07-07T20:10:33.000Z","dependencies_parsed_at":"2022-08-16T11:00:16.827Z","dependency_job_id":null,"html_url":"https://github.com/instructure/QTIMigrationTool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2FQTIMigrationTool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2FQTIMigrationTool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2FQTIMigrationTool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instructure%2FQTIMigrationTool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instructure","download_url":"https://codeload.github.com/instructure/QTIMigrationTool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223407794,"owners_count":17140563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T20:17:04.526Z","updated_at":"2024-11-06T20:17:05.124Z","avatar_url":"https://github.com/instructure.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"QTI Migration Tool\n------------------\n\nThis is the QTI migration tool, use is governed by the license at the bottom of\nthis file.\n\nFor up to date information about the migration tool and related initiatives go\nto http://qtitools.caret.cam.ac.uk/ - Please direct any comments to\nswl10@cam.ac.uk\n\nInstructure Modifications\n------------\n\nThis tool has been modified by Instructure. Many of the modifications conform to\nthe QTI 2.0 specifications, but some don't. So buyers beware!\n\nFor instructions on using this tool with Canvas see this project's wiki page:\nhttps://github.com/instructure/QTIMigrationTool/wiki\n\n\nInstallation\n------------\n\nThe migration tool can work either in batch mode activated from the command line\nor using a graphical user interface (GUI).\n\n* Windows\n\nSimply download the installer program and run it.\n\n* Mac OS X\n\nSimply download the application disk image.  To install the application just\ndrag it from the mounted disk image to the Applications folder.\n\n* Unix/Linux\n\nFollow the source release installation instructions below.\n\n* Installing the Source\n\nTo install the source distribution you will need a version 3 python interpreter\nto be installed on your system.  Python is available as a simple installer for\nmost popular platforms, for more details see:\n\nhttp://www.python.org/\n\nYou will also need the LXML package installed. You can get it with \n`pip3 install lxml` or with your system's package manager, e.g.\n`apt-get install python3-lxml`.\n\nThe GUI mode requires wxPython to be installed.  wxPython is available for\nWindows, Mac and Unix/Linux based systems.  The installation is straightforward\non most modern versions of these operating systems.  For details of how to\ndownload and install it for your system see:\n\nhttp://www.wxpython.org/\n\nFinally, if you install the vobject package into your Python interpreter the\nmigration tool can use it to enhance the --qmdextensions option.  This tool\nhas been tested against version 0.6.0 of vobject, for more details, see:\n\nhttp://vobject.skyhouseconsulting.com/\n\nOnce you have installed Python (and optionally, wxPython and vobject) you should\nsimply unpack the source distribution into the desired location in the file\nsystem.\n\n\nRunning\n-------\n\nOn some systems you may be able to open the migration tool directly from your\nGUI just by double-clicking the \"migrate.py\" file.  However, the migration tool\ncan always be run from the command line.  On Windows machines you must use the\n*DOS* command line, on MacOS X you should use the terminal.  Windows users are\nadvised to familiarize themselves with the instructions for running python\nscripts from the DOS command line:\n\nhttp://www.python.org/doc/faq/windows/#how-do-i-run-a-python-program-under-windows\n\nTo run the tool you must change to the directory in which the tool resides and\nthen run the migrate.py script.\n\nBy default, the tool launches in GUI mode if it can.  If you don't have wxPython\ninstalled, or you use the --nogui option, the tool uses batch mode instead. When\nrunning in GUI mode command line options can be used to set the initial states\nof the corresponding controls.\n\n* Batch mode\n\nTo force batch mode, pass --nogui an argument to the migrate.py command.\n\nYou pass the paths of the QTI version 1 files to process as arguments.  If you\npass the name of a directory then it is scanned recursively for QTI xml files\n(which are assumed to be all files with the extension \".xml\").\n\nThe tool writes some messages to the standard output, mainly to report on\nprogress and to flag unsupported conversion features.\n\nBy default, the migration tool just examines the version 1 items for problems\nwithout generating an output content package.  To actually convert the items you\nwill need to pass it the path of a directory in which to write its output files,\nthis is passed as a special path prefixed with the string --cpout= (see example\nbelow).\n\nmigrate.py --nogui MyQTIv1Items.xml --cpout=Package\n\nThis example uses batch mode to convert all the items in the XML file\nMyQTIv1Items.xml and places them in a directory called Package.  In QTI version\n1, a single XML document could contain many items.  In version 2.0 multiple\nitems are grouped together using an IMS Content Package instead.  The migration\ntool generates an appropriate manifest file automatically and places it in the\noutput directory.\n\n* GUI Mode\n\nThe GUI allows you to select a \"Single QTIv1.2 File\" or a \"Full Directory\" to\nprocess.  To generate a content package you must select a directory using the\ncontrol in the \"Save files to...\" box.\n\nTo convert the files use the \"Convert...\" button.\n\nYou can control the destination of the status messages and error reports by\ntoggling the \"Show Output Log\" menu item in the \"File\" menu.\n\n* Options\n\nYou can use options to tweak the behaviour of the migration tool.  Options can\nbe specified on the command line.  In GUI mode they are available from the\nOptions menu.  A full list is given below.\n\nOnce you have got a basic migration of your content, you might like to use the\n--qmdextensions and --ucvars options as these usually improve the resulting\noutput at the risk of deviating slightly from the proper interpretatin of the\noriginal (version 1.x) QTI specification.  Similarly, use of --lang is highly\nrecommended for improving the quality of the resulting metadata.\n\n\nTroubleshooting\n---------------\n\nI've tried to make the migration tool as tolerant as possible so that it\nproduces some output for all items, even if the migration is incomplete.\nHowever, sometimes the tool refuses to parse the input files completely and\njust stops.  Have a look at the section on problems with graphical characters\n(below) and do check that your input files are at least well formed XML files.\n\nCheck the comments that the tool writes at the top of each version 2 file it\ngenerates, they sometimes contain important information about decisions made\nduring the migration.\n\nIf you are dissatisfied with the result of migrating your QTI data or the tool\nexits with an error without generating any output *please* do send me a sample\nQTI (version 1.x) file demonstrating the problem so that I can use it to improve\nfuture versions.  It is often possible to fix migration problems quickly and to\nincorporate changes for the next release so that everyone benefits.\n\n\nMigration Tool Options\n----------------------\n\n--cpout=\u003cpath to package directory\u003e\n\"Save files to... Select Directory\" in the GUI\n\nUsed to specify an output directory for the content package to be written to.\nWithout this option the migration tool will only examine the version 1 files and\nreport problems without generating a content package.\n\n--ucvars\n\"Options: Force Uppercase\" in the GUI\n\nVersion 1 of the QTI specification was unclear on whether or not variable names\nwould be treated case sensitively or not.  From version 2.0 onwards all variable\nnames are treated case sensitively.  Some old content may assume that\ncomparisons are case-insensitive.  Watch out for errors reported in the output\nlike \"reference to undeclared outcome\" - this may indicate a case-mismatch\nbetween references and declared variables.  The tool auto-declares missing\noutcomes so these errors are not fatal but the resulting output won't work as\nexpected!  If you specify this option, the migration tool will force all\nidentifiers to upper-case before processing them.\n\n--qmdextensions\n\"Options: Allow Metadata Extensions\" in the GUI\n\nSome metadata tags are in use that were not part of QTI version 1 itself.  You\ncan turn on support for these metadata extensions with this flag.  Specifically,\nthe following tags are then recognized:\n\n\t\u003cqmd_keywords\u003e\n\t\u003cqmd_domain\u003e        (treated as a keyword)\n\t\u003cqmd_description\u003e\n\t\u003cqmd_title\u003e\n\t\u003cqmd_author\u003e        (requires vobject support, see above)\n\t\u003cqmd_organisation\u003e  (requires vobject support, see above)\n\n--lang=\u003clanguage\u003e\n\"Options: Default Language\" in the GUI\n\nThis option allows you to provide a default language for items migrated by the\ntool. If there is no language specified for an item then it is treated as if\n\u003clanguage\u003e was specified instead.  Note that this option also affects metadata\nwhich is read from the item tag itself in version 1 of QTI.  In fact, one of its\nmain purposes is to ensure that the metadata values are appropriately language\ntagged when migrating them into the manifest of the content package.\n\n--nocomment\n\"Options: Suppress Comment\" in the GUI\n\nThe migration tool generates warning messages during conversion which it adds\nto the top of each output files in the form of an XML comment immediately\nfollowing the XML declaration.  This option suppresses the generation of these\ncomments.\n\n--dtdloc=\u003cpath\u003e\n\"Options: Force DTD Location\" in the GUI\n\nFiles that contain a SYSTEM idenifier pointing at a non-existent file will cause\nthe migration tool to fail.  The only ways to overcome this are (a) to put a\ncopy of the required DTD in the specified location, (b) remove the SYSTEM\nidentifier from the DOCTYPE declaration at the top of the file or (c) use the\n--dtdloc option to tell the migration tool the *directory* where it can find\nthe DTD.\n\n--forcefibfloat\n\"Options: Force Float\" in the GUI\n\nSome implementations blurred the distinction between string and numeric\nvariables.  As a result, some content creates fill-in-the-blank or 'fib'\nquestions that obtain string type values from the user that are then treated as\nnumbers during response processing.  There is no general fix for this in the\nmigration tool but the --forcefibfloat option forces all fibs to be treated as\nif they had been declared as floats instead.  Only use this option if you know\nthat your content suffers from this problem.\n\n--nogui\n\nAs of version 20080610 the migration tool will launch in GUI mode if wxPython is\ninstalled.  You can force the tool to run in batch mode with this option.\n\n--help\n\nPrint a help message (implies --nogui)\n\n--version\n\nPrint version information (implies --nogui)\n\n\nGraphic Character Problems: fixwinchars.py\n------------------------------------------\n\nSometimes, the migration tool fails with an \"Invalid Token\" message, generated\nby the XML parser.  These messages might be caused by the additional graphic\ncharacters often used by Windows.  These characters, including 'smart' quotes,\nare not portable between systems and cannot be included in XML files without an\nappropriate XML declaration.  The source release contains a simple script to\nhelp solve this problem. You pass it the name of a file (or files) and it will\nexamine them for special graphical characters.  If it finds some, it will\nreplace them with XML character entity references to the appropriate Unicode\ncharacters.\n\nBE CAREFUL: files are changed in place so only ever run this script on a copy of\nyour files!  For safety, fixwinchars will only process files that start with a\n'\u003c' character.\n\nfixwinchars.py MyWindowsFile.xml\n\nThe output of the script might look like something this:\n\nFixing 2 chars in file: MyWindowsFile.xml\nchr(0x96) -\u003e \u0026#x2013;\nchr(0x96) -\u003e \u0026#x2013;\n\nIf there is nothing to be done, no output is generated.\n\nYou can force all non-ascii characters to be encoded by passing the --ascii\noption, you should use this option if your file is missing the XML declaration\nall together (or has been incorrectly labelled as being UTF-8):\n\nfixwinchars.py --ascii MyWindowsFile.xml\n\n\nBuilding the Binary Executables\n-------------------------------\n\nThe source release contains all the files necessary to build the binary\nexecutable files.\n\nFor Windows, you will need py2exe. The compile.bat file contains the command\nrequired to trigger the build given a typical Python 2.5 installation:\n\npython setup_migrate.py py2exe --packages encodings\n\nThe executable files are created in the dist directory. These can be packaged into\nan installer using the Inno Setup tool, a suitable installation script is provided in\nmigrate_w32.iss.\n\nFor Mac OS, you will need to install py2app and setuptools.  You can then build\nthe binary application using the command:\n\npython build.py py2app\n\nTo build the binary releases you *must* have VObject installed.\n\npython: http://www.python.org/download/\npy2exe: http://www.py2exe.org/\nInno Setup: http://www.jrsoftware.org/isinfo.php\nVObject: http://vobject.skyhouseconsulting.com/\n\nAll needed tools are available for free download.\n\nChange Log\n----------\n\n\nVersion: 20080612\n\nNew features:\n\n* Integrated Pierre Gorissen's GUI interface code into the source release to\nspeed up production of Windows (and now Mac) binary distributions.\n\n* Added --nocomment option\n\n\nVersion: 20080604\n\nBug fix release to correct \"Non-ASCII character\" problem.\n\n\nVersion: 20080602\n\nNew features:\n\n* Added rudimentary (but effective) support for the parsing of embedded RTF\n  code in mattext\n\n* Significantly improved parsing of embedded HTML code in mattext, including\nsupport for HTML code with missing CDATA sections delimitters, better code to\nhandle omitted tags and a wider range of supported tags (including basic\ntables and img elements in mattext).\n\n* Added support for copying media files into the content package, previously\n  this had to be done by hand after the migration.\n\n* Added automated generation of QTI specific metadata in the manifest and added\nsupport for \u003cqtimetadata\u003e and the following legacy tags:\n\t\u003cqmd_itemtype\u003e\n\t\u003cqmd_levelofdifficulty\u003e\n\t\u003cqmd_maximumscore\u003e\n\t\u003cqmd_status\u003e\n\t\u003cqmd_toolvendor\u003e\n\t\u003cqmd_topic\u003e\n\n* Improved generated XML to ensure validation against latest IMS schemas.\n\n* Relaxed various validation issues to generate warnings instead of terminating\nthe migration process.\n\n* Reduced verbosity when skipping unsupported tags\n\n* Added --ucvars option\n\n* Added --qmdextensions option\n\n* Added --forcefibfloag option\n\n* Added --lang option\n\n* Added --dtdloc option\n\n* Bundled the related fixwinchars script with this release\n\nBugs fixed:\n\n* Fixed a bug that allowed invalid identifiers to be migrated unchanged.\n\n* Fixed a bug which occasionally caused truncation of content when processing\nembedded formatting tags.\n\n* Fixed a bug caused by the use of language tags on the top level questestinterp.\n\n* Fixed a bug caused by the use of multiple response processing sections in a\nsingle item\n\n\nVersion: 20070424\n\nChanged the errors trapped by the XML parser to prevent the tool exiting out\nwhen faced with badly formed input files during a batch run.\n\n\nVersion: 20060915\n\nAdded support for the unanswered tag to accompany my XSLT pre-processor for\nconverting content from the QAed authoring tool.\n\nChanged the QTI schema location hint in the output to point to the version of\nthe schema published on the IMS website.\n\n\nVersion: 20050610\n\nThis version of the tool represents an improvement on the earlier version\ndistributed as a Windows executable through SURF SiX.  Though the modifications\nare fairly minor.\n\nThis version is functionally identical to the one that was used at the\nCETIS/LIFE project CodeBash event in Bolton, April 2005.\n\n\nAcknowledgements\n----------------\n\nThanks to Pierre Gorissen for providing the GUI code and the Windows binary\nexecutable and installer.\n\nThanks to all those people who have offered me content to test the migration\nprocess on.  In particular, thanks to all the attendees at the CETIS Code Bashes\nwith a special thank you to Dick Bacon for loaning me the Physical Sciences item\nbank.\n\n\nLicense\n-------\n\nCopyright (c) 2004-2008, University of Cambridge.\nGUI Code Copyright (c) 2004-2008, Pierre Gorissen\n\nAll rights reserved.\n\nRedistribution and use of this software in source and binary forms\n(where applicable), with or without modification, are permitted\nprovided that the following conditions are met:\n\n *  Redistributions of source code must retain the above copyright\n    notice, this list of conditions, and the following disclaimer.\n\n *  Redistributions in binary form must reproduce the above\n    copyright notice, this list of conditions, and the following\n    disclaimer in the documentation and/or other materials provided with\n    the distribution.\n\n *  Neither the name of the University of Cambridge, nor the names of\n    any other contributors to the software, may be used to endorse or\n    promote products derived from this software without specific prior\n    written permission.\n\nTHIS SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\nOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructure%2Fqtimigrationtool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstructure%2Fqtimigrationtool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstructure%2Fqtimigrationtool/lists"}