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
Understanding the behavior of Grades with AGS
Administrators should be aware of the following considerations that affect the behavior of grades when using the Assignments and Grades Service. AGS scores are stored only when the Can be graded in Grades option is enabled for the user being assessed. If a grade item is submitted for a user with a role that cannot be graded, the grade is no longer stored, and an error message is sent to the submitting tool.
To set tool behaviors:
- From your organizational homepage, click Admin Tools.
- Under the Security section, click Roles and Permissions.
- Click the More Actions menu beside the role for which you want to set the Can be graded in Grades option.
- Click Edit Settings.
- Under Tool Behavior Options, select Can be graded in Grades.
- Click Save and Close.
Figure: When you enable the Can be graded in Grades option, you can assess users enrolled with this role in the Grades tool.
Administrators should also be aware that if Can Exceed is not set for a grade item, and a tool sends the grade book a grade higher than the maximum set for the grade item:
- The maximum allowable score (not the higher grade submitted) appears in the grade book.
- The score sent from the tool that is higher than the maximum is recorded in an internal table for future reference.
Note: LTI tools and D2L customers do not have access to this internal table.
To turn on or turn off the Can Exceed status for a grade item:
- From the course navbar, click Grades.
- Click the Manage Grades tab and select the grade item.
- On the Properties tab, under Grading, confirm or update the Can Exceed check box as applicable.
Figure: The Can Exceed option in the Grading area of a grade item's Properties.
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.
|
Note: It is recommended to use a QuickLink instead if a LineItem, as there are limitations in where LineItem pass back works when adding via Insert Stuff or through the course builder deep link quick link.
For the course builder workflow, clicking the link in the panel allows the tool to send the information to create the LineItem.
|
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.
Link Placements and Grades
Every placement of a link in a course is associated to the same grade object. This is completed by having every placement of the link have the same Resource Link ID within that course. If additional line items are needed for a specific link, additional links can be created through External Learning Tools > LTI Advantage or, if the tool supports Deep Linking, the resource selected through the deep linking launch has a distinct LTI resource link ID and line item association.
AGS can be used to manually create a grade associated to a link by including the Resource Link ID received from the launch, this works for all links except for widgets.
HTML Editor and Deep Linking
Line items can be created using the HTML editor and deep linking in two ways:
- By using Auto Create Grades: the line item is created automatically. The grade is out of 100, and any further updates to the line item should be made through AGS.
- Through AGS: a tool can use AGS to manually create a line item. To ensure the grade has the correct link association, the tool must include the ResourceLinkId received from the launch when creating the line item.
Maximum Score
If Can Exceed is not selected and a tool sends a score higher than the max allowed, the max score is shown in the grade book, and the actual score sent from the tool is stored in an internal table, tools and customers do not have access to this table.