Pearson
Always Learning

Overview

When a teacher grades an item, LearningStudio sends this event to tell you a new grade exists for a user. 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.created

What Triggers This Event

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

  • Grades for Gradebook Items by Course

    • POST /courses/{courseId}/gradebookItems/{gradebookItemId}/grades
    • POST /courses/{courseId}/ gradebook/gradebookItems/{gradebookItemId}/grades
  • Grades for Gradebook Items by User

    • POST /users/{userId}/courses/{courseId}/ gradebookItems/{gradebookItemId}/grades
    • POST /users/{userId}/courses/{courseId}/ gradebook/gradebookItems/{gradebookItemId}/grades

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": {pointsAchieved},
    "gradableitempointspossible": {pointsPossible},
  },
  "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). Sample Format:
YYYY-MM-DDTHH:MM:SS.SSSZ.
{eventType} Event type of the event object. This will be the same for all events of this type.
pearson.ls.gradebook.
↳ grade.created
{objectId} Unique object ID for the specific event contract data.
pearson.ls.gradebook.
↳ grade_{gradeId}
{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 user for the gradebook item.  
{pointsAchieved} Grade points awarded to user for the gradebook item. Float number type, may be up to two decimal places.
{pointsPossible} Grade points that were possible for the gradebook item. Float number type, may be up to two decimal places.
{actorId} LearningStudio user ID of user who is associated with the grade.  
{actorType} Type of user who is associated with the grade.  
{firstName} First name of 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 course ID that contained the gradebook item where the grade was created.  
{courseTitle} Title of the course that contained the gradebook item where the grade was created.  
{displayCourseCode} Display code for the course that contained the gradebook item where the grade was created.  
{courseCallNumbers} Array of institution's call numbers assigned to the course that contained the announcement whose read status was updated. 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

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