POST group/…/tests

Defines a new group test. A test consists of a fixed number of questions taken from one or more drills. The user taking the test answers each question, but will not receive any feedback while doing so. When finished, a score is calculated based on the number of correct answers.

Objective

An objective can be set for a group test. The objective is to complete the test before a specific date. To set an objective, a reviewDate must be specified. The test can be further configured with a reminder message, and an announcement message. See the parameters below for more information.

Adaptive test

An adaptive test selects test questions adaptively, based on the user's previous answers. It is defined with two or more drills, with each drill representing a difficulty level. The drills are specified in increasing difficulty order. The specified questions defines the number of questions that is taken from each drill (level).

After answering all question of a level, a decision is made which level to use next. If the user answered < 1/3 of the questions correctly, the level below the current one is used. If the user answered >= 1/3 and < 2/3 of the questions correctly, the same level is continued. If the user answered >= 2/3 of the questions correctly, the level above the current level is used. If a lower or higher level is not available, the same level is continued.

The total number of questions of the test depends on the number of defined levels (drills), and the entry level (the drill from which the first question is taken). By default, the entry level halfway (#levels/2), but can be specified per user when obtaining the first test question. The score of the test is the evaluation of the last set of questions.

To define an adaptive test, set adaptive to TRUE, make sure to specify at least two drills, and specify the number of questions per drill (once).

Resource URL

https://www.drillster.com/api/2.1.1/group/{group_id}/tests

Parameters

Field Type Description
drill
required, repeatable		 String The drill to test. Can be specified multiple times to test multiple drills in a single test.

Example value: yy9p1ivLSMGGvoX8PkBsv
title
optional		 String The title of the test. If not specified, the name of the drill is used, or the subject if more than one drill is specified.

Example value: Testing my geography
instructions
optional		 String An instruction text that will be presented just before the test starts. These typically contain directions for the user taking the test.

Example value: Carefully read the test questions, and take your time to select the correct answer.
disclosure
optional		 String The disclosure defines what test results the user will see after finishing the test. Two components can be displayed:

  • Test score — the user's score for the test (0-100%)
  • Detailed results — the test metadata, the evaluation of each answer, plus the score per drill if multiple drills were tested.
The possible values are:

  • FULL — The test score and the detailed results (default)
  • PARTIAL — Only the test score
  • NONE — No results are displayed
direction
optional		 String The enforced direction for the questions of this test. If the drill of this test has an enforced direction, this will be used instead of the provided direction.

  • PRODUCTIVE — Reproduce what you've learned: questions are picked from the known column
  • RECEPTIVE — Recognize what you've learned: questions are picked from the unknown column(s)
  • BIDIRECTIONAL — Questions are picked from both the known and unknown columns (default)
style
optional		 String The answer style for the questions of this test. If the drill(s) of this test have a enforced style, this style will be used instead of the provided style.

  • MULTIPLE_CHOICE — The user has to select the correct answer from two or more presented answers (default)
  • OPEN_ENDED — The user has to enter the correct answer
column
optional, repeatable		 String The name of the unknown column to include in the test questions. If the drill that is tested has more than one unknown column, you can limit the questions that will appear in the test by specifying the name of the unknown column. You can specify this parameter multiple times if you want to include multiple unknown columns.

Omitting this parameter will include all available unknown columns in the test.

Example value: French
tag
optional, repeatable		 String The entry tag to include in the test questions. Entry tags can be attached to specific drill entries in the drill editor. Each drill specified for this test must have at least one of the entry tags you specify. You can specify this parameter multiple times if you want to include multiple entry tags.

Omitting this parameter will include all available entries in the test.

Example value: grammar
questions
optional, repeatable		 Integer The number of questions to include in the test. This can't be higher than the number of entries in the drill(s). If omitted, 40 questions will be selected by default (or less if the drill does not have 40 entries). The questions will be selected randomly from the specified drill(s).

If more than one drill is specified, and this parameter is provided once, the number of questions taken from each drill is proportional to the size (number of entries) of the drill. If, for example, you specify 2 drills, one having 20 entries and the other 40, and you specify questions once, with value 30, 10 questions will be taken from the 1st drill, and 20 from the 2nd.

However, if the parameter is provided more than once (while specifying more than one drill), the number of questions taken from each drill is the value of each parameter. This means that for each drill, one questions parameter must be specified – no more, and no less. The first parameter value specifies the number of questions taken from the first drill, the second parameter value specifies the number of questions from the second drill, etc. So, for example, you specify drill A and B (in that order), and you specify questions=15 and questions=20 (in that order), 15 questions will be taken from drill A, and 20 from drill B.

For adaptive tests, this parameter must be specified exactly once, and indicates the number of questions that will be taken from each drill.
weights
optional, repeatable		 Integer The weight of each drill on the result of the test. When more than one drill is specified, you can set a weight for each drill. The weight of the drill is used to adjust the contribution of the answers for the drill to the overall score. The value of the weight can anything between 0 and 100 (inclusive). By default, the weight of each drill is 100.

If the test contains two drills, and the first drill's weight is 50, and the second is 100, the answers on questions from the second drill will have twice the impact of answers on the first drill.

The number of specified weight values must match the number of specified drill values. The order of the weight values must match that of the drill values, so the first weight value applies to the first drill, etc.
adaptive
optional		 Boolean Specify TRUE for an adaptive test, or FALSE (or omit) for standard a test.

  • TRUE
  • FALSE (default)
timeLimit
optional		 ISO 8601 duration Specifies the maximum time that the user is allowed to complete the test. Answers submitted after this time limit (or not submitted) are considered incorrect. The time is measured from the moment the first question is presented. It is not possible to configure a time limit for adaptive tests (adaptive = TRUE), or for tests that contain drills with answer time limits.

If a time limit is specified, allowUnansweredQuestions must be TRUE.

Example values:
  • PT10M30S (10 minutes 30 seconds)
  • PT1H (1 hour)
allowQuestionNavigation
optional		 Boolean Specify TRUE (or omit) to allow the user to navigate (go back and forth) between the questions of the test, or FALSE to force the user to see and answer all questions in the order defined by the test.

It is not possible to allow question navigation for adaptive tests, nor for tests with drills containing answer time limits. For these tests, FALSE must be specified.

  • TRUE (default)
  • FALSE
allowUnansweredQuestions
optional		 Boolean Specify TRUE allow the user to complete the test while one or more questions are unanswered, or FALSE (or omit) to force the user to answer all questions before completing the test.

  • TRUE
  • FALSE (default)
reviewDate
optional		 Date The date that all group members are expected to have completed the test. Group members can't start or complete the test after this date. If the value PER_USER can be specified to indicate that a review date will be configured per group member after this objective has been set up. This can be done with the PUT group/…/objective/… call.

The review date must be a future date, and it must be formatted according the ISO-8601 standard. It is allowed to include a time in the date.

Example value: 2013-10-24T20:00
reminderDays
optional		 Integer If specified, a reminder email is sent to all group members who have not completed the test the specified number of days before the review date. The email reminds the users about the test's upcoming review date.

A value of 1 to 30 can be used, and a review date must have been specified.

Example value: 2
sendAnnouncement
optional		 Boolean If TRUE, an email is sent to all group members, announcing the test and its review date. The email contains a hyperlink that will take the user directly to the test. The emails are sent within 24 hours after defining the test, or within 24 hours after a new user joins the group after this test was defined.

A review date must have been specified.

  • TRUE
  • FALSE (default)

Response

A 2.1.1 Group object with only its id populated.

Example request

POST https://www.drillster.com/api/2.1/tests
drill=1J-_acRwTnmyN03eMS5IHw&drill=FHh6PtOzQFWK-LH_Roe0xw&title=Testing+all+european+capitals&disclosure=PARTIAL&questions=12&questions=8

Response

{
  "id": "HCg9aaeZRdGEw16dLXUowQ"
}

Error responses

The following error situations are possible:

ID Description
drill_not_released You specified one or more drills that have not been released. Group tests can only be defined for drills that have been released.
drills_missing You did not specify any drills.
inaccessible_drill You specified one or more drills that you are not allowed to use. It might be a private drill of another user.
empty_drill The drills you specified don't have any entries.
invalid_direction The specified direction is not one of the possible values.
invalid_disclosure The specified disclosure is not one of the possible values.
invalid_nr_of_questions The specified question value(s) is invalid, e.g. more than the available number of drill entries, or in case you specified more than one question parameters, the number of parameters does not match the number of drills.
invalid_reminder_days The specified reminder days are invalid. It must be 1-30.
invalid_review_date The specified review date is invalid. It must formatted according the ISO-8601 standard.
invalid_style The specified style is not one of the possible values.
invalid_test_type The specified test type is not one of the possible values.
no_permission Your Drillster account does not allow setting up tests. For an individual test, you must have a Drillster Premium Account, and for an anonymous test you must have a Educational or Business Account.
non_public_drill You are setting up an anonymous test, but you specified one or more drills that are not public. For anonymous tests, all drills must be public, otherwise the users taking the test can't access them.
reminder_days_not_allowed Reminder days were specified, but no review date.
review_date_in_past The specified review date is not in the future.
send_announcement_not_allowed An announcement was specified, but no review date.
unknown_drill You specified one or more non-existing drills.

 

Last updated on