Assignment and Grade Services (AGS) is a Learning Tools Interoperability (LTI) extension. LTI 1.3 is designed to handle advanced grade interactions between a tool and a platform. It provides developers with a series of sub-services that allow the management of grade objects and values inside Brightspace.
Assignment 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 Assignment and Grades Services. 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.
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.
LineItem Service
Use LineItem Service 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 LineItem when there is only one LineItem associated with the resource link; If there is more than one LineItem, 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 sending 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 ResourceID for the link in content.
- resource_id: Return 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 passback 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 a 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, refer to 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."
}]
|
Note: The Brightspace Gradebook allows instructors to provide comments using a full HTML editor. However, the Learning Tools Interoperability (LTI) service accepts comments only as plain text, so it removes any HTML formatting from the comment. If the comment received through the Result service does not match the comment most recently provided by the tool, an instructor likely updated the feedback in the Brightspace Gradebook. Use the Score service to update only the grade value, without overwriting the instructor's comment. |
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 following 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"
>}
|
Note: If needed, use the Score service to update only the grade. This allows the tool to preserve comments that an instructor entered in the Brightspace grade book, including comments that use HTML formatting, instead of overwriting them with a new plain-text comment. |
Timestamp is a mandatory value indicating when the score changes 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 relies only 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. To view details of Grading Progress, refer to the official IMS documentation.
When checked, grades created through Assignment and Grades Services 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 an instructor 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 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
The Auto Create Grade Items setting offers feature parity with the Outcomes service in LTI 1.1. When this setting is enabled, Brightspace automatically creates a line item for each LTI link. This can create confusing situations if the tool does not use the automatically created line item and instead uses the Assignment and Grade Services (AGS) to create its own line items.
The Automatic Grade Item Creation option is controlled by the Auto Create Grade Items LTI Advantage Deployment configuration setting (the default value is OFF).
|
Important: This setting is a legacy compatibility option that is planned for deprecation and is not recommended for new integrations. In Brightspace Apps, this setting is named Legacy LTI Grades Management. |
To enable Automatic 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.
- Do one of the following:
- Click Create Deployment (for creating new deployments).
- Click Save and Close (for editing deployments).
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 ResourceLinkID 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 ResourceLinkID and line item association.
AGS can be used to manually create a grade associated with a link by including the ResourceLinkID received from the launch. This works for all links except for widgets.
HTML Editor and Deep Linking
A tool can use Assignment and Grade Services (AGS) to create a grade item for any LTI link in its deployment. When LTI links are added to HTML pages through Deep Linking (using either Insert Stuff or Quicklink), Brightspace ignores the line item provided by the tool. Instead, the tool can create the grade item later by using AGS when an instructor or learner launches the LTI link.
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 maximum allowed, the maximum 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.