Pearson
Always Learning

Overview

When a teacher changes a grade on an item, LearningStudio sends this event to tell you an existing grade has been updated. You can use the APIs to find out more about the gradebook category, related content item, or grade detail.

Message Type ID

Use this message type id to subscribe to this event and identify incoming instances of it:

pearson.ls.gradebook.grade.updated

What Triggers This Event

This event is triggered by updating a grade in the LearningStudio User Interface, or via API calls that do the same action, including:

  • Grades for Gradebook Items by Course
    • PUT courses/{courseId}/ gradebookItems/{gradebookItemId}/grades/{gradeId}
    • PUT courses/{courseId}/ gradebook/gradebookItems/{gradebookItemId}/grades/{gradeId}
  • Grades for Gradebook Items by User
    • PUT users/{userId}/courses/{courseId}/ gradebookItems/{gradebookItemId}/grades/{gradeId}
    • PUT users/{userId}/courses/{courseId}/ gradebook/gradebookItems/{gradebookItemId}/grades/{gradeId}

See Grades for the resources, use cases, and concepts for the Grades API resources.

Event Payload

Here is the structure of the event's payload. Text directly surrounded by curly brackets (e.g., {eventId}) are parameters that are defined in the table below.

{
  "eventId": "{eventId}",
  "eventDate": "{eventDate}",
  "eventType": "{eventType}",
  "object": {
    "id": "{objectId}",
    "type": "{parentEventType}",
    "gradeid": {gradebookItemID},
    "usergrade": {UserGrade},
    "gradepointsachieved": {GradePointsAchieved},
    "gradableitempointspossible": {GradableItemPointsPossible},
  },
  "actor": {
    "id": "{actorId}",
    "type": "{actorType}",
    "firstName": "{FirstName}",
    "lastName": "{LastName}",
    "emailAddress": "{EmailAddress}"
    "userName": "{Username}"
  },
  "contexts": {
    "course": {
      "id": "{courseId}",
      "title": "{courseTitle}",
      "displayCourseCode": "{displayCourseCode}"
      "callNumbers": [{courseCallNumbers}],
      "nodes": ["{courseNode}"]
    }   
    "ep": {
      "id": "{epId}",
      "clientString": "{clientString}"
    }
  }
}

Event Payload Parameter Descriptions

Name Description Valid Values
{eventId} Unique ID assigned to the specific event.
{eventDate} Date and time when the event was published to the eventing message queue. Time is in UTC (no timezone offset). Format is
YYYY-MM-DDTHH:MM:SS.SSSZ
.
{eventType} Event type of the event object.
pearson.ls.gradebook.
↳ grade.updated
{objectId} Unique object ID for the specific event contract data.
pearson.ls.gradebook.
↳ grade_
↳ {objectGradeId}
.
{parentEventType} An ID that represents the category of events, less specific than this event message type.
pearson.ls.gradebook.
↳ grade
{gradebookItemID} Gradebook Item ID for which this grade is recorded. You can use this to retrieve more information about the grade category or the grade itself.
{UserGrade} Letter grade awarded to the user for the gradebook item.
{GradePointsAchieved} Grade points awarded to the user for the gradebook item. Float number type, may be up to two decimal places.
{GradableItemPointsPossible} Grade points that were possible for the gradebook item. Float number type, may be up to two decimal places.
{actorId} LearningStudio user ID of the user who is associated with the grade.
{actorType} Type of user who is associated with the grade.
{FirstName} First name of the user who is associated with the grade.
{LastName} Last name of the user who is associated with the grade.
{EmailAddress} Email address of the user who is associated with the grade.
{Username} LearningStudio username (login ID) of the user who is associated with the grade.
{courseId} LearningStudio ID of the course where the grade exists.
{courseTitle} Title of the course where the grade exists.
{courseDisplayCourseCode} Display code for the course where the grade exists.
{courseCallNumbers} Array of instituion's call numbers assigned to the course where the grade exists. Zero or more IDs written as strings.
{courseNode} Array of IDs of the nodes for which this course is associated. Zero or more IDs written as strings.
{epId} The numeric ID of the institution (the LearningStudio campus or instance).
{clientString} The institution's client string (primary identifier for campuses).

Example

{
  "eventId": "970d11ac-1234-46d6-b028-10b94186ed7e",
  "eventDate": "2013-07-03T21:06:41.800Z",
  "eventType": "pearson.ls.gradebook.grade.updated",
  "object": {
    "id": "pearson.ls.gradebook.grade_70018",
    "type": "pearson.ls.gradebook.grade",
    "gradeid": 804c6114-dd97-1234-a2dc-306f70c605bf,
    "usergrade": “B”,
    "gradepointsachieved": “88.00”,
    "gradableitempointspossible": “100.00”,
  },
  "actor": {
    "id": "9876543",
    "type": "user",
    "firstName": "John",
    "lastName": "Smith",
    "emailAddress": "jsmith1@domain.com",
    "userName": "johnsmith1"
  },
  "contexts": {
    "course": {
      "id": "2022425",
      "title": "GB Course",
      "displayCourseCode": "GBC",
      "callNumbers": ["123456","456789"],
      "nodes": ["epsamplestring234"]
    },  
    "ep": {
      "id": "456789",
      "clientString": "epsamplestring"
 
    }
  }
}
3031 reads
Always Learning
Pearson