Developer Platform (August 2020)

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 satisfied 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 satisfied when its subordinate conditions are satisfied.

{
    "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 satisfied.

Operands

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

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

Conditions

CONDITIONDATA_T

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

Tool

Value

Corresponding Language Term

Awards

EarnsAward

Award Earned

Checklist

CompletesChecklist

Completed checklist

Checklist

CompletesChecklistItem

Completed checklist item

Checklist

NotCompletedChecklist

Incomplete checklist

Checklist

NotCompletedChecklistItem

Incomplete checklist item

Classlist

DaysEnrolledInCurrentOrgUnit

Date of enrollment in current org unit

Classlist

EnrolledInGroup

Group enrollment

Classlist

EnrolledInOrgUnit

Org unit enrollment

Classlist

EnrolledInSection

Section enrollment

Classlist

RoleInCurrentOrgUnit

Role in current org unit

Content

CompletesContentTopic

Completed content topic

Content

NotCompletedContentTopic

Not completed content topic

Content

NotVisitedContentTopic

Not visited content topic

Content

VisitsAllContentTopics

Visited all content topic

Content

VisitsContentTopic

Visited content topic

Discussions

AuthorsPostsInTopic

Posts authored in topic

Discussions

NotAuthoredPostsInTopic

No posts authored in topic

Dropboxes

NotSubmittedToDropbox

No submission to folder

Dropboxes

ReceivesFeedback

Receive feedback on submission

Dropboxes

SubmitsToDropbox

Submission to folder

Grades

NotReceivedScoreOnGradeItem

No grade received

Grades

ReceivesScoreOnGradeItem

Grade value on a grade item

Grades

ReleasedFinalGrade

Released final grade score

Quizzes

NotSubmittedQuizAttempt

No completed quiz attempt

Quizzes

ReceivesScoreOnQuiz

Score on a quiz

Quizzes

SubmitsQuizAttempt

Completed quiz attempt

CURRENTROLE_T

RoleInCurrentOrgUnit conditions may use the following comparison operators:

Value

Description

Enrolled

User is enrolled as this role

NotEnrolled

User is enrolled in any role except for this role

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 ].

POSTS_T

AuthorsPostsInTopic and NotAuthoredPostsInTopic conditions may use the following posting types:

Value

Description

NewThreadsOnly

Posts new threads only

ThreadsAndReplies

Posts new threads or replies to existing threads

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 satisfied 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.

Checklist

CompletesChecklist

A condition that is satisfied when a user completes all items within a checklist.

CompletesChecklistData
{
    "Type": "CompletesChecklist",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "CompletesChecklistParams": { <composite:CompletesChecklistParams> }
}
CompletesChecklistParams
{
    "ChecklistId": <number:D2LID>
}
ChecklistId

Corresponds to the Id property on a checklist.

CompletesChecklistItem

A condition that is satisfied when a user completes a checklist item.

CompletesChecklistItemData
{
    "Type": "CompletesChecklistItem",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "CompletesChecklistItemParams": { <composite:CompletesChecklistItemParams> }
}
CompletesChecklistItemParams
{
    "ChecklistItemId": <number:D2LID>,
    "ChecklistId": <number:D2LID>
}
ChecklistItemId

Corresponds to the ChecklistItemId property on a checklist item.

ChecklistId

Corresponds to the Id property on a checklist.

NotCompletedChecklist

A condition that is satisfied when a user has not yet completed all items within a checklist. Once the user completes all of the checklist’s items, this condition cannot be satisfied.

NotCompletedChecklistData
{
    "Type": "NotCompletedChecklist",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotCompletedChecklistParams": { <composite:NotCompletedChecklistParams> }
}
NotCompletedChecklistParams
{
    "ChecklistId": <number:D2LID>
}
ChecklistId

Corresponds to the Id property on a checklist.

NotCompletedChecklistItem

A condition that is satisfied when a user has not yet completed a checklist item. Once the user completes the checklist item, this condition cannot be satisfied.

NotCompletedChecklistItemData
{
    "Type": "NotCompletedChecklistItem",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotCompletedChecklistItemParams": { <composite:NotCompletedChecklistItemParams> }
}
NotCompletedChecklistItemParams
{
    "ChecklistItemId": <number:D2LID>,
    "ChecklistId": <number:D2LID>
}
ChecklistItemId

Corresponds to the ChecklistItemId property on a checklist item.

ChecklistId

Corresponds to the Id property on a checklist.

Classlist

DaysEnrolledInCurrentOrgUnit

A condition that is satisfied when the number of days that have elapsed since the user was first enrolled in the current org unit exceeds a threshold.

DaysEnrolledInCurrentOrgUnitData
{
    "Type": "DaysEnrolledInCurrentOrgUnit",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "DaysEnrolledInCurrentOrgUnitParams": { <composite:DaysEnrolledInCurrentOrgUnitParams> }
}
DaysEnrolledInCurrentOrgUnitParams
{
    "NumberOfDays": <number>
}
NumberOfDays

The number of days that must have elapsed since the user was first enrolled in the org unit.

Calculation. duration = (today - date_of_first_enrollment). Duration does not take into account any periods of unenrollment and does not reset when a user is re-enrolled in the org unit.

EnrolledInGroup

A condition that is satisfied 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.

EnrolledInOrgUnit

A condition that is satisfied when a user is enrolled in an org unit.

EnrolledInOrgUnitData
{
    "Type": "EnrolledInOrgUnit",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "EnrolledInOrgUnitParams": { <composite:EnrolledInOrgUnitParams> }
}
EnrolledInOrgUnitParams
{
    "OrgUnitId": <number:D2LID>
}
OrgUnitId

Corresponds to the Identifier property on an org unit.

EnrolledInSection

A condition that is satisfied when a user is enrolled in a section.

EnrolledInSectionData
{
    "Type": "EnrolledInSection",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "EnrolledInSectionParams": { <composite:EnrolledInSectionParams> }
}
EnrolledInSectionParams
{
    "SectionId": <number:D2LID>
}
SectionId

Corresponds to the SectionId property on a section.

RoleInCurrentOrgUnit

A condition that is satisfied when a user is enrolled in the current org unit either with a specific role, or with any role other than a specific role.

RoleInCurrentOrgUnitData
{
    "Type": "RoleInCurrentOrgUnit",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "RoleInCurrentOrgUnitParams": { <composite:RoleInCurrentOrgUnitParams> }
}
RoleInCurrentOrgUnitParams
{
    "RoleId": <number:D2LID>,
    "EnrollmentType": <string:CURRENTROLE_T>
}
RoleId

Corresponds to the Identifier property on a role.

EnrollmentType

Enrollment type to use for role comparison.

Content

CompletesContentTopic

A condition that is satisfied when a user completes a content topic.

CompletesContentTopicData
{
    "Type": "CompletesContentTopic",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "CompletesContentTopicParams": { <composite:CompletesContentTopicParams> }
}
CompletesContentTopicParams
{
    "TopicId": <number:D2LID>
}
TopicId

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

NotCompletedContentTopic

A condition that is satisfied when a user has not yet completed a content topic. Once the user completes the content topic, this condition cannot be satisfied.

NotCompletedContentTopicData
{
    "Type": "NotCompletedContentTopic",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotCompletedContentTopicParams": { <composite:NotCompletedContentTopicParams> }
}
NotCompletedContentTopicParams
{
    "TopicId": <number:D2LID>
}
TopicId

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

NotVisitedContentTopic

A condition that is satisfied when a user has not yet viewed a content topic. Once the user views the content topic, this condition cannot be satisfied.

NotVisitedContentTopicData
{
    "Type": "NotVisitedContentTopic",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotVisitedContentTopicParams": { <composite:NotVisitedContentTopicParams> }
}
NotVisitedContentTopicParams
{
    "TopicId": <number:D2LID>
}
TopicId

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

VisitsAllContentTopics

A condition that is satisfied when a user has viewed all content topics in the org unit.

VisitsAllContentTopicsData
{
    "Type": "VisitsAllContentTopics",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "VisitsAllContentTopicsParams": {}
}

Parameters. Although no parameters are supported by this condition, you must pass an empty object in the VisitsAllContentTopicsParams field when creating this condition.

Calculation. Users are required to view all topics that have been made visible to learners, excluding:

  • Topics that are hidden from users

  • Topics that are descendants of modules that are hidden from users

No other restrictions are taken into account. Users will be required to have viewed topics that are restricted by other mechanisms. Therefore, this condition may not be satisfiable in org units having content with additional restrictions.

The following is an incomplete list of restrictions not taken into account:

  • Availability dates

  • Broken links

  • Exemptions

  • Group or section restrictions

  • Permissions

  • Release conditions

  • Special access restrictions

VisitsContentTopic

A condition that is satisfied when a user views 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.

Discussions

AuthorsPostsInTopic

A condition that is satisfied when a user authors posts in a discussion topic.

AuthorsPostsInTopicData
{
    "Type": "AuthorsPostsInTopic",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "AuthorsPostsInTopicParams": { <composite:AuthorsPostsInTopicParams> }
}
AuthorsPostsInTopicParams
{
    "ForumId": <number:D2LID>,
    "TopicId": <number:D2LID>,
    "NumberOfPosts": <number>,
    "PostsType": <string:POSTS_T>
}
ForumId

Corresponds to the ForumId property on a discussion topic.

TopicId

Corresponds to the TopicId property on a discussion topic.

NumberOfPost

The number of posts a user must author to satisfy the condition.

PostsType

The types of posts that count towards satisfying the condition.

NotAuthoredPostsInTopic

A condition that is satisfied when a user has not yet authored a post in a discussion topic. Once the user authors a post in the discussion topic, this condition cannot be satisfied.

NotAuthoredPostsInTopicData
{
    "Type": "NotAuthoredPostsInTopicData",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotAuthoredPostsInTopicParams": { <composite:NotAuthoredPostsInTopicParams> }
}
NotAuthoredPostsInTopicParams
{
    "ForumId": <number:D2LID>,
    "TopicId": <number:D2LID>,
    "PostsType": <string:POSTS_T>
}
ForumId

Corresponds to the ForumId property on a discussion topic.

TopicId

Corresponds to the TopicId property on a discussion topic.

PostsType

The types of posts that count towards unsatisfying the condition.

Dropboxes

NotSubmittedToDropbox

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

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.

ReceivesFeedback

A condition that is satisfied when a user’s submission receives feedback.

ReceivesFeedbackData
{
    "Type": "ReceivesFeedback",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "ReceivesFeedbackParams": { <composite:ReceivesFeedbackParams> }
}
State, Text

Inherited.

ReceivesFeedbackParams
{
    "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

NotReceivedScoreOnGradeItem

A condition that is satisfied when a user has not yet received a score on a grade item. Once the user receives a grade value, this condition cannot be satisfied.

NotReceivedScoreOnGradeItemData
{
    "Type": "NotReceivedScoreOnGradeItem",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotReceivedScoreOnGradeItemParams": { <composite:NotReceivedScoreOnGradeItemParams> }
}
State, Text

Inherited.

NotReceivedScoreOnGradeItemParams
{
    "GradeObjectId": <number:D2LID>
}
GradeObjectId

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

ReceivesScoreOnGradeItem

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

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

ReleasedFinalGrade

A condition that is satisfied when a user’s final grade is released, optionally requiring that it match the supplied criteria.

ReleasedFinalGradeData
{
    "Type": "ReleasedFinalGrade",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "ReleasedFinalGradeParams": { <composite:ReleasedFinalGradeParams> }
}
State, Text

Inherited.

ReleasedFinalGradeParams

The condition can either require that the grade be released only, or be released and satisfy the supplied criteria.

{
    "Operator": <string:OPERATOR_T>|null,
    "Operands": [ <number:decimal>, ... ]|null
}
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.

Quizzes

NotSubmittedQuizAttempt

A condition that is satisfied when a user has not yet submitted a quiz attempt. Once the user submits a quiz attempt, this condition cannot be satisfied.

NotSubmittedQuizAttemptData
{
    "Type": "NotSubmittedQuizAttempt",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "NotSubmittedQuizAttemptParams": { <composite:NotSubmittedQuizAttemptParams> }
}
State, Text

Inherited.

NotSubmittedQuizAttemptParams
{
    "QuizId": <number:D2LID>
}
QuizId

Corresponds to the QuizId property of a quiz.

ReceivesScoreOnQuiz

A condition that is satisfied 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.

SubmitsQuizAttempt

A condition that is satisfied when a user submits one or more quiz attempts.

SubmitsQuizAttemptData
{
    "Type": "SubmitsQuizAttempt",
    "State": <string>|null,
    "Text": { <composite:RichText> },
    "SubmitsQuizAttemptParams": { <composite:SubmitsQuizAttemptParams> }
}
State, Text

Inherited.

SubmitsQuizAttemptParams
{
    "QuizId": <number:D2LID>,
    "NumberOfAttempts": <number>
}
QuizId

Corresponds to the QuizId property of a quiz.

NumberOfAttempts

The number of attempts a user must submit to satisfy the condition. Cannot exceed the number of attempts allowed on the quiz.

Targets

TARGET_T

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

Value

Corresponding Resource

ID Property

awardAssociations

Award Association

AssociationId

checklists

Checklist

Id

contentObjects

Content Object

Id

discussionForums

Discussion Forum

ForumId

discussionTopics

Discussion Topic

TopicId

dropboxes

Dropbox Folder

Id

grades

Grade Object

Id

news

News Item

Id

quizzes

Quiz

QuizId

surveys

Survey

SurveyId

Note

When making calls with a targetType of “surveys”, if the survey identified by the targetId is anonymous, then a 400 Bad Request status code will be indicated in the response as anonymous surveys cannot have release conditions.

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 – Release conditions cannot be applied to the provided target (the message will describe the reason), or 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.

  • 429 Too Many Requests – API call-rate limit exceeded.

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  »