This method will create a single test element within a course.  The test is created under a specified parent folder in the course. If parent folder is not specified, then by default it will be placed under the course root folder.

The test is created in two parts; first the test itself and then the questions in the test. It does not create any results for the test.

The test questions are added through the IMS QTI 2.1 standard file.  The file will be ZIP file contains the XML in QTI format.  The QTI ZIP file should be uploaded to itslearning first.



Action

This type of message will create a test in a course.  The test element can be added to the course root folder or another folder within a course.  Each test should have a unique SynchKey associated with it up to the size of 128 characters.

A UserId or UserSyncKey needs to be specified which identifies the user who created the link.  

An Active parameter can be set on the test. This decides whether a test is shown in the course or not.  By default if the active parameter is set to true, so the element will be displayed.

The questions can include the rules for rich text import as you may want to include links to images in the Rich Content Questions.

Images / resources related to the questions, should be contained within the ZIP file as per the QTI format, not uploaded separately. The file / image handling referred to on the Handling rich content and files page does NOT apply to content within QTI packages.

The import system does not support categories


Screenshots

The imported questions from a QTI file.


Editing an imported test.



The test options as specified in the test add message.


Best Practice for 3rd Parties

  • The Migration API does not currently support the upload of learner test submissions, only the tests itself.
  • Optionally a scoring method can be used. By default tests have no penalty or scoring.
    • "With penalty". This gives a penalty for incorrect or incomplete answers - useful in exams and formal tests. The penalty may prevent participants from guessing.
    • "Without penalty". All correct answers are rewarded - useful for training and motivation.
  • Optionally tests can have criteria for completion. If used a percentage (1-100) must be set to show the level required to obtain a 'Completed' in the progress report.
  • Optionally tests can display test presents questions in a random order from participant to participant. This can be used to make tests seem more random.
  • Tests must have a navigation option set. The default is "free navigation" where participants can answer the questions in any order. The full list of options is as follows:
    • Forward only ? here participants must answer a question before they are allowed to proceed to the next.
    • Free navigation ? the default where participants can skip questions and navigate back and forth.
    • Show all questions on one page ? shows the entire test in one, this is not recommended for tests with many questions.
  • Tests can be taken one or more times. The default is once. However, you can select from ?1, 2, 3, 4, 5, 8, 13 or unlimited?.
  • Tests can be "timed". The default time is unlimited. However, you can specify from 1 to 35791394 minutes. We do not recommend you use more the upper limit!
  • Results from the tests be shown at different times. You can select from four options. The default is to show the results after each test attempt. So participants get feedback after each question. The full list of option are:
    • When the teacher decides.
    • Never
    • After each attempt.
    • After all attempts (for tests that can be taken multiple times).
  • Feedback (results of the test) can be given at differnet times. You can use this to allow students to have feedback straight away, or not see feedback at all.
    • On Questions: Shows feedback after every question.
    • On Alternatives: Shows feedback after every alternative.
    • No feedback. 

Scenario

In order to create a test the will:

  1. Create a test in a QTI format based on the IMS QTI 2.1 standard file and create a a ZIP file with all the question XML files and manifest XML file.
  2. Upload the zip file to itslearning. A successful upload will return a GUID e.g. 177e9203-a5c8-4972-ab80-b00c11600b91
  3. Add add a message with the type corresponding to Create.Course.Test and reference the GUID from the above step to in the <file /> section to reference the uploaded QTI file with this test.
The result of that message processing can be acquired using GetMessageResult method with message identifier as an input parameter.

Input

Name
Description
Type
M/O
Message Type
Type of Message.
Text. ?CreateCourseElementTest?
M
SyncKey
External SyncKey for the created content.
Text 
O

SiteId

Site where action will be executed

Integer

O

VendorId

VendorId which will be associated with created content

Text

O

CourseID
ID of the course where the element is to be created.
Integer
O/M
CourseSyncKey
SyncKeyID of the course where the element is to be created.
Text
O/M

ParentID

ID of the (previously created) folder where the element is to be created. If not specified then create in root.

Integer

O

ParentSyncKey
SyncKey of the (previously created) folder where the element is to be created. If not specified then create in root. Must be a SyncKey.
Text

O

Active
Is the element active?
True = "Active".
False = "Not Active".
Default is "Active".
Boolean. True/False.
O
UserID
UserID of the creator.
Integer
O/M
UserSyncKey
User SyncKeyID of the creator.
Text
O/M
Title

Description of the test.
Text
Must not be blank. Must follow same rules as UI.
M

Description
Text (rich content) description of the test.
Text
See user story on importing rich content for description of parsing
O
Deadline
If Deadline is missing blank then set to "no deadline".
If a date is specified then set to the time / date ? even if in the past.
Text.
Valid UTC date. 
O
Assessment
This is the ID of the grade, if grading is used.
Assessment ID: Sets the ?AssessmentID?.
If the value is missing then no assessment grade is used.
If value is not a valid grade ID then assume no grade used and return warning.
NOTE: You are not allowed to enter both Assessment and UseScore.
Integer
O

UseScore

This is flag that the test should use score as assessment type.
If the customer has setting "Use score" is off then assume "Not assessment" used and return warning.

