Valence (May 2016)

Grades (grade objects, categories, values, schemes)

«  Dropboxes (Folders, categories, submissions, feedback)   ·  [   home  ·   reference  ·   community   ·  index   ·  routing table   ·  modules   ]   ·  Course content (content objects, ISBNs, tables of content)  »

Contents

Attributes

GRADEOBJ_T

Grade objects support several different means of assessment. We organize these into a list of grade object types and use the term GRADEOBJ_T to stand in for an appropriate integer value.

Grade object type Value
Numeric 1
PassFail 2
SelectBox 3
Text 4
Calculated 5 ^
Formula 6 ^
FinalCalculated 7 ^
FinalAdjusted 8 ^
Category 9 ^

^ Direct creation of these types through these APIs is not supported.

GRADINGSYSTEM_T

Each org unit is configured with a grading system that is used by all grade objects in the org unit. These string labels identify the various grading systems:

Grading System Final grade calculation
Points Sum of the points from each grade object.
Weighted Weighted sum of the points from each grade object.
Formula Determined by custom formula.
Points and Weighted

The points method simply sums up the raw points of each grade object (for example, test one worth 10 points and test two worth 15 points produces a sum of 15 points towards the final grade).

The weighted method treats each grade object as a percentage of the final grade (so, test one could comprise 30% of the final grade, and test two could comprise 15% of the final grade: together, they account for 45% of the final grade).

Formula
The calculation of the final grade gets done according to a custom formula, and all the grade items and categories use the Points method within this formula.
Grade.GradeObject

A grade object describes a single point of assessment for an org unit, containing the parameters within which participants will get assessed. The framework supports the creation of four different types of GradeObjects, each with slightly different properties.

Providing grade object data blocks. The following blocks demonstrate what the framework API returns to callers. When you must provide grade object data blocks into the framework API, abide by these restrictions:

  • Do not provide an Id field.

  • The CategoryId field should contain a valid category ID value for an existing grade category, or a value of 0.

  • The Description field should use the RichTextInput field type, and not the RichText type sent back on output by the service.

  • The GradeScheme field for numeric or pass-fail grade objects should match an existing grade scheme ID for the org unit, but can be null if the grade object has no associated scheme.

    The GradeScheme field for select-box grade objects must have an associated scheme ID; it cannot be null for select-box grade objects.

  • The MaxPoints field (for grade objects that have one) must have a value that ranges between 0.01 and 9999999999.

  • The Name field must not be the same as any current grade object in the org unit’s gradebook.

    The Name field may not contain any of these characters: / ” * < > + = | , %

    Both the Name and ShortName field must be 128 unicode characters or fewer in length.

Default Category ID values. When the service provides you with a grade object block, it may provide you with a CategoryId value of 0 if the grade object has no associated grade category, instead of providing you with null – you should be able to cope with receiving both values, and recognize that in either case, the grade object has no associated category (do not attmept to fetch a grade category with a category ID of 0, as one won’t be findable: this is also true of the call to retrieve all grade categories).

Numeric. Numeric grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "CanExceedMaxPoints": <boolean>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>|null,
    "Id": <number:D2LID>,  // not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "Numeric",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "GradeSchemeUrl": <string:APIURL>,  // not on input actions
    "ActivityId": <string:D2LID>|null,  // not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null
}
GradeSchemeUrl
Appears in LE’s 1.9 contract as of LE v10.5.5. Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.
ActivityId
Appears in LE’s unstable contract as of LE v10.5.7. The identifier used when referencing the grade object as a generic learning activity. Intended for future use.
AssociatedTool
Appears in LE’s 1.11 contract. Describes the tool object associated with this grade object.

PassFail. Pass-fail grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>|null,
    "Id": <number:D2LID>,  // not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "PassFail",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "GradeSchemeUrl": <string:APIURL>,  // not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null
}
GradeSchemeUrl
Appears in LE’s 1.9 contract as of LE v10.5.5. Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.
AssociatedTool
Appears in LE’s 1.11 contract. Describes the tool object associated with this grade object.

SelectBox. Select-box grade objects look like this:

{
    "MaxPoints": <number:decimal>,
    "IsBonus": <boolean>,
    "ExcludeFromFinalGradeCalculation": <boolean>,
    "GradeSchemeId": <number:D2LID>,  // must not be null on input actions
    "Id": <number:D2LID>,  // not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "SelectBox",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "GradeSchemeUrl": <string:APIURL>,  // not on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null
}
GradeSchemeUrl
Appears in LE’s 1.9 contract as of LE v10.5.5. Contains the URL for an API action to retrieve the grade scheme associated with the grade object. Retrieving this URL will return a GradeScheme object.
AssociatedTool
Appears in LE’s 1.11 contract. Describes the tool object associated with this grade object.

Text. Text grade objects look like this:

{
    "Id": <number:D2LID>,  // not on input actions
    "Name": <string>,
    "ShortName": <string>,
    "GradeType": "Text",
    "CategoryId": <number:D2LID>|null,
    "Description": { <composite:RichText> },  // { <composite:RichTextInput> } on input actions
    "AssociatedTool": { <composite:AssociatedTool> }|null
}
AssociatedTool
Appears in LE’s 1.11 contract. Describes the tool object associated with this grade object.
Grade.AssociatedTool

Included in grade objects to indicate the underlying tool and tool item associated with the grade object.

{
    "ToolId": <number:D2LID>,
    "ToolItemId": <number:D2LID>
}

Grade categories

Grade.GradeObjectCategory

This data block contains a GradeObjectCategoryData block while adding an Id field and a Grades array field:

{
    "Id": <number:D2LID>,
    "Grades": [ <Grade.GradeObject>, ... ],
    "Name": <string>,
    "ShortName": <string>,
    "CanExceedMax": <boolean>,
    "ExcludeFromFinalGrade": <boolean>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "Weight": <number:decimal>|null,
    "MaxPoints": <number:decimal>|null,
    "AutoPoints": <boolean>|null,
    "WeightDistributionType": <number>|null,
    "NumberOfHighestToDrop": <number>|null,
    "NumberOfLowestToDrop": <number>|null
}
Grade.GradeObjectCategoryData

This data block contains all the fundamental values for a generic grade object category.

{
    "Name": <string>,
    "ShortName": <string>,
    "CanExceedMax": <boolean>,
    "ExcludeFromFinalGrade": <boolean>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "Weight": <number:decimal>|null,
    "MaxPoints": <number:decimal>|null,
    "AutoPoints": <boolean>|null,
    "WeightDistributionType": <number>|null,
    "NumberOfHighestToDrop": <number>|null,
    "NumberOfLowestToDrop": <number>|null
}

Grade schemes

Grade.GradeScheme
{
    "Id": <number:D2LID>,
    "Name": <string>,
    "ShortName": <string>,
    "Ranges": [ // Array of GradeSchemeRange blocks
        {
            "PercentStart": <number:decimal>,
            "Symbol": <string>,
            "AssignedValue": <number:decimal>|null,
            "Colour": <string>
        },
        { <composite:GradeSchemeRange> }, ...
    ]
}

Grade values

Grade.GradeValue

The framework can provide grade values slightly differently depending upon whether the underlying grade object type is a computable value, or not (basically, only Text (4) grade types are not computable).

Basic. All grade values will share at least these properties:

{
    "DisplayedGrade": <string>,
    "GradeObjectIdentifier": <string:D2LID>,
    "GradeObjectName": <string>,
    "GradeObjectType": <number:GRADEOBJ_T>,
    "GradeObjectTypeName": <string>|null,
    "Comments": <composite:RichText>,  // Added with LE v1.13 API
    "PrivateComments": <composite:RichText>  // Added with LE v1.13 API
}

Computable. Computable grade values can have additional properties; computable value structures have all the basic properties, and also add these:

{
    "PointsNumerator": <number>|null,
    "PointsDenominator": <number>|null,
    "WeightedDenominator": <number>|null,
    "WeightedNumerator": <number>|null
}

Note

Nullable grade values for these fields in the computable grade value structures indicate (when null) a default grade value state before a grade value has actually been assessed.

Grade.UserGradeValue

Contains a User and a GradeValue.

{
   "User": { <composite:User> },
   "GradeValue": { <composite:GradeValue> }|null
}
GradeValue
If the user currently has no grade value set, this will be null.
Grade.IncomingGradeValue

As with grade objects, the framework handles incoming grade values slightly differently depending upon the grade object type associated with the grade value (these APIs support incoming grade values for the first four grade object types).

Basic. All incoming grade value structures share at least these common properties:

{
    "Comments": <composite:RichTextInput>,  // added with LE v1.13 API
    "PrivateComments": <composite:RichTextInput>,  // added with LE v1.13 API
}

You should provide the basic properties that are appropriate to the API version level you’re using (for example, if you’re using the v1.14 APIs, use all the basic properties introduced with that version and older, such as, v1.13, v1.12, and so on).

Comments and PrivateComments

Note that both these properties use the RichTextInput structure for incoming grade values.

With LE v1.13 of the API and later, you should include these properties with incoming grade value structures of all types, and leave the comment text as an empty string if you intend to have no comment or privately-visible comment associated with the grade value.

With older versions of the API, you should not include these two properties at all in incoming grade value structures.

Grade values have additional properties depending on their type.

Numeric. When providing numeric grade values grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // appropriate basic common properties here
    "GradeObjectType": 1,
    "PointsNumerator": <number:decimal>
}

PassFail. When providing pass-fail grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // appropriate basic common properties here
    "GradeObjectType": 2,
    "Pass": <boolean>
}

SelectBox. When providing select-box grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // appropriate basic common properties here
    "GradeObjectType": 3,
    "Value": <string>
}

Text. When providing text grade values, you should make a JSON block that includes both the basic common properties appropriate for your API contract version and these additional properties:

{
    // appropriate basic common properties here
    "GradeObjectType": 4,
    "Text": <string>
}
Grade.IncomingFinalAdjustedGradeValue

If you use the API to provide a final adjusted grade value for a user, then use a block like this:

{
    "PointsNumerator": <number:decimal>,
    "PointsDenominator": <number:decimal>
}

Course completion

Grade.CourseCompletion
{
    "OrgUnitId": <number:D2LID>,
    "CompletionId": <number:D2LID>,
    "UserId": <number:D2LID>,
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
Grade.CourseCompletionCreationData
{
    "UserId": <number:D2LID>,
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
ExpiryDate
Course created with an expiry date if this property is not null.
Grade.CourseCompletionUpdateData
{
    "CompletedDate": <string:UTCDateTime>,
    "ExpiryDate": <string:UTCDateTime>|null
}
ExpiryDate
Course adjusted to have an expiry date if this property is not null.

Grade Statistics

Grade.GradeStatisticsInfo
{
    "OrgUnitId": <number:D2LID>,
    "GradeObjectId": <number:D2LID>,
    "Minimum": <number:decimal>|null,
    "Maximum": <number:decimal>|null,
    "Average": <number:decimal>|null,
    "Mode": [ <number:decimal>, ... ],
    "Median": <number:decimal>|null,
    "StandardDeviation": <number:decimal>|null,
}

Grade Setup

Grade.GradeSetupInfo
{
    "GradingSystem": <string:GRADINGSYSTEM_T>,
    "IsNullGradeZero": <boolean>,
    "DefaultGradeSchemeId": <number:D2LID>
}

Actions

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Delete a specific grade object for a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectID (D2LID) – Grade object ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
GET /d2l/api/le/(version)/(orgUnitId)/grades/

Retrieve all the current grade objects for a particular org unit.

Parameters:
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a JSON array of GradeObject blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Retrieve a specific grade object for a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeObject JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/grades/

Create a new grade object for a particular org unit.

Parameters:
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded: the return body contains the parsed grade object data.
  • 400 Bad Request – Bad request: you have posted invalid data, the return body may contain further detail.
  • 403 Forbidden – No permission to manage grades.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Input. This action expects a grade object of one of the first four grade object types.

Note

Your posted grade object must have a unique Name property.

Return. This action returns a GradeObject JSON block for the grade object that the service just created, so you can quickly retrieve the grade object ID.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)

Update a specific grade object.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID.
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded: the return body contains updated grade object data.
  • 400 Bad Request – Bad request: you provided invalid data; the return body may contain further detail.
  • 403 Forbidden – No permission to manage grade objects.
  • 404 Not Found – No such grade object, or no such org unit.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Input. This action expects a grade object of one of the first four grade object types. Note that your provided block’s data replaces all the associated grade object’s data on the service.

Note

If you update the Name property for your grade object, the new name should be unique.

Return. This action returns a GradeObject JSON block for the grade object that the service just updated.

Grade categories

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/categories/(categoryId)

Delete a specific grade category for a provided org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • categoryId (D2LID) – Grade category ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
GET /d2l/api/le/(version)/(orgUnitId)/grades/categories/

Retrieve a list of all grade categories for a provided org unit.

Parameters:
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action retrieves a JSON array of GradeObjectCategory blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/categories/(categoryId)

Retrieve a specific grade category for a provided org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • categoryId (D2LID) – Grade category ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action retrieves a GradeObjectCategory JSON block.

POST /d2l/api/le/(version)/(orgUnitId)/grades/categories/

Create a new grade category for a provided org unit.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns the newly created grade object category in a GradeObjectCategory JSON block, so that you can quickly gather its grade category ID.

Grade schemes

GET /d2l/api/le/(version)/(orgUnitId)/grades/schemes/

Retrieve all the grade schemes for a provided org unit.

Parameters:
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a JSON array of GradeScheme blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/schemes/(gradeSchemeId)

Retrieve a particular grade scheme.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeSchemeId (D2LID) – Grade scheme ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeScheme JSON block.

Grade values

Default grade values. Each user can have a grade value associated with each grade object. If you try to retrieve a computable grade value for a user for whom a grade has not been set, the API may return a “default” grade value object instead of a 404. In this case, the computable properties for the grade value that the LMS has not yet been able to calculate (the numerator and denominator properties for the grade value) will be set to null, and you should be prepared to handle such values.

Final grade values. Note that final grade values can be managed before being released. If the calling user has permission to see grades but not to manage them, they may not get a value back when calling the final grade actions if the grades have not yet been released. Calling users that can manage grades, however, can use the final grade actions to retrieve final grade values before release, provided some value has been set for them. The kind of value the back-end service returns depends upon how the org unit’s gradebook has been configured to provide final grades (whether to release the final grades as calculated, or as adjusted).

GET /d2l/api/le/(version)/(orgUnitId)/grades/final/values/myGradeValue

Retrieve the final grade value for the current user context.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – Current user context has no permission to see grade values.
  • 404 Not Found – No final grade found for current user in org unit, or no org unit found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeValue JSON block containing the final calculated grade value for the current user context.

GET /d2l/api/le/(version)/(orgUnitId)/grades/final/values/(userId)

Retrieve the final grade value for a particular user.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • userId (D2LID) – User ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see grade values.
  • 404 Not Found – No final grade found for provided user in org unit, or no user found, or no org unit found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeValue JSON block containing the final calcualted grade value for the provided user.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/

Retrieve each user’s grade value for a particular grade object.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID.
Query Parameters:
 
  • sort (string) – Optional. Sort by firstname, lastname, or grade value (see description).
  • pageSize (number) – Optional. Number of objects to return in each data page (see description).
  • isGraded (boolean) – Optional. Filter to graded or not graded users (see description).
  • searchText (string) – Optional. Show only users that match this string inside first and last names.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid page size provided, or grade object is an unsupported type (see description).
  • 403 Forbidden – No permission to see grade values.
  • 404 Not Found – No grade object found in org unit, or org unit not found.
API Versions:
  • 1.8+ – Route first appears in LMS v10.5.4.

Input. This action can take a number of optional sort and filter parameters:

isGraded

If you do not provide an isGraded query parameter, this action fetches back a list of all users to whom the grade object applies, whether they have yet been graded or not.

If you provide true for this parameter, the action filters the list to show only graded users; if you provide false for this parameter, the action filters the list to show only ungraded users.

sort

You can control the sorting key field, and the direction of the sort, by using the key name in combination with a minus sign (to make the sort descending instead of ascending). Thus, to do an ascending sort by graded user’s first name you use ?sort=firstname; to do a descending sort by grade value, you use ?sort=-grade.

If you don’t provide the parameter, this action behaves as if you had provided ?sort=lastname (ascending sort by graded user’s last name).

You can also request an adjustment to the size of the data pages retrieved with this action: by default, the data pages will contain at most 20 items; you can use the pageSize query parameter to request up to 200 items per page.

Return. This action returns an ObjectListPage JSON block containing a list of user grade values for your provided grade object.

Note

Valid grade object types. Valid grade object types for this route are Numeric, PassFail and SelectBox. If this route is called with a grade object of any other type, a 400 status code will be returned.

Sorting and searching. When searching and/or sorting you are subject to user privacy controls. If you try to sort by last name or first name, and your calling user context does not have permission to see the relevant field, then this action falls back to sorting by grade.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/(userId)

Retrieve a specific grade value for a particular user assigned in an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID.
  • userId (D2LID) – User ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see grade values.
  • 404 Not Found – No grade found for provided user in org unit, or no grade object, user, or org unit found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeValue JSON block.

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/myGradeValue

Retrieve a specific grade value for the current user context assigned in a particular org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – Current user context has no permission to see grade values.
  • 404 Not Found – No grade found for current user in org unit, or no grade object found, or no org unit not found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a GradeValue JSON block.

GET /d2l/api/le/(version)/(orgUnitId)/grades/values/myGradeValues/

Retrieve all the grade objects for the current user context assigned in a particular org unit.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – Current user context has no permission to see grade values.
  • 404 Not Found – No grades found for current user context in org unit, or no org unit not found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a JSON array of GradeValue blocks.

GET /d2l/api/le/(version)/(orgUnitId)/grades/values/(userId)/

Retrieve all the grade objects for a particular user assigned in an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • userId (D2LID) – User ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see grades.
  • 404 Not Found – No grades found for provided user in org unit, or no user found, or no org unit found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a JSON array of GradeValue blocks.

POST /d2l/api/le/(version)/(orgUnitId)/grades/final/calculated/(userId)

Recalculate final grade value for provided user in org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • userId (D2LID) – User ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
POST /d2l/api/le/(version)/(orgUnitId)/grades/final/calculated/all

Recalculate all final grade values for provided org unit.

Parameters:
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
PUT /d2l/api/le/(version)/(orgUnitId)/grades/final/values/(userId)

Set the adjusted final grade value for provided user in org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • userId (D2LID) – User ID.
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
PUT /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/values/(userId)

Provide a specific grade value for a particular user.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId (D2LID) – Grade object ID
  • userId (D2LID) – User ID.
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Mismatch between provided incoming grade value type and grade object type.
  • 403 Forbidden – No permission to see or manage grades.
  • 404 Not Found – No such user in org unit, or no grade object found, or no org unit found.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Input. This action expects an IncomingGradeValue aligned with one of the first four grade object types.

Course completion

DELETE /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/(completionId)

Delete a course completion.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • completionId (D2LID) – Completion ID.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.
GET /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/

Retrieve all the course completion records for an org unit.

Parameters:
Query Parameters:
 
  • userId (D2LID) – Optional. User ID.
  • startExpiry (UTCDateTime) – Optional. Start of expiration range to query.
  • endExpiry (UTCDateTime) – Optional. End of expirtation range to query.
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
  • 200 OK – Action succeeded.
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Input. You can limit the scope of this query by providing an optional start and/or end date to clamp the search. You can also limit the scope of this query by providing an optional User ID (to fetch only course completions for that user within the org unit).

You can also use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting CourseCompletion data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

GET /d2l/api/le/(version)/grades/courseCompletion/(userId)/

Retrieve all the course completion records for a user.

Parameters:
Query Parameters:
 
  • startExpiry (UTCDateTime) – Optional. Start of expiration range to query.
  • endExpiry (UTCDateTime) – Optional. End of expirtation range to query.
  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Input. You can limit the scope of this query by providing an optional start and/or end date to clamp the search.

You can also use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting CourseCompletion data blocks for the segment following your bookmark parameter (or the first segment if the parameter is empty or missing).

POST /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/

Create a new course completion for an org unit.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a CourseCompletion JSON block with the newly created course completion record.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/courseCompletion/(completionId)

Update an existing course completion.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • completionId (D2LID) – Completion ID.
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.5+ – Route first appears in LMS v10.4.3.
  • 1.4Deprecated as of LMS v10.5.6.
  • 1.3-Obsolete as of LMS v10.4.7.

Return. This action returns a CourseCompletion JSON block with the updated course completion record.

Grade statistics

GET /d2l/api/le/(version)/(orgUnitId)/grades/(gradeObjectId)/statistics

Get statistics for a specified grade item.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • gradeObjectId – Grade object ID.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.5.5.

Return. This action returns a GradeStatisticsInfo JSON block.

Grade setup

GET /d2l/api/le/(version)/(orgUnitId)/grades/setup/

Retrieve the grades configuration for the org unit.

Parameters:
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.

Return. This action returns a GradeSetupInfo JSON block.

PUT /d2l/api/le/(version)/(orgUnitId)/grades/setup/

Update the grades configuration for the org unit.

Parameters:
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.

Input. This action expects a GradeSetupInfo JSON block.

Return. This action returns a GradeSetupInfo JSON block.

«  Dropboxes (Folders, categories, submissions, feedback)   ·  [   home  ·   reference  ·   community   ·  index   ·  routing table   ·  modules   ]   ·  Course content (content objects, ISBNs, tables of content)  »