POST group/…/objectives

Defines a new practice objective for a group.

A practice objective is either a ONEOFF, PERMANENT or RECURRING objective. Test objectives cannot be defined with this API call.

Objective types

A ONEOFF practice objective defines a minimum proficiency that the user should achieve, for one or more drills, before a specified review date. The objective is met by the user if their proficiency for the drill(s) at the review date is the defined minimum, or higher. If the user achieves the minimum proficiency before the review date, it does not mean that the objective is met, since the proficiency might drop below the minimum if the user stops practicing.

A PERMANENT practice objective defines a minimum proficiency that the user should retain, for one or more drills, after a specified review date. The objective is met by the user if their proficiency for the drill(s) after the review date is the defined minimum, or higher. If the proficiency drops below the minimum, the objective is no longer met.

A RECURRING practice objective defines a minimum proficiency that the user should achieve, for one or more drills, before a specified review date, or during a review period, which keeps on recurring by its defined cycle. The objective is met by the user if their proficiency for each of the drills at the review date, or during the review period is more or equal to the defined minimum.

Review date

If a reviewDate is specified, the objective is reviewed at that date for all group members. It is also possible to be more flexible, and use a review date per group member. To do so, the review date must be omitted in this endpoint, and be specified per group member using the PUT group/…/objective endpoint.

Review period

A review period is a period of time for a ONEOFF or RECURRING objective, wherein the user is expected to achieve the minimum proficiency. Once the minimum proficiency is achieved, the objective is met, and remains met indefinitely for a ONEOFF objective, and until the next objective start for a RECURRING objective.

The review period is defined by specifying a reviewDate to mark the end of the period, and a reviewDuration that defines the length of the period. If a reviewDuration, but no reviewDate is specified, a review date can be specified per group member, using the PUT group/…/objective endpoint.

Cycle duration

In case of a RECURRING objective, the cycle duration is a necessary field. It represents the calendar period where the objective repeats, after the first review date. It represents an idle period where the objective is not active + either a study period ending with a review date or a review period.

Resource URL

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

The group ID is the unique identifier for the group.

Parameters

Field Type Description
group_id
required		 String The unique ID of the group.

Example value: OcPiC-pcH2MaO8pow3TlKB-0wzeHAJzM6vlL1te6wI
type
required		 String constant The type of the practice objective.
  • ONEOFF
  • PERMANENT
minimumProficiency
required		 Integer The minimum proficiency to achieve or retain (0-100)

Example value: 95
reviewDate
optional		 Date The review date for the practice objective (ISO 8601). The date must be in the future. Can be omitted for user-specific review dates.

Example value: 2013-12-10T03:06Z
reviewDuration
optional		 Duration The duration of the review period for the practice objective (ISO 8601). Can be omitted for user-specific review period.

Note: Months (M) in a duration are converted to a fixed number of days (30). Years (Y) are not supported.

Example value: P30D
estimatedStudyDuration
conditional		 String The estimated study duration for the practice objective (ISO 8601). It is required when the parameter joinDateIsStudyStartDate is true.

Note: Months (M) in a duration are converted to a fixed number of days (30). Years (Y) are not supported.

Example value: P30D
cycleDuration
conditional		 String The duration of a whole RECURRING objective, before it repeats again (ISO 8601).

note that a month or year is depending on the calendar date of the reviewDate.

Example value: P4M
joinDateIsStudyStartDate
optional		 Boolean When true new members added to the group will have personalized practice objectives, where the review date will be calculated in function of the estimatedStudyDuration and the date where the new member was added to the group.

Valid values are: TRUE and FALSE. The value is optional and defaults to FALSE.
name
optional		 String The custom name of the practice objective. If no name is given, a standard name is constructed.
drillable
required, repeatable		 String The drill(s) or course(s) to define the objective for. This parameter can be repeated to configure multiple drills or courses for the objective.

Example value: h5Zsz2bkSJGwfZvca6cE9A
messageStartup Boolean Whether to send a one-off startup message to inform users that an objective has been set.

Valid values are: TRUE and FALSE. The value is optional and defaults to FALSE.

Response

An 2.1.1 Objective object, with only its id property set.

Error responses

The following error situations are possible:

ID Description
group_not_found Could not retrieve group details.
no_access You are not allowed to add objectives to this group.
drills_missing You are not specifying drills, or they are not usable.
invalid_objective_type You are specifying an invalid objective type, or you are trying to create a test.
invalid_review_date The provided objective review date is not valid.
invalid_estimated_study_duration The provided estimated study duration is not valid.
no_estimated_study_review_duration If you specified joinDateIsStudyStartDate, but you specified neither reviewDuration nor estimatedStudyDuration.
invalid_review_duration The provided review duration is not valid or negative.
wrong_combination An invalid combination of input fields was provided.

 

Last updated on