Incoming REST Specifications
Grades Journey v2 can provision gradebook data using REST APIs. Though these APIs are different than the core Learn APIs, the Grades Journey v2 API authentication follows the same OAuth2 authentication process as the core Learn REST API. This requires a REST API application setup on the Anthology Developer Portal.
Create Grading Schema
Web service endpoint
https://{{hostname}}/learn/api/v2/cc/gradejourney/gradeSchemasAPI
Example JSON Body
[
{
"title": "Pass-Fail-Custom-Schema",
"symbols": "P=80:F=0",
"optionalData": "sisSchemaID=PF"
}
]Grading Schema Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
title | Title of the grading Schema. | yes | String (333 chars) |
symbols | Symbols in a list with an optional lower bound. | yes | String (2000 chars) |
optionalData | Key/value pairs with each set of pairs separated by a colon, and key/values separated by an equal sign. For example: key1=value1:key2=value2 | no | String (2000 chars) |
Example Response
[
{
"courseId": "",
"name": "Pass-Fail-Custom-Schema",
"status": "OK",
"message": "Grade schema successfully created"
}
]Create Gradable Items and Grade Columns
Web service endpoint
https://{{hostname}}/learn/api/v2/cc/gradejourney/gradableItemsAPI
Example JSON Body
[
{
"courseId": "course1",
"name": "Final Grade",
"itemType": "MANUAL_COLUMN",
"instructions": ""
"anonymous": false,
"group": false,
"contentAreaName": "Assignments",
"available": true,
"attempts": 1,
"tracked": false,
"startDate":
"endDate":
"dueDate": "",
"points": 100,
"gradeSchema": "Pass-Fail-Custom-Schema",
"sequenceNum": 1,
"extract": true,
"mapping": "",
"optionalData": "SIS_ID=FG123456",
}
]Gradable Items and Grade Columns Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
courseId | Batch_uid identifying the course to which this gradable item or grade column applies. | yes | String (256 chars) |
name | Title of the gradable item. | yes | String (333 chars) |
itemType | Type of gradable item to create. Possible values: *ASSIGNMENT, *TEST, SURVEY, DISCUSSION_BOARD, WIKI, BLOG, JOURNAL, SELF_AND_PEER_TEST, *MANUAL_COLUMN, *WEIGHTED_COLUMN, TOTAL_COLUMN *Ultra and Original courses. All others Original courses only. | yes | String (333 chars) |
instructions | Instructions for the gradable item. | no | String (2000 chars) |
anonymous | If true, the Assignment or Test will be created with Anonymous Grading enabled. For Ultra Courses Anonymous Grading requires a dueDate be set on the item. | no | Boolean (Default false) |
group | If true, the assignment will be created as Assignment Type Group Submission. | no | Boolean (Default false) |
contentAreaName | Location the gradable item will be created. Can be used in Ultra courses to provision a subfolder and put content in the subfolder. The value has the format "parent@>@child" where "parent" is the name of the top-level (parent) folder and "child" is the name of the subfolder. If the subfolder already exists, the assignment will be added to the existing subfolder. If the subfolder does not exist, it will be created in the parent folder. | no | String (255 chars) |
available | Determines if the item is visible to students. | no | Boolean (Default false) |
color | Color of the gradable item link in an Original course. Color name or hex value. Original courses only. | no | String (10 chars) |
attempts | Number of attempts allowed for the Test or Assignment. | no | Int (Default –1 for unlimited) |
tracked | Determines if statistics tracking is enabled for the gradable item. Does not apply to grade columns. Original courses only. | no | Boolean (Default false) |
startDate | Display from date. | no | Date |
endDate | Display until date. | no | Date |
dueDate | Due date of the Gradable item. | no | Date |
points | Points Possible. | no | Float (Default 100.0) |
gradeschema | Grade schema name as it exists in Learn. Note that this schema may have been created using the web service as available from Grade Export or in Blackboard Learn | no | String (333 chars) |
sequenceNum | Content area sequence display order number. Original courses only. | no | Int |
extract | True/false – If true, this column will be extracted from the extraction tool. Only applies when Grades Journey has Provision Enabled on Outgoing Settings page. | no | String (333 chars) |
mapping | For a weighted column, specify the mappings. The default is no mapping, which requires the mapping to be performed manually directly in Learn. This will be the gradable item name/percentage pairs, separated by a comma, where the percentages total 100. Example: Assignment 1=30,Test 1=30,Test 2=40. For a Total column, specify just the columns that should be included in the total. For example, Assignment 1, Test 1, Assignment 2, Final Grade | no | String (333 chars) |
optionalData | Key/value pairs with each set of pairs separated by a colon, and key/values separated by an equal sign. For example: key1=value1:key2=value2 | no | String (2000 chars) |
Example Response
[
{
"status": "OK",
"message": "Gradecolumn successfully created",
"courseId": "course1",
"name": "Final Grade"
}
]Delete Grade Columns
Web service endpoint
https://{{hostname}}//learn/api/v2/cc/gradejourney/gradeColumnDeleteAPI
Example JSON Body
[
{
"courseId": "course1",
"name": "Final Grade"
}
]Grade Column Delete Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
courseId | The course batch_uid. | yes | String (333 chars) |
name | The name of the column to be deleted. | yes | String (333 chars) |
Example Response
[
{
"status": "OK",
"message": "Grade column successfully deleted",
"courseId": "TG-TEST-ORIG",
"name": "Delete Column"
}
]Set the External Grade
(only available for Original courses)
Web service endpoint
https://{{hostname}}/learn/api/v2/cc/gradejourney/externalGradeColumnAPI
Example JSON Body
[
{
"courseId": "course1",
"name": "Final Grade"
}
]External Grade Column Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
courseId | The course batch_uid. | yes | String (333 chars) |
name | The name of the column to be set as the External Grade. | yes | String (333 chars) |
Example Response
[
{
"status": "OK",
"message": "External grade column successfully updated",
"courseId": "course1",
"name": "Final Grade"
}
]Create Enrollment Metadata
Web service endpoint
https://{{hostname}}/learn/api/v2/cc/gradejourney/userMetadataAPI
Example JSON Body
[
{
"courseId": "course1",
"userId": "student1",
"optionalData": "EnrollType=LetterGrade"
},
{
"courseId": "course1",
"userId": "student2",
"optionalData": "EnrollType=Audit"
}
]Enrollment Metadata Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
courseId | The course batch_uid. | yes | String (333 chars) |
userId | The user batch_uid. | yes | String (333 chars) |
optionalData | Key/value pairs with each set of pairs separated by a colon, and key/values separated by an equal sign. For example: key1=value1:key2=value2 | no | String (2000 chars) |
Example Response
[
{
"status": "OK",
"message": "User metadata successfully created",
"courseId": "course01",
"name": "student01"
},
{
"status": "OK",
"message": "User metadata successfully created",
"courseId": "course02",
"name": "student02"
}
]Update Grade Value
Web service endpoint
https://{{hostname}}/learn/api/v2/cc/gradejourney/gradeValueAPI
Example JSON Body
[
{
"courseId": "course001",
"userId": "user1",
"name": "FINAL GRADE",
"value": "B"
}
] Grade Value Update Element Definitions
Element name | Description | Required | Type and Max Size |
|---|---|---|---|
courseId | The course batch_uid. | yes | String (333 chars) |
userId | The user batch_uid. | yes | String (333 chars) |
name | The column whose value to be updated. | yes | String (333 chars) |
value | The grade value to update to. | yes | String (333 chars) |
Example Response
[
{
"status": "OK",
"message": "Grade value successfully added",
"courseId": "course1",
"name": "Final Grade"
}
]