NOTE: You are not allowed to enter both Assessment and UseScore.

Boolean

O

Mandatory
Is the assignment mandatory?
True = "Mandatory".
False = "Not Mandatory".
If not specified then assume mandatory.
Boolean.

O
Active
Is the element active?
True = "Active".
False = "Not Active".
Default is "Active".
Boolean.
O
Scoring Method
Optional. False is "With Penalty". True is "Without penalty". Default is "True".
Boolean
O
Completion Criteria
Optional. If specified then the integer shows the percentage needed to mark as completed. Defaults to "Do not use".
Integer
1 ? 100.
O
Order
Denotes if the test presents questions in a random order from participant to participant Defaults to off.
Boolean
O
MaxTime
Denotes if the test has a time limit. This is specified in minutes from 0 to 35791394. If not specified or ?0? then assume no max test time.
Integer
O
ShowResults
Denotes when results from tests shown. Default is "After Each".
Text
One of:
TeacherDecides
AfterEach
AfterAll
Never
O
ShowFeedback
Denotes when feedback is shown. Options are
·         OnQuestions: Shows feedback after every question).
·         OnAlternatives: Shows feedback after every alternative.
·         No feedback.
Default is No Feedback.
Text
One of:
OnQuestions
OnAlternatives
Nofeedback
O
File 
GUID of the file already uploaded to ITSL.
Text
M
   

Notes

  • Both ParentID and ParentSyncKey are optional. Possible use only one of them either ParentID or ParentSyncKey.

Output

Finished Status:
1.      If the assignment was created successfully.
2.      Returns the Element ID and SyncKey of the element.
 
 
Warning Status:
1.      Unknown assessment (grade) ID - "No assessment" assumed.
2.      Your settings don't allow you to use score as assessment alternative. Please contact your administrator  - "No Assessment" assumed.

Errors Status:

Some error messages only return error codes. In this case, refer to the codes next to the messages e.g. [Error Code: ...], to get a more detailed message.
  1. Invalid format / parameters (different to specified schema).
  2. Message contains duplicates for syncKeys: {0}. Make sure your syncKeys are globally unique.
  3. User with specified UserId/UserSyncKey is not valid.
  4. User with specified UserId/UserSyncKey is deleted.
  5. User with specified UserId/UserSyncKey is external.
  6. Course does not exist.
  7. Course is external.
  8. Course is be deleted.
  9. Course is archived.
  10. ParentSyncKey/ParentId is not an element within the course.
  11. ParentSyncKey/ParentId is not a folder.
  12. Folder related to ParentSyncKey/ParentId has been deleted or removed.
  13. Message must contain valid ParentId.
  14. ParentSyncKey is deleted.
  15. Invalid or unknown ParentSyncKey.
  16. Tile missing or incorrectly formatted.
  17. Rich content badly formatted or invalid in "Description"
  18. Invalid deadline date or not in UTC format.
  19. Test time must be from 1 - 35791394 minutes.
  20. Unknown File (asset) ID. Check the asset has not expired.
  21. Show Results does not match acceptable options.
  22. Show Results does not match acceptable options.
  23. File quota was been exceeded. Element not created.
  24. File format not valid, or corrupt.
  25. Uploaded package is not valid IMS package v1.2 or one or more items is not IMS QTI v2.1 format (item "?" default namespace is "?", expecting "?").   [Error Code: "Uploaded package is not valid IMS package v1.2 or one or more items is not IMS QTI v2.1 format (item ""{FileName}"" default namespace is ""{ProvidedNamespace}"", expecting ""{namespace}"")."]
  26. Uploaded package is not valid IMS package v1.2 or one or more items is not in IMS QTI v2.1 format (expected namespace "?" was not found for item "?"). [Error Code: "Uploaded package is not valid IMS package v1.2 or one or more items is not in IMS QTI v2.1 format (expected namespace ""{Namespace}"" was not found for item ""{FileName}"")."]
  27. Package "?" incomplete. The manifest or assessment items have references to files which do not exist in the package (?). [Error Code: "Package is incomplete. The manifest or assessment items have references to files which do not exist in the package ({ExceptionMessage})."]
  28. The package "?" is incomplete. The manifest or assessment items have references to files which do not exist in the package. [Error Code: "The package is incomplete. The manifest or assessment items have references to files which do not exist in the package."]
  29. An unknown error occurred while importing the package "?". [Error Code: "An unknown error occurred while importing the package ""{Type of exception}"""]
  30. Error while reading assessment item (interaction type "?", resource identifier "?" ). [Error Code: "Error while reading assessment item (interaction type ""{interaction type}"", resource identifier ""{resource identifier}"" )"]
  31. Unsupported functionality! Unable to import item "?" (?). [Error Code: "Test_Import_From_Qti_unsupported_functionality: Unsupported functionality! Unable to import item ""{assessment item ID}"" ({assessment item HREF})"]
  32. An error occurred when trying to import the package ?. Possible causes could be that the zip format is not valid, or the file imsmanifest.xml is missing inside the package. [Error Code: "An error occurred when trying to import the package. Possible causes could be that the zip format is not valid, or the file imsmanifest.xml is missing inside the package."]
  33. An error occurred when trying to import the package ?. The XML in the file imsmanifest.xml inside the package is not in a valid format. [Error Code: "An error occurred when trying to import the package. The XML in the file imsmanifest.xml inside the package is not in a valid format."]
  34. Your security settings doesn't allow you to perform that operation. Please contact administration to grant you an access to {HieararchyName} organisation.


