POST group/…/objectives

POST 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 his or her 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 his or her 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/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

drill
required, repeatable
String

The drill(s) to define the objective for. Courses can also be specified, by their respective codes. This parameter can be repeated to configure multiple drills or courses for the objective.

Example value: h5Zsz2bkSJGwfZvca6cE9A

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.

  • STARTUP
  • 1ST_REMINDER
  • 2ND_REMINDER
  • 3RD_REMINDER

Response

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

Example request

POST https://www.drillster.com/api/2/group/OcPiC-pcH2MaO8pow3TlKB-0wzeHAJzM6vlL1te6wI/objectives
type=ONEOFF
minimumProficiency=90
reviewDate=2013-09-13
drill=vEnKzwihvvNPSArmvdteww
drill=h5Zsz2bkSJGwfZvca6cE9A

Response

{
  "id" : "FnZYjnYSSmufU-mRfgptyQ"
}

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.