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 call, and be specified per group member using the PUT group/…/objective call.
Messages
The objective can be configured to send several types of messages to the users. By default, no messages are sent.
STARTUP
A message informing the user about the defined objective. The message is sent after defining the objective, or when a user joins the group for which the objective is defined.1ST_REMINDER
(ONEOFF
only) A message that is sent if the user has not achieved 25% of the objective's minimum proficiency, at the time that 25% of the available time has passed.2ND_REMINDER
(ONEOFF
only) A message that is sent if the user has not achieved 50% of the objective's minimum proficiency, at the time that 50% of the available time has passed.3RD_REMINDER
(ONEOFF
only) A message that is sent if the user has not achieved 75% of the objective's minimum proficiency, at the time that 75% of the available time has passed.
Resource URL
https://www.drillster.com/api/2.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.
|
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 |
estimatedStudyDuration conditional |
String | The estimated study duration for the practice objective (🔗 ISO 8601). It is required when the parameter joinDateIsStudyStartDate is true. Example value: PT50M30S |
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 . |
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 . |
message optional, repeatable |
String | The message(s) you would like the users to receive. The reminder messages can only be configured for ONEOFF practice objectives. This parameter can be repeated to configure multiple messages.
|
Response
An 2.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. |