Schema

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:message-schema"
elementFormDefault="qualified"
targetNamespace="urn:message-schema">
<xs:element name="Message" type="MessageType" />
<xs:complexType name="MessageType">
<xs:sequence>
<xs:element name="SyncKeys" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="SyncKey" minOccurs="0" maxOccurs="1" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="SiteId" minOccurs="0" maxOccurs="1" type="xs:int" />
<xs:element name="VendorId" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="36"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="CreateCourseElementTest" type="CreateCourseElementTestType" />
<xs:element name="Files" type="FilesType" minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="CreateCourseElementTestType">
<xs:sequence>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="CourseId" type="xs:integer" />
<xs:element name="CourseSyncKey" type="xs:string" />
</xs:choice>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="ParentId" type="xs:integer" />
<xs:element name="ParentSyncKey" type="xs:string" />
</xs:choice>
<xs:element name="Active" type="xs:boolean" minOccurs="0" maxOccurs="1" default="true" />
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="UserId" type="xs:integer" />
<xs:element name="UserSyncKey" type="xs:string" />
</xs:choice>
<xs:element name="Title" minOccurs="1" maxOccurs="1" >
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="Description" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="Deadline" type="xs:dateTime" minOccurs="0" maxOccurs="1"/>
<xs:choice minOccurs="0" maxOccurs="1">
<xs:element name="Assessment" type="xs:int" default="0"/>
<xs:element name="UseScore" type="xs:boolean" default="false"/>
</xs:choice>
<xs:element name="Mandatory" type="xs:boolean" minOccurs="0" maxOccurs="1" default="true" />
<xs:element name="ScoringMethod" type="xs:boolean" minOccurs="0" maxOccurs="1" default="true" />
<xs:element name="CompletionCriteria" minOccurs="0" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:int">
<xs:minInclusive value="1"/>
<xs:maxInclusive value="100"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="Order" type="xs:boolean" minOccurs="0" maxOccurs="1" default="false"/>
<xs:element name="MaxTime" minOccurs="0" maxOccurs="1" default="0">
<xs:simpleType>
<xs:restriction base="xs:int">
<xs:minInclusive value="0"/>
<xs:maxInclusive value="35791394"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="ShowResults" type="ShowResultsType" minOccurs="0" maxOccurs="1" default="AfterEach"/>
<xs:element name="ShowFeedback" type="ShowFeedbackType" minOccurs="0" maxOccurs="1" default="Nofeedback"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ShowResultsType">
<xs:restriction base="xs:string">
<xs:enumeration value="TeacherDecides" />
<xs:enumeration value="AfterEach" />
<xs:enumeration value="AfterAll" />
<xs:enumeration value="Never" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ShowFeedbackType">
<xs:restriction base="xs:string">
<xs:enumeration value="OnQuestions" />
<xs:enumeration value="OnAlternatives" />
<xs:enumeration value="Nofeedback" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="FilesType">
<xs:sequence>
<xs:element name="File" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="SyncKeyRef" type="xs:IDREF" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>


Message content example

Sample request with assessment
<Message xmlns="urn:message-schema">
<CreateCourseElementTest>
<CourseId>1</CourseId>
<Active>true</Active>
<UserId>2</UserId>
<Title>My Imported Test</Title>
<Description>This test was imported.</Description>
<Deadline>2012-05-01T01:01:01+00:00</Deadline>
<Assessment>1</Assessment>
<Mandatory>true</Mandatory>
<ScoringMethod>true</ScoringMethod>
<CompletionCriteria>1</CompletionCriteria>
<Order>false</Order>
<MaxTime>0</MaxTime>
<ShowResults>AfterEach</ShowResults>
<ShowFeedback>Nofeedback</ShowFeedback>
</CreateCourseElementTest>
<Files>
<File>177e9203-a5c8-4972-ab80-b00c11600b91</File>
</Files>
</Message>
Sample request with score
<Message xmlns="urn:message-schema">
<CreateCourseElementTest>
<CourseId>1</CourseId>
<Active>true</Active>
<UserId>2</UserId>
<Title>My Imported Test</Title>
<Description>This test was imported.</Description>
<Deadline>2012-05-01T01:01:01+00:00</Deadline>
<UseScore>true</UseScore>
<Mandatory>true</Mandatory>
<ScoringMethod>true</ScoringMethod>
<CompletionCriteria>1</CompletionCriteria>
<Order>false</Order>
<MaxTime>0</MaxTime>
<ShowResults>AfterEach</ShowResults>
<ShowFeedback>Nofeedback</ShowFeedback>
</CreateCourseElementTest>
<Files>
<File>177e9203-a5c8-4972-ab80-b00c11600b91</File>
</Files>
</Message>