POST group/…/objectives

Defines a new practice objective for a group.

A practice objective is either a ONEOFF or a PERMANENT 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.

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 objective, wherein the user is expected to achieve the minimum proficiency. Once the minimum proficiency is achieved, the objective is met, and remains met until the end of the review period, even if the user's proficiency drops below the minimum again before the end of the review period.

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.

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
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 members to this group.
invalid_review_date The provided objective review date is not valid.
invalid_estimated_study_duration The provided estimated study duration is not valid.
invalid_review_duration The provided review duration is not valid.
invalid_input_combination An invalid combination of input fields was provided.

 

Last updated on