Assignments and grade services (AGS) is an LTI extension. LTI 1.3 is designed to handle advanced grade interactions between a tool and a platform. It enables developers with a series of sub-services that allow the management of grade objects and values inside Brightspace.
The Assignments and grade services (AGS) comprises three services:
- LineItem Service
- Result Service
- Score Service
LineItem Service
The LineItem Service is used to manage the grade items for learning tools. It enables a tool to create, delete, and get details of grade items that the tool itself owns. This service offers the following capabilities:
- LineItems.url: The endpoint URL for accessing the LineItem container for the current context.
- LineItem.url: The endpoint URL for accessing the line item when there is only one line item associated with the resource link; If there is more than one line item, this property must be blank.
There are different defined media types by the LineItem Service:
-
application/vnd.ims.lis.v2.lineitem+json, with a sample:
{
"id" : https://lms.example.com/context/2923/lineitems/1,
"scoreMaximum" : 60,
"label" : "Math 202 Quiz",
"resourceId" : "a-9334df-33",
"tag" : "grade",
"resourceLinkId" : "1g3k4dlk49fk",
"startDateTime": "2019-03-06T20:05:02Z",
"endDateTime": "2019-04-06T22:05:03Z"
}
- application/vnd.ims.lis.v2.lineitemcontainer+json, with a sample:
[{
"id": "https://lms.example.com/context/2923/lineitems/1",
"scoreMaximum": 60,
"label": "Math 202 Quiz",
"resourceId": "a-9334df-33",
"tag": "grade",
"resourceLinkId": "1g3k4dlk49fk",
"endDateTime": "2019-04-06T22:05:03Z"},
{
"id": "https://lms.example.com/context/2923/lineitems/47",
"scoreMaximum": 100,
"label": "Week 3 Assignment",
"resourceId": "a-9334df-33",
"tag": "originality",
"resourceLinkId": "1g3k4dlk49fk"
},
{"id": "https://lms.example.com/context/2923/lineitems/69",
"scoreMaximum": 60,
"label": "Week 4 Assignment",
"tag": "grade"
}]
When trying a GET request to the container endpoint, you may want to filter the following results:
- resource_link_id: Return only those items associated with the specified tool platform's resource ID for the link in content.
- resource_id: Return those only those items associated with the specified tool resource identifier. Multiple line items can share the same resourceId within a context.
- tag: Return only those items associated with the specified tag. Always a string.
- limit: Restrict the number of line items returned. If more items exist following the returned ones, a 'Link' http header with a URL pointing to the next page and a 'rel' value of 'next' MUST be included in the response. D2L limits GET calls to 200.
Sample of a new line item
To create a new grade item
You must POST to application/vnd.ims.lis.v2.lineitem to the LineItems.url. It can appear as follows:
{
"scoreMaximum" : 60,
"label" : "Math 101 Quiz",
"resourceId" : "quiz-2031",
"tag" : "math",
"startDateTime": "2019-07-07T20:05:02Z",
"endDateTime": "2019-07-07T22:05:03Z",
}
Result Service
The Result service allows users to make tool query the platform for the current values of grade objects it owns. The term result itself represents a current grade for a given object or for a particular user. To sync new grades, see the Score Service section of this topic.
Note: A result cannot be directly altered through this service, so only GET commands are supported.
The service endpoint is a subpath of the line item resource URL. The resource URL has the path appended with '/results'. This service only supports GET operations and returns all the results for the line item. For example:[{
"id": "https://lms.example.com/context/2923/lineitems/1/results/5323497",
"scoreOf": "https://lms.example.com/context/2923/lineitems/1",
"userId": "5323497",
"resultScore": 0.83,
"resultMaximum": 1,
"comment": "This is exceptional work."
}]Tools can filter these results using the following query parameters:
- user_id: Filter the results to a single user based on their ID.
- limit: Restrict the number of results returned. D2L limits results to 200.
Score Service
A score represents the value of an activity that a user just completed. The term score refers to that value at the time the activity was taken. The Score Service is used by a tool to publish the latest score to Brightspace. Because Brightspace only posts new scores, this service is write-only. When accessed later, D2L accesses it as a result using the result service, which is read only.
There is only one media type defined by this service: application/vnd.ims.lis.v1.score+json. The follow is how a sample result might appear:
{"timestamp": "2017-04-16T18:54:36.736+00:00",
"scoreGiven" : 83,
"scoreMaximum" : 100,
"comment" : "This is exceptional work.",
"activityProgress" : "Completed",
"gradingProgress": "FullyGraded",
"userId" : "5323497"
>}
Timestamp is a mandatory value indicating when the score is changed and is intended to be used by the platform to guard against out of order score updates. The timestamp value is an ISO 8601 date time of the server time when the score state is modified. To protect data historically, this value is expected to increase with each request.
Activity Progress denotes the status of a specific activity at that point in time. While IMS documents several available values, Brightspace ignores these values and instead only relies on Grading Progress status value.
Final grades
The field grading progress has many available values, as documented by 1EdTech. However, Brightspace currently only recognizes the FullyGraded value: the grading process is completed; the score value, if any, represents the current Final Grade. See the details of Grading Progress in the official IMS documentation.
When checked, grades created through AGS are included in the final grade calculation by default. When not checked, grades created through AGS are excluded from the final grade calculation by default.
Grades sync function on a "last update" model, meaning if a faculty member updates the gradebook in Brightspace and then retriggers a sync from the tool, the grade will be overwritten. However, you can check the grade event log to show the changes that occur for a particular grade object.
You can delete the grade items that you create using LTI Advantage if you send Assignments and grades services (AGS) delete command. If the grade item has a score, the AGS line item is deleted, but the grade item in Brightspace remains.
Automatic grade item creation
LTI 1.3 tools can optionally automatically create grades if none are already set up. The automatic grade item creation option is controlled by the Auto Create Grade Items LTI Advantage Deployment configuration setting (the default value is OFF).
To enable automatic grade item creation- From the Admin Tools menu, click External Learning Tools.
- Select the LTI Advantage tab. Do one of the following:
- If you want to create a new deployment, click New Deployment.
- If you want to make changes to an existing deployment, click on the corresponding deployment name in the table.
- In the Configuration Settings area, select Auto Create Grade Items.
Figure: The Auto Create Grade Items LTI Advantage Deployment configuration setting is ON.
- Do one of the following:
- Click Create Deployment (for creating new deployments).
- Click Save and Close (for editing deployments).
As a result, grades are automatically created in the Grade book after receiving a score from the LTI tool for the first time, regardless of if there is already a grade association.