Developer Platform (November 2019)

Release Conditions

«  Checklists (Checklists, Categories, Checklist Items)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Quizzes  »

Contents

Release conditions provide the ability to dynamically release resources to users that have satisified one or more conditions. Several types of resources can be the target of release conditions, including content, discussions and quizzes. Brightspace offers a broad range of conditions over its suite of tools, ranging from activity completion, such as posting to discussions and submitting assignments, to receiving evaluations in the form of grades and quizzes.

Attributes

ConditionsData

Conditions on a resource are represented using a top-level expression.

{
    "Expression": { <composite:ExpressionData> }
}

Expressions

EXPRESSIONOPERATOR_T

Expressions support two satisfiability modes.

Value

Description

All

All conditions must be met

Any

Any condition must be met

ExpressionData

An expression is a group of conditions that is satisified when its subordinate conditions are satisified.

{
    "Type": "Expression",
    "State": null,
    "ExpressionParams": { <composite:ExpressionParams> },
    "Text": { <composite:RichText> }
}
ExpressionParams

Expressions are composed of an operator and one or more condition operands.

{
    "Operator": <string:EXPRESSIONOPERATOR_T>,
    "Operands": [ { <composite:ConditionData> }, ... ]
}
Operator

The method by which the expression is satisified.

Operands

Zero or more conditions, joined by the Operator, that comprise the expression.

When an expression contains no condition operands, it is always considered satisified.

Conditions

CONDITIONDATA_T

Brightspace offers a broad range of conditions over its suite of tools.

Value

Corresponding Language Term

EarnsAward

Awards > Award Earned

EnrolledInGroup

Classlist > Group enrollment

NotSubmittedToDropbox

Assignments > No submission to folder

ReceivesScoreOnGradeItem

Grades > Grade value on a grade item

ReceivesScoreOnQuiz

Quizzes > Score on a quiz

SubmitsToDropbox

Assignments > Submission to folder

VisitsContentTopic

Content > Visited content topic

OPERATOR_T

Conditions that compare scores may use the following comparison operators:

Value

Arity

Formula

Between

2

(score ≥ a ) ∧ (score ≤ b)

EqualTo

1

score = a

GreaterThan

1

score > a

GreaterThanOrEqual

1

score ≥ a

LessThan

1

score < a

LessThanOrEqual

1

score ≤ a

NotBetween

2

(score < a) ∨ (score > b)

NotEqualTo

1

score ≠ a

Operands. Operands are in the form [ a, b ].

ConditionData

Condition structures vary depending on their type.

Basic. All conditions share the following common properties:

{
    "Type": <string:CONDITIONDATA_T>,
    "State": <string>|null,
    "Text": { <composite:RichText> }
}
Type

A unique, case-sensitive string that identifies the behavior of the condition. Conditions have additional type-specific parameters exposed as an object. Available conditions and their parameter structures are described below, grouped by tool.

Types supported by Brightspace that are not currently supported in the API are identified by the “RoundTrip” type and do not include a params object.

State

Opaque value used by Brightspace to round-trip conditions that are not supported either by your client or the API. When creating conditions, you may omit this property or specify null.

Text

Generated by the server to describe the condition behavior in plain language. When modifying conditions, you may omit this property or specify null.

Compatibility. New types may be added in future versions of Brightspace. Your client does not need to support all of the available types. When modifying conditions, your client must include unsupported conditions with both their Type and State properties, otherwise they will be removed from the target, resulting in an unintended change.

Awards

EarnsAward

A condition that is satisified when a user earns an award.

EarnsAwardData
{
    "Type": "EarnsAward",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "EarnsAwardParams": { <composite:EarnsAwardParams> }
}
State, Text

Inherited.

EarnsAwardParams
{
    "AssociationId": <number:D2LID>
}
AssociationId

Corresponds to the AssociationId property on an awards association.

Classlist

EnrolledInGroup

A condition that is satisified when a user is enrolled in a group or a group category.

EnrolledInGroupData
{
    "Type": "EnrolledInGroup",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "EnrolledInGroupParams": { <composite:EnrolledInGroupParams> }
}
EnrolledInGroupParams

The condition can either require membership of a specific group, or any group within a group category.

{
    "GroupId": <number:D2LID>|null,
    "GroupCategoryId": <number:D2LID>|null
}
GroupId

Corresponds to the GroupId property on a group. Mutually exclusive with GroupCategoryId.

GroupCategoryId

Corresponds to the GroupCategoryId property on a group category. Mutually exclusive with GroupId.

Content

VisitsContentTopic

A condition that is satisified when a user has viewed a content topic.

VisitsContentTopicData
{
    "Type": "VisitsContentTopic",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "VisitsContentTopicParams": { <composite:VisitsContentTopicParams> }
}
VisitsContentTopicParams
{
    "TopicId": <number:D2LID>
}
TopicId

Corresponds to the Id attribute on a content object of type Topic.

Dropboxes

NotSubmittedToDropbox

A condition that is satisified when a user has not yet submitted to a dropbox folder. Once a user submits to the dropbox, this condition cannot be satisified.

NotSubmittedToDropboxData
{
    "Type": "NotSubmittedToDropbox",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotSubmittedToDropboxParams": { <composite:NotSubmittedToDropboxParams> }
}
NotSubmittedToDropboxParams
{
    "FolderId": <number:D2LID>
}
FolderId

Corresponds to the Id property on a dropbox folder.

SubmitsToDropbox

A condition that is satisfied when a user submits to a dropbox folder.

SubmitsToDropboxData
{
    "Type": "SubmitsToDropbox",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "SubmitsToDropboxParams": { <composite:SubmitsToDropboxParams> }
}
State, Text

Inherited.

SubmitsToDropboxParams
{
    "FolderId": <number:D2LID>
}
FolderId

Corresponds to the Id property on a dropbox folder.

Grades

ReceivesScoreOnGradeItem

A condition that is satisified when a user receives a score on a grade item matching the supplied critieria.

ReceivesScoreOnGradeItemData
{
    "Type": "ReceivesScoreOnGradeItem",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "ReceivesScoreOnGradeItemParams": { <composite:ReceivesScoreOnGradeItemParams> }
}
State, Text

Inherited.

ReceivesScoreOnGradeItemParams
{
    "GradeObjectId": <number:D2LID>,
    "Operator": <string:OPERATOR_T>,
    "Operands": [ <number:decimal>, ... ]
}
GradeObjectId

Corresponds to the Id property on a grade object of type Numeric, PassFail or SelectBox.

Operator

Operator to use for the grade value comparison.

Operands

One or two percentage values, depending on the Operator, to compare the grade value against.

Numeric. Grade values are compared with the operands directly.

PassFail. Two comparisons are supported.

Pass.

{
    "GradeObjectId": <number:D2LID>,
    "Operator": "GreaterThan",
    "Operands": [ 0 ]
}

Fail.

{
    "GradeObjectId": <number:D2LID>,
    "Operator": "EqualTo",
    "Operands": [ 0 ]
}

SelectBox. Operands must correspond to a PercentStart value in the grade scheme. If they do not, they are rounded down to the nearest range. Grade values are then compared with the operands directly.

It is invalid to supply the following comparison criteria:

  • Less than the lowest grade scheme range

  • Greater than the highest grade scheme range

Quizzes

ReceivesScoreOnQuiz

A condition that is satisified when a user’s overall quiz score is graded and matches the supplied criteria.

ReceivesScoreOnQuizData
{
    "Type": "ReceivesScoreOnQuiz",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "ReceivesScoreOnQuizParams": { <composite:ReceivesScoreOnQuizParams> }
}
State, Text

Inherited.

ReceivesScoreOnQuizParams
{
    "QuizId": <number:D2LID>,
    "Operator": <string:OPERATOR_T>|null,
    "Operands": [ <number:decimal>, ... ]|null
}
QuizId

Corresponds to the QuizId property of a quiz.

Operator

Operator to use for the quiz score comparison.

Operands

One or two percentage values, depending on the Operator, to compare the quiz score against.

Targets

TARGET_T

Several types of resources can be the target of release conditions.

Value

Corresponding Resource

ID Property

contentObjects

Content Object

Id

discussionForums

Discussion Forum

ForumId

discussionTopics

Discussion Topic

TopicId

dropboxes

Dropbox Folder

Id

quizzes

Quiz

QuizId

Actions

GET /d2l/api/lp/(version)/(orgUnitId)/conditionalRelease/conditions/(targetType)/(targetId)

Retrieve the conditions on a target in the org unit.

Parameters
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • targetType (TARGET_T) – Target type.

  • targetId (D2LID) – Target ID.

Status Codes
API Versions
  • 1.25+ – Route first appears in LMS v20.19.11

Return. This action returns a ConditionsData JSON structure representing the conditions on the target. When the target has no conditions, the ExpressionData will be present but its Operands will be empty.

PUT /d2l/api/lp/(version)/(orgUnitId)/conditionalRelease/conditions/(targetType)/(targetId)

Replace the conditions on a target in the org unit.

Parameters
  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • targetType (TARGET_T) – Target type.

  • targetId (D2LID) – Target ID.

JSON Parameters
Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – One or more parameters in the request are invalid. When possible, the message will identify the specific invalid token.

  • 404 Not Found – Target not found in the org unit.

  • 403 Forbidden – No permission to replace conditions for the target.

API Versions
  • 1.25+ – Route first appears in LMS v20.19.11

Input. Provide a ConditionsData JSON structure specifying the desired conditions on the target. When modifying existing condition structures, you should include the retrieved State property with your modifications. When modifying or adding condition structures, you may omit the Text property (it is ignored). To remove all of the conditions from the target, specify a ExpressionData structure containing an empty Operands property.

«  Checklists (Checklists, Categories, Checklist Items)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Quizzes  »