Learning Tools Interoperability (LTI) Assignment and Grade Services Specification

LTI 과제 및 성적 서비스 표준 2.0

Final Release
Spec Version 2.0

위 관리번호는 1EdTech Consortium의 공식 표준 식별자가 아니라 1EdTech Korea의 번역 출판 관리를 위한 내부 식별자입니다.

요약

1. Overview

Assignment and Grade Services are based on IMS Learning Information Services (LIS) [LIS-20]. The Basic Outcomes service introduced in LTI 1.1 [LTI-11] provides a simple facility for associating a single gradebook column with each resource link and allows a tool to manage results in these columns as decimal normalized values. The creation of the gradebook column is typically part of the LTI link configuration within the tool platform's interface.

This document builds upon the concepts and terms introduced in the LTI 1.3 specification [LTI-13], specifically:

• The notions of platforms and tools as participants in an LTI workflow
  LTI 워크플로우에서 플랫폼(platform)과 도구(tool)의 참여자 역할.
• The organization of collections of resources within contexts
  컨텍스트 내 리소스 모음(collections of resources)의 구성.
• The interactions of messages and services
  메시지와 서비스 간의 상호작용.

The Assignment and Grade Services, as described in this document, replace the Basic Outcomes service and significantly extends the ability of the tool to interact with the tool platform's gradebook by:

• Supporting the declarative model established by basic outcome (tool platform creating a gradebook column on link creation)
  기본 결과 서비스에서 수립된 선언적 모델 지원: 도구 플랫폼이 링크 생성 시 성적표 열(gradebook column)을 생성한다.
• Allowing direct access and management of the gradebook columns (allowing the tool to programmatically create gradebook columns)
  성적표 열에 대한 직접 액세스 및 관리 허용: 도구가 프로그래밍 수준으로 성적표 열을 생성할 수 있다.
• More expressiveness on the score information including maximum points and grading status
  점수 정보의 표현력 확장: 최대 점수(maximum points) 및 채점 상태(grading status)와 같은 추가 정보를 포함한다.

Notably, the Assignment and Grade Services removes the strict one-to-one relationship between a resource link and a line item:

• Resource link may have more than one related line items
  리소스 링크는 둘 이상의 관련 라인 아이템을 가질 수 있다.
• Line items may be created without any explicit relationship to any Resource Link
  라인 아이템은 특정 리소스 링크와 명시적인 관계없이 생성될 수 있다.

The specification supports the auto-create flow to support simpler cases where the creation of the line item is delegated to the platform upon resource link creation (either as a setting or a line item declaration in the content item definition), allowing a straight migration from the basic outcome service.

The Assignment and Grade Services are made of 3 services:

• LineItem service: Management of line items
  라인 아이템 서비스(LineItem Service): 라인 아이템 관리.
• Score Service: Posting of scores by the tool. This service is a Write Only service (syncing grades to platform)
  점수 서비스(Score Service): 도구가 점수를 게시(post)하는 서비스. 이 서비스는 쓰기 전용(Write Only) 서비스로, 플랫폼으로 성적을 동기화한다.
• Result Service: Getting current grades from the platform's gradebook This is a Read Only service.
  결과 서비스(Result Service): 플랫폼 성적표에서 현재 성적을 가져오는 서비스. 이 서비스는 읽기 전용(Read Only) 서비스이다.

Note: that in any case the Assignment and Grade Services only expose gradebook information directly tied to the tool deployment. Other information in the tool platform's gradebook is not visible nor modifiable by the tool.

Figure 1 Assignment and Grade Services Overview

1.1 Terminology

Line item
A line item is usually a column in the tool platform's gradebook; it is able to hold the results associated with a specific activity for a set of users. The activity is expected to be associated with a single LTI context within the platform, so there is a one-to-many relationship between a context and its line items.

Line item container
A line item container has an array of line items. These line items might, for example, represent all those associated with a specific LTI context within the platform for the querying tool. Alternatively, the query may include a filter to query only line items associated to a resource link or a tool's resource. The actual content will depend upon the service request being used.

Result
A result is usually a cell in the tool platform's gradebook; it is unique for a specific line item and user. The value may have a numeric score and a comment. All results for a specific line item will be deemed to have a status of “Initialized” when the line item is created. A tool platform may maintain a history of changes for each result value and also allow an instructor to override a value. However, this service only provides access to the latest result. If the value of the result is changed directly within the tool platform, any such changes will be reflected in GET requests for the result.

Score
A score represents the last score obtained by the student for the tool's activity. It also exposes the current status of the activity (like completed or in progress), and status of the grade (for example, grade pending a manual input from the instructor). The score is sent from the tool to the tool platform using the score service. The tool platform ingests that value to possibly alter the current result (value shown in the gradebook).

Score container
The score container is the end point to push score updates for a given line item. It cannot be queried.

1.2 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

1.3 Document Set

1.3.1 Normative Documents

LTI Advantage Conformance Certification Guide [LTI-CERT-13]

The LTI Advantage Conformance Certification Guide describes the procedures for testing Platforms and Tools against the LTI v1.3 and LTI Advantage services using the IMS certification test suite.

1.3.2 Informative Documents

LTI Advantage Implementation Guide [LTI-IMPL-13]

The LTI Advantage Implementation Guide provides information to lead you to successful implementation and certification of the LTI Core v1.3 specification and the set of LTI Advantage specifications.

2. Relationship with other specifications

The Assignment and Grade Services relates to the following specifications:

• Deep Linking Message: The Deep Linking specification allows for a declarative option to create a line item by including its definition in the LTI Link's Content Item definition.
  Deep Linking Message: Deep Linking 표준은 LTI 링크의 콘텐츠 항목(Content Item) 정의에 라인 아이템(line item)의 정의를 포함하여 선언적으로 생성할 수 있는 옵션을 제공한다.
• Submission Review Message: The Submission Review Message specification allows the instructor and the student to launch from the gradebook back to the tool provider to see what's 'behind' a given result. This might for example allow the instructor to launch into a tool provider's grading interface in the context of a given student's submission.
  Submission Review Message: Submission Review Message 표준은 교사와 학생이 성적표에서 도구 제공자(tool provider)로 다시 이동하여 특정 결과와 관련된 내용을 확인할 수 있다. 예를 들어, 교사가 특정 학생의 제출물과 관련된 도구 제공자의 채점 인터페이스로 이동할 수 있다.

3. Services definition

3.1 Assignment and Grade Service claim

This specification introduces the claim https://purl.imsglobal.org/spec/lti-ags/claim/endpoint. This claim MUST be included in LTI messages if any of the Assignment and Grade Services are accessible by the tool in the context of the LTI message.

The claim defines the following properties:

• lineitems: the endpoint URL for accessing the line item container for the current context. May be omitted if the tool has no permissions to access this endpoint.
  lineitems: 현재 컨텍스트의 라인 아이템 컨테이너(line item container)에 접근하기 위한 엔드포인트(endpoint) URL. 도구가 이 엔드포인트에 접근할 권한이 없는 경우 생략될 수 있다.
• lineitem: when an LTI message is launching a resource associated to one and only one lineitem, the claim must include the endpoint URL for accessing the associated line item; in all other cases, this property must be either blank or not included in the claim.
  lineitem: LTI 메시지가 하나의 라인 아이템과만 연관된 리소스를 실행할 때, 해당 라인 아이템에 접근하기 위한 엔드포인트 URL을 반드시 포함해야 한다. 다른 모든 경우에는 이 속성이 비어 있거나 클레임에 포함되지 않아야 한다.
• scope: An array of scopes the tool may ask an access token for.
  scope: 도구가 액세스 토큰을 요청할 때 사용할 수 있는 범위(scope)의 배열.

The platform MAY change end point URLs as it deems necessary; therefore, by best practice, the tool should check with each message for the endpoint URL it should use with respect to the resource associated with the message. By best practice, the platform should maintain the presence of endpoints communicated within a message for some length of time, as tools may intend to perform asynchronous operations; for example, the tool may use the lineitem URL to update scores quite some time after the student has actually completed its associated activity.

3.1.1 Example Service Claims

3.1.1.1 Example: link with one line item, tool has all permissions

Figure 2

"https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
  "scope": [
    "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
    "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
    "https://purl.imsglobal.org/spec/lti-ags/scope/score"
  ],
  "lineitems": "https://www.myuniv.example.com/2344/lineitems/",
  "lineitem": "https://www.myuniv.example.com/2344/lineitems/1234/lineitem"
}

3.1.1.2 Example: link has no line item (or many), tool can query and add line items

Figure 3

"https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
  "scope": [
    "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
    "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
    "https://purl.imsglobal.org/spec/lti-ags/scope/score"
  ],
  "lineitems": "https://www.myuniv.edu/2344/lineitems/"
}

3.1.1.3 Example: link has a single line item, tool can only POST score

Figure 4

"https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
  "scope": [
    "https://purl.imsglobal.org/spec/lti-ags/scope/score"
  ],
  "lineitem": "https://www.myuniv.edu/2344/lineitems/1234/lineitem"
}

3.1.2 Extensions

Line item, score and result MAY be enriched with additional data. Any extension MUST be done by adding a new parameter to the JSON object. The key name MUST be a fully qualified URL uniquely identifying the property. The value MUST be any valid JSON data. The organization MAY provide a JSON Schema defining the format of the data added.

For example, if a tool wanted to pass extra data to the platform when the score is updated, it MAY enrich the score as follows:

Figure 5

{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "activityProgress" : "Completed",
  "gradingProgress" : "PendingManual",
  "userId" : "5323497",
  "https://www.toolexample.com/lti/score": {
    "originality": 94,
    "submissionUrl": "https://www.toolexample.com/lti/score/54/5893/essay.pdf"
  }
}

3.2 Line item service scope and allowed http methods

Access to this service MAY be controlled by authorization scopes. The authorization scope MAY differ per tool deployment and per context.

3.2.1 Line item service Media types and schemas

The accompanying OpenAPI documentation [AGS-OpenAPI] defines the following media types and schemas used by the line item Service:

• 'application/vnd.ims.lis.v2.lineitem+json'
• 'application/vnd.ims.lis.v2.lineitemcontainer+json'

The first media type provides a representation of a single line item; the second is a representation for a set of line items within a context.

3.2.2 Example Line Item Requests

3.2.2.1 Example GETting a single line item

Figure 6

HTTP/1.1 GET lineitem URL
Accept: application/vnd.ims.lis.v2.lineitem+json

200 OK
content-type: application/vnd.ims.lis.v2.lineitem+json
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "a-9334df-33",
  "tag" : "grade",
  "resourceLinkId" : "1g3k4dlk49fk",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z",
  "gradesReleased": false
}

3.2.2.2 Example GETting all line items for a given container

Figure 7

HTTP/1.1 GET lineitems URL
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json

200 OK
content-type: application/vnd.ims.lis.v2.lineitemcontainer+json
[  {
    "id": "https://lms.example.com/context/2923/lineitems/1",
    "scoreMaximum": 60,
    "label": "Chapter 5 Test",
    "resourceId": "a-9334df-33",
    "tag": "grade",
    "resourceLinkId": "1g3k4dlk49fk",
    "endDateTime": "2018-04-06T22:05:03Z"
    "gradesReleased": true
  },
  {
    "id": "https://lms.example.com/context/2923/lineitems/47",
    "scoreMaximum": 100,
    "label": "Chapter 5 Progress",
    "resourceId": "a-9334df-33",
    "tag": "originality",
    "resourceLinkId": "1g3k4dlk49fk"
  },
  {
    "id": "https://lms.example.com/context/2923/lineitems/69",
    "scoreMaximum": 60,
    "label": "Chapter 2 Essay",
    "tag": "grade"
  }
]

3.2.3 Line Item id REST Endpoint

The id property of the line item is the service endpoint URL to access or modify that line item. It must be a fully qualified URL addressable for read (HTTP GET), update (HTTP PUT) and delete (HTTP DELETE) operations. While it may occasionally change, a learning platform should aim at keeping it stable.

The Line Item id URL also serves as a base URL for Score POST and Result GET operations.

3.2.4 Container Request Filters

A 'GET' request to the container endpoint MAY use one or more of the following query parameters to filter the response; the platform MUST implement the support for those filters:

• resource_link_id - to limit the line items returned to only those which have been associated with the specified tool platform's LTI link ID (as passed in the 'resource_link_id' LTI message parameter).
  지정된 도구 플랫폼의 LTI 링크 ID(‘resource_link_id’ LTI 메시지 매개변수에 전달된 값)와 연결된 라인 아이템만 반환하도록 제한한다.
• resource_id - to limit the line items returned to only those which have been associated with the specified tool resource identifier.
  지정된 도구 리소스 식별자와 연결된 라인 아이템만 반환하도록 제한한다.
• tag - to limit the line items returned to only those which have been associated with the specified tag.
  지정된 태그와 연결된 라인 아이템만 반환하도록 제한한다.
• limit - to restrict the number of line items returned; the platform MAY further reduce the number of items returned at its own discretion. If more items exist following the returned ones, a 'Link' http header (per [RFC8288]) with a URL pointing to the next page and a 'rel' value of 'next' MUST be included in the response; The platform MAY also include other relations including 'prev', 'first' and 'last'.
  반환되는 라인 아이템의 수를 제한한다. 플랫폼은 자체 재량으로 반환되는 항목의 수를 더 줄일 수(MAY) 있다. 반환된 항목 다음에 더 많은 항목이 존재하는 경우, 응답에 URL이 포함된 Link HTTP 헤더([RFC8288] 참조)와 rel 값이 next인 항목을 반드시(MUST) 포함해야 한다. 플랫폼은 또한 prev, first, last와 같은 다른 관계를 포함할 수도(MAY) 있다.

The URL for the 'next' link is left to the discretion of the implementer. The tool must use the 'next' URL as is and not re-apply filters to it. The tool platform must thus make sure the 'next' URL contains enough information to insure the next page displays the right set of elements based on the filters present on the original request.

Link: <https://lms.example.com/sections/2923/lineitems/69?p=2>; rel="next"

If both 'resource_link_id' and 'resource_id' are used in the same query, then only those LineItems which are associated with BOTH the LTI link and the tool's resource MUST be included in the result set.

If there are no matching line items, the returned value MUST just be an empty array:

Figure 8

HTTP/1.1 GET lineitems URL?resource_id=d0d6212ecc4e4696a76f7359ef76e3f4
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json

200 OK
content-type: application/vnd.ims.lis.v2.lineitemcontainer+json
[]

3.2.5 Creating a new line item

A new line item is added by POSTing a line item ('application/vnd.ims.lis.v2.lineitem+json' representation) to the lineitems endpoint URL. The response by the platform MUST be the newly created item, enriched by its URL.

Figure 9

POST lineitems URL
Authorization: Bearer 78aerc7829z.890.duepz
Content-Type: application/vnd.ims.lis.v2.lineitem+json
{
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z"
}

HTTP/1.1 201 Created
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z"
}

Returned 'application/vnd.ims.lis.v2.lineitem+json' representation for platforms not supporting start and end times.

Figure 10

HTTP/1.1 201 Created
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade"
}

The platform MUST NOT modify the resourceId and tag values. It MAY modify the other properties, although preserving the original values from the tool is recommended.

Note: that the tool MAY provide a resourceLinkId value for the created line item; this supports the case where the tool may want to create a line item for an LTI Link resource link identifier that it has already received via a launch. The tool MAY NOT create a resource link identifier value of its own accord, nor use a resource link identifier for an LTI Context other than the one the platform already demonstrated owns that identifier. The platform may choose to ignore this property if provided by the tool, or treat it as a bad request if the tool improperly uses the resource link identifier value (for example, the link no longer exists in the LTI Context on the platform).

3.2.6 Updating a line item

A tool may update a line item definition by PUTting a complete definition of the line item to the line item URL endpoint. Note that this operation replaces the line item definition with the new, complete definition provided by the tool; because of this, by best practice the tool should first GET the state of a line item to retrieve the platform's current complete definition -- this can help the tool avoid editing-conflict race conditions, unintentionally unsetting previously set line item properties, and so on.

A tool MUST NOT change the id and resourceLinkId values. The tool may omit the id attribute. If the tool does provide a different value for one of these attributes on update, the platform MAY either ignore those values or treat the update request as invalid.

A platform may ignore changes to other attributes. The platform MUST return the line item definition as applied to the platform.

If the platform applies the scoreMaximum change, it is expected the results will be scaled to the updated value.

In the example below, the tool updates the line item's end time and label and voids the start time. The platform does not apply the change to scoreMaximum.

Figure 11

PUT lineitems URL
Authorization: Bearer 78aerc7829z.890.duepz
Content-Type: application/vnd.ims.lis.v2.lineitem+json
{
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "endDateTime": "2018-04-06T22:05:03Z"
}

HTTP/1.1 201 Created
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 50,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "startDateTime": "",
  "endDateTime": "2018-04-06T22:05:03Z"
  "gradesReleased": true
}

3.2.7 Label

The label is a short string with a human readable text for the line item. It MUST be specified and not blank when posted by the tool. A platform must always include the label.

3.2.8 scoreMaximum

The maximum score for this line item. Maximum score MUST be a numeric non-null value, strictly greater than 0.

3.2.9 resourceLinkId and binding a line item to a resource link resourceLinkId

A line item MAY be attached to a resource link by including a 'resourceLinkId' in the payload. The resource link MUST exist in the context where the line item is created, and MUST be a link owned by the same tool. If not, the line item creation MUST fail with a response code of Not Found 404.

The platform MAY remove the line items attached to a resource link if the resource link itself is removed.

3.2.10 Tool resource identifier resourceId

A tool MAY identify which of its resources the line item is attached to by including a non blank value for resourceId in the payload. This value is a string. For example, resourceId can be 'quiz-231' or any other resource identifier uniquely identifying a resource in a given context.

Multiple line items can share the same resourceId within a given context. resourceId must be preserved when a context is copied if the line items are included in the copy.

If no resourceId is defined for a lineitem, the platform may omit this attribute, or include it with a blank or null value.

3.2.11 tag

A tool MAY further qualify a line item by setting a value to tag. The attribute is a string. For example, one assignment resource may have 2 line items, one with tag as 'grade' and the other tagged as 'originality'.

Multiple line items can share the same tag within a given context. tag must be preserved when a context is copied if the line items are included in the copy.

If no tag is defined for a lineitem, the platform may omit this attribute, or include it with a blank or null value.

3.2.12 startDateTime

A tool MAY specify the initial start time submissions for this line item can be made by learners. The initial value may subsequently be changed within the platform.

ISO 8601 Date and time when the line item can start receiving submissions [ISO8601]. The datetime value MUST include a time zone designator (Z designator or +00:00 offset to specify UTC, or time offset from UTC for another time zone).

If the platform does not have any start time for the line item but supports that functionality, it SHOULD include the parameter with a blank or null value.

If the platform does not support that functionality, it should omit this parameter.

3.2.13 endDateTime

A tool MAY specify the initial end time submissions for this line item can be made by learners. The initial value may subsequently be changed within the platform.

ISO 8601 Date and time when the line item stops receiving submissions [ISO8601]. The datetime value MUST include a time zone designator (Z designator or +00:00 offset to specify UTC, or time offset from UTC for another time zone).

If the platform does not have any end time but supports that functionality, it SHOULD include the parameter with a blank or null value.

If the platform does not support that functionality, it should omit this parameter.

3.2.14 gradesReleased

A tool MAY specify to the platform if it wishes the grades to be released or not. A platform can decide how to handle this, as the platform owns its gradebook behavior.

3.2.15 Course copy and export/import

When line items are copied (or exported and imported), all their attributes MUST be preserved, with the exception of the 'resource_link_id' which will now be the id of the link in the copied/imported course. If the line items to be copied/imported are attached to a link that will not be restored/copied, the tool platform MUST NOT copy/import those line items.

A tool MUST NOT create a new line item in a copied/restored course if that line item would result in a duplicate. The tool MUST use the line items URL to query the existing line items and use the resourceLinkId, resourceId and/or tag values to internally apply the binding with the matching line item URLs.

Alternatively, for line item associated to resource links, it MAY just wait for the resource link to be launched and discover the associated line item using the line item parameter passed in the launch message.

3.3 Result Service

Result Service allows the tool to query the tool platform for the current results of its own line items. A result represents the current grade for a given line item and user in the platform's gradebook, including any change done directly to the grade within the tool platform. A result cannot be directly altered by the tool, and so only GET operations are supported. See Score Service for posting grades to the Tool Consumer.

3.3.1 Result service endpoint

The results service endpoint is a subpath of the line item resource URL: it MUST be the line item resource URL with the path appended with '/results'. Any query or route parameters from the line item resource URL must also be added.

3.3.2 Result service scope and allowed http methods

Access to this service MAY be controlled by authorization scope. The authorization scope MAY differ per tool deployment and per context.

3.3.3 Result service Media type and schema

Since the service URL is derived from the line item resource URL, it is NOT included in LTI messages.

This service only supports GET operations and MUST return all the results for this line item (i.e. across all users enrolled in the line item's context). When a context member does not have a result for a line item, the platform MAY omit the result or return a result without any score.

The results can be narrowed to a single user result by filtering by 'user_id'.

3.3.4 Media type and schema

The accompanying OpenAPI documentation [AGS-OpenAPI] defines the following media type and schemas used by the Result service:

3.3.4.1 Example of GETting the results for a line item

Figure 12

GET lineitem URL/results
Authentication: Bearer 8789.ghiurn2.polgw1
Accept: application/vnd.ims.lis.v2.resultcontainer+json

HTTP/1.1 200 OK
content-type: application/vnd.ims.lis.v2.resultcontainer+json
[{
  "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,
  "scoringUserId": "4567890",
  "comment": "This is exceptional work."
}]

3.3.4.2 id

URL uniquely identifying the result record.

3.3.4.3 scoreOf

URL identifying the Line Item to which this result belongs. Must be the same as the line item id and the value of the lineitem claim when included in the LTI message.

3.3.4.4 userId

The userId contains the LTI user ID identifying the recipient of the Result (usually a learner). The userId MUST be present.

3.3.4.5 resultScore

The current score for this user. The value must be a numeric value. If no value exists, this attribute may be omitted, or have an explicit null value.

3.3.4.6 resultMaximum

The 'resultMaximum' value MUST be a positive number (with 0 considered a negative number); if no value is specified, then a default maximum value of 1 must be used.

3.3.4.7 scoringUserId

The scoringUserId contains the LTI user ID identifying the provider of the Result (usually an instructor). If no value exists, this attribute may be omitted (if the Platform does not support this property, or if the item's result was provided by machine-scoring, for example).

3.3.4.8 comment

The current value for the comment. The value must be a string. If no value exists, this attribute may be omitted, blank or have an explicit null value.

3.3.5 Platform MAY skip empty results

A GET on Results URL MUST return a result record for each user that has a non empty 'resultScore' for the queried upon line item. The platform MAY skip empty results.

3.3.6 Container Request Filters

A 'GET' request to the container endpoint MAY use the following query parameters to filter the response:

• user_id: to filter the results to a single user. The results MUST contain at most 1 result. An empty array MAY be returned if the user does not have any result recorded.
  user_id: 특정 사용자에 대한 결과를 필터링하기 위해 사용. 결과는 반드시(MUST) 최대 1개의 결과를 포함해야 한다. 사용자가 기록된 결과를 가지고 있지 않은 경우, 빈 배열이 반환될 수(MAY) 있다.
• limit: to restrict the number of results returned; the platform MAY further reduce the number of results returned at its own discretion.
  limit: 반환되는 결과의 수를 제한. 플랫폼은 자체 재량으로 반환되는 결과 수를 더 줄일 수(MAY) 있다.

If more result records exist following the returned ones, a 'Link' http header (per [RFC8288]) with a URL pointing to the next page and a 'rel' value of 'next' MUST be included in the response. The platform MAY also include other relations including 'prev', 'first' and 'last'.

3.4 Score publish service

A score represents the grade and, more generally, the status of a user in regards to a given line item within the tool. The score service is used by the tool to publish the latest tool scores to the platform. The score service is write only, GET operations are explicitly not supported.

3.4.1 Service endpoint

The scores service endpoint MUST be the line item resource URL with the path appended with '/scores'. Any query or route parameters from the line item URL must also be added.

Since the service URL is derived from the line item resource URL, it is NOT included in LTI messages.

3.4.2 Score service scope and allowed http methods

Access to this service MAY be controlled by authorization scope. The authorization scope MAY differ per tool deployment and per context.

3.4.3 Score service Media type and schema

The accompanying OpenAPI documentation [AGS-OpenAPI] defines the following media types and schemas used by the Score service:

• 'application/vnd.ims.lis.v1.score+json'

3.4.3.1 Example POSTing a final score update

Figure 13

POST lineitem URL/scores
Content-Type: application/vnd.ims.lis.v1.score+json
Authentication: Bearer 89042.hfkh84390xaw3m
{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "scoreGiven" : 83,
  "scoreMaximum" : 100,
  "comment" : "This is exceptional work.",
  "activityProgress" : "Completed",
  "gradingProgress": "FullyGraded",
  "userId" : "5323497",
  "scoringUserId": "4567890"
}

HTTP/1.1 204 No Content

3.4.3.2 Example POSTing a progress started score update

Figure 14

POST lineitem URL/scores
Content-Type: application/vnd.ims.lis.v1.score+json
Authentication: Bearer 89042.hfkh84390xaw3m
{
  "timestamp": "2017-03-16T18:54:36.736+00:00",
  "activityProgress" : "InProgress",
  "gradingProgress": "NotReady",
  "userId" : "5323497",
  "submission": {
    "startedAt": "2017-03-13T16:12:27.000+00:00",
    "submittedAt": "2017-03-14T18:42:15.000+00:00"
  }
}

HTTP/1.1 204 No Content

3.4.4 scoreGiven and scoreMaximum scoreGiven

All scoreGiven values MUST be positive number (including 0). scoreMaximum represents the denominator and MUST be present when scoreGiven is present. When scoreGiven is not present or null, this indicates there is presently no score for that user, and the platform should clear any previous score value it may have previously received from the tool and stored for that user and line item.

The platform MUST support scoreGiven higher than scoreMaximum. For example, if the tool passes normalized score, ranging from 0 to 1, the scoreMaximum would be 1. scoreGiven: 1.1 would be a valid score.

A scoreGiven MAY be used to pass actual points value, in which case a value for scoreMaximum would be the maximum points possible for that student. For example, the tool MAY pass scoreGiven: 1, scoreMaximum: 3 instead of scoreGiven: 0.33333, scoreMaximum: 1.

Usually a platform will just re-scale the value to the line item's scoreMaximum. For example, if the line item maximum is 6 in the above example, then it would show 2 points as the given score; accordingly, the result would contain resultScore of 2 and resultMaximum of 6.

3.4.5 userId

The userId contains the LTI user ID identifying the recipient of the Score (usually a learner). The userId MUST be present.

3.4.6 scoringUserId

The scoringUserId contains the LTI user ID identifying the provider of the Score (usually an instructor). If present, this property must contain an LTI user ID (it may not be null or empty); this property is optional and need not be provided (if, for example, the Tool doesn't support the property or the Score is determined by machine-scoring).

3.4.7 activityProgress

activityProgress MUST be used to indicate to the tool platform the status of the user towards the activity's completion.

The activityProgress property of a score MUST have one of the following values:

• Initialized – the user has not started the activity, or the activity has been reset for that student.
  사용자가 활동을 시작하지 않았거나, 해당 학생에 대해 활동이 초기화된 상태.
• Started – the activity associated with the line item has been started by the user to which the result relates.
  라인 아이템과 연관된 활동이 사용자가 시작한 상태.
• InProgress - the activity is being drafted and is available for comment.
  활동이 작성 중이며, 댓글을 받을 수 있는 상태.
• Submitted - the activity has been submitted at least once by the user but the user is still able make further submissions.
  사용자가 활동을 한 번 이상 제출했지만, 추가 제출이 가능한 상태.
• Completed – the user has completed the activity associated with the line item.
  사용자가 라인 아이템과 연관된 활동을 완료한 상태

It is up to the tool to determine the appropriate 'activityProgress' value. A tool platform MAY ignore statuses it does not support.

The activityProgress property SHOULD be updated and transmitted to the platform anytime any meaningful state change in the activity takes place. For example, if a student begins an activity the activityProgress should be updated to 'Started' and sent to the platform.

3.4.8 gradingProgress

gradingProgress MUST be used to indicate to the platform the status of the grading process, including allowing to inform when human intervention is needed.

The gradingProgress property of a score must have one of the following values:

• FullyGraded: The grading process is completed; the score value, if any, represents the current Final Grade; the gradebook may display the grade to the learner
  채점이 완료된 상태. 점수 값이 있는 경우, 이는 현재 최종 성적을 나타내며, 성적표는 학습자에게 성적을 표시할 수 있다.
• Pending: Final Grade is pending, but does not require manual intervention; if a Score value is present, it indicates the current value is partial and may be updated.
  최종 성적이 대기 중인 상태로, 수동 개입이 필요하지 않다. 점수 값이 있는 경우, 이는 현재 값이 부분적인 점수이며 업데이트될 수 있음을 나타낸다.
• PendingManual: Final Grade is pending, and it does require human intervention; if a Score value is present, it indicates the current value is partial and may be updated during the manual grading.
  최종 성적이 대기 중인 상태로, 수동 개입이 필요하다. 점수 값이 있는 경우, 이는 현재 값이 부분적인 점수이며 수동 채점 중 업데이트될 수 있음을 나타낸다.
• Failed: The grading could not complete.
  채점을 완료할 수 없는 상태.
• NotReady: There is no grading process occurring; for example, the student has not yet made any submission.
  채점 과정이 이루어지지 않는 상태. 예를 들어, 학생이 아직 제출물을 제출하지 않은 경우.

It is up to the tool to determine the appropriate gradingProgress value. A tool platform MAY ignore scores that are not FullyGraded as those have to be considered partial grades.

The gradingProgress property SHOULD be updated and transmitted to the platform anytime any meaningful state change in the activity takes place.

3.4.8.1 Example 'application/vnd.ims.lis.v1.score+json' of a Score Pending Manual grading representation

Figure 15

{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "activityProgress" : "Completed",
  "gradingProgress" : "PendingManual",
  "userId" : "5323497"
}

3.4.9 timestamp

The timestamp MUST be present and indicate when the score was changed; it is intended to be used by the platform as a way to guard against out of order score updates. Score timestamp represents the server time when the Score state was modified. It MUST always be strictly increasing, so, for example, if a score has a value 'V1' at timestamp 'T1', then the score is updated at 'T2' to be 'V2', then reverted to 'V1', then the revert MUST have a timestamp 'T3' such that 'T1 < T2 < T3' and the three updates MUST have been sent to the platform in the following order:

1. (V1, T1)
2. (V2, T2)
3. (V1, T3)

Timestamp values MUST be formatted using ISO 8601 with a sub-second precision. The value MUST include a time zone designator (Z designator or +00:00 offset to specify UTC, or time offset from UTC for another time zone).

A tool MUST NOT send multiple score updates of the same (line item, user) with the same timestamp.

The platform MUST NOT update a result if the last timestamp on record is later than the incoming score update. It may just ignore the incoming score update, or log it if it maintains any kind of history or for traceability.

3.4.9.1 Example of valid timestamps

Figure 16

"timestamp": "2017-04-16T18:54:36.736+00:00"
"timestamp": "2017-04-16T18:54:36.736Z"
"timestamp": "2017-04-16T18:54:36.736+00"

3.4.10 submission (Optional)

The submission MAY be present and contains metadata about the submission attempt.

3.4.10.1 startedAt (Optional)

The startedAt MAY be present and indicates when work on the line item submission was first started by the student. If present, the value MUST be formatted using ISO 8601 with a sub-second precision. The value MUST include a time zone designator (Z designator or +00:00 offset to specify UTC, or time offset from UTC for another time zone).

The tool should include the startedAt in subsequent score updates. However, if not present, the platform should use the last value it received unless the activityProgress is set back to Initialized, in which case the startedAt value should be cleared.

In the abscence of startedAt, the learning platform should continue to use the timestamp of the 1st score event it receives with an activityProgress of Started or InProgress as the startedAt value.

3.4.10.2 submittedAt (Optional)

The submittedAt MAY be present and indicates when work on the line item submission was completed by the student. If present, the value MUST be formatted using ISO 8601 with a sub-second precision. The value MUST include a time zone designator (Z designator or +00:00 offset to specify UTC, or time offset from UTC for another time zone).

If this field, and the startedAt field are both present, then this field must be equal to, or later in time than, the startedAt field. The tool should include the submittedAt in subsequent score updates. However, if not present, the platform should use the last value it received unless the activityProgress is set back to Initialized, Started or InProgress, in which case the submittedAt value should be cleared.

In the abscence of submittedAt, the learning platform should continue to use the timestamp of the 1st score event it receives with an activityProgress of Submitted or Completed as the submittedAt value.

3.4.11 comment

A score object MAY include a comment. A comment value MUST be a string in plain text format. comment is intended to be seen by both the student and the instructors. This specification does not support an history of comments; the platform MUST update its comment with every score update. If a score update does not contain a comment, a blank or null, then the comment value MUST be cleared in the platform if the previously recorded comment was also a comment sent from the tool.

4. Implementation guidelines

4.1 Difference between result and score services

Figure 17 Diagram illustrating the working flow of Result and Score between a platform and a tool.

The Result is the current score within the Tool Consumer for the line item and user i.e. the value currently showing in the cell for that column and user in a typical tabular gradebook. This value can only be read by the tool, as the platform has the final say on what should be a student final score; for example, an instructor may force a grade through a manual entry directly in the gradebook. Or a modifier may be applied (late work, ...).

The Score is the last score (or status change) the user got within the tool itself. It is published to the platform so that it may be used to update the current result. This value is write-only.

4.2 Datetime values

It's highly recommend that all datetime values sent by both platform and tool be UTC (using either the Z designator or the +00:00 UTC time offset value).

4.3 Coupled vs decoupled line items

With the Assignment and Grade Services, there are now 2 main models of interaction to create and manage line items:

4.3.1 Declarative:

The platform creates the line item, usually at the time of the resource link creation. The resource link and line item are coupled. On resource link launch, substitution parameters related to the line item must be passed to the tool. The platform owns the lifecycle of the line item. This is the historical flow for line items lifecycle in LTI.

Figure 18 Diagram illustrating the lifecycle of the line item.

4.3.2 Programmatic:

The tool uses the line item service to manage its own line items. Those line items are typically not attached to any resource link i.e. it no longer requires a resource link to return grades. This is the decoupled model introduced by this specifications.

Figure 19 Diagram illustrating programmatic or uncoupled line items.

The decoupled approach offers much greater flexibility to the tool; for example it may push grades obtained through a different channel like a mobile app, or handle more complex tool offering complex experiences made of many activities behind a single link. It however requires an elevated level of trust from the platform which might be cautious to which tools it grants POST on 'LineItems.url'. The tool should prefer the simpler declarative model if it fits its requirement.

4.4 Substitution parameters available on launch

'LineItem.url' can only be resolved if there is only a single associated line item with the resource link. In that case, the corresponding matching parameters MUST be present in the launch data. This is a convenience that simplifies the most common use case and offers a natural migration from Basic Outcome Service. If, however, there is more than one line item, or no direct relationship between the resource link and line items, the platform cannot pass any of those values. The tool will need to use the 'LineItems.url' and filter by either 'resource_link_id', 'resource_id' and/or 'tag' depending on the binding model chosen. The tool should then persist that information to avoid querying the 'lineItems.url' each time a grade operation is needed.

4.5 Migrating from basic outcomes service

Tools already using the Basic Outcomes service introduced in LTI 1.1 can migrate their implementations to by using the score and result services and, if appropriate, also take advantage of the line item service to add further line items.

Migration from basic outcome service can be achieved in the following way:

The associated line item is the same as the one which would be accessed using the Basic Outcomes service if the platform offered both services, in which case the services could be used interchangeably.

4.6 Submission Review Message

The Submission Review Message is a companion specification which allows launches from a result in the platform's gradebook (or wherever the result is displayed) back to the Tool in the context of the result; for example, a student can see an 82% and click on the grade to actually see the submission, or an instructor can directly access the student's submission to review and grade it.

The ability for the Tool to exchange statuses in addition to score values offers the infrastructure for a richer integration; for example:

1. The tool posts a Score with a gradingProgress: pendingManual
   도구가 gradingProgress: pendingManual 상태로 점수를 POST한다.
2. The platform decorates the gradebook cell with a needs attention indicator
   플랫폼이 성적표 셀에 "주의 필요(needs attention)" 표시를 추가한다.
3. The instructor can then click on the indicator
   교사가 이 표시를 클릭한다.
4. An LtiSubmissionReviewRequest launches the user into the grading interface of the tool, directly in context of the activity and student to be graded
   LtiSubmissionReviewRequest가 실행되며, 사용자를 도구의 채점 인터페이스로 이동시킨다. 이 인터페이스는 채점할 활동과 학생의 컨텍스트를 직접 보여준다.
5. After grading, the tool sends a score update through a POST to the Score endpoint and redirects the user back the Learning Platform using the return URL included in the launch
   채점이 완료되면, 도구가 점수 업데이트를 점수 엔드포인트(Score endpoint)에 POST로 전송하고, 실행에 포함된 반환 URL을 사용하여 사용자를 학습 플랫폼으로 다시 리디렉션한다.
6. The tool platform updates the grade and status of the activity for that student 도구 플랫폼이 해당 학생의 활동 성적 및 상태를 업데이트한다.

4.7 Scores and gradingProgress

The Tool must set the 'gradingProgress' to 'FullyGraded' when communicating the actual student's final score. The platform may decide to not record any score that is not final ('FullyGraded').

4.8 Managing Multiple Line Items

These new services enable a tool to return multiple results to a tool consumer for a single resource. For example, a percentage progress measure could be maintained as well as the grade achieved in the tool consumer gradebook. The typical workflow for achieving this is as follows (assuming that the LineItem, Score and Result services are enabled for the tool by the tool consumer, and the 'LineItems.url' capability has been agreed between the parties):

1. On receipt of the first launch from a resource link, the tool sends a 'GET' request to the 'LineItems.url'. It may specify the 'resource_link_id' query parameter to only get the line items associated with the link. The response is checked for any existing line items and, for those which are not present (based on the value of their 'tag' or 'resourceId' element), the tool sends a POST request to the line item container endpoint with the 'resourceLinkId' element set to the value of the 'resource_link_id' message parameter and an appropriate value for the 'tag' element; for example, "grade" or "progress". The 'id' elements is extracted from the response(s) received and saved for future reference. It will serve as the base to get results and post scores.
   리소스 링크에서 처음 실행을 수신하면, 도구는 LineItems.url에 GET 요청을 보낸다. 이때 resource_link_id 쿼리 매개변수를 지정하여 링크와 연결된 라인 아이템만 가져올 수 있다. 응답에서 기존 라인 아이템을 확인하고, tag 또는 resourceId 값에 따라 존재하지 않는 라인 아이템에 대해 도구는 라인 아이템 컨테이너 엔드포인트에 POST 요청을 보낸다. 이 요청은 resourceLinkId 요소를 resource_link_id 메시지 매개변수 값으로 설정하고, tag 요소에 "grade" 또는 "progress"와 같은 적절한 값을 설정한다. 응답에서 반환된 id 요소를 추출하여 저장하고, 이후 참조를 위해 사용한다. 이 id는 결과를 가져오거나 점수를 게시하는 기본 경로로 사용된다.
2. As a learner progresses through the resource, scores may be 'POST'ed to the 'scores' endpoint.
   학습자가 리소스를 진행함에 따라 점수는 scores 엔드포인트에 POST 될 수 있다.
3. When the learner completes the activity, score may be 'POST'ed to the 'scores' endpoint with an 'activityProgress' of 'Completed'.
   학습자가 활동을 완료하면, 점수는 scores 엔드포인트에 activityProgress가 Completed로 설정된 상태로 POST 될 수 있다.
4. When the final score is set on the activity, score must 'POST'ed to the 'scores' endpoint with a 'gradingProgress' of 'FullyGraded'.
   활동에 최종 점수가 설정되면, 점수는 gradingProgress가 FullyGraded로 설정된 상태로 scores 엔드포인트에 반드시 POST 되어야 한다.

Note: that for simpler interaction, there may only need to be a single POST to scores, when the activity is completed and graded.

Further, line items can be created in the same way; giving each a unique 'tag' or 'resourceId' value allows their purpose to be identified when requesting a line item container and, for example, when a resource link has been copied within the tool consumer (thereby giving it a new resource link ID).

The flow is similar when a binding to a resource ID rather than to a resource link ID is used.

4.9 Line Item Declaration through Deep Linking Deep Linking

Alternatively to being created programmatically using the LineItems Service, line items may also be created declaratively by embedding their definitions within the LTI link definition as part of a Deep Linking message exchange (see https://www.imsglobal.org/spec/lti-dl/v2p0).

A. Revision history

This section is non-normative.

LTI Assignment and Grade Services v2.0 follows from, and replaces, the Outcomes Management v1.0 specification and the Gradebook Services specification (later rebranded as IMS LTI Assignment and Grades Services).

A.1 Version History

B. References

B.1 Normative references

[AGS-OpenAPI]

Learning Tools Interoperability® Assignment and Grade Services Version 2.0 OpenAPI Specs. Colin Smythe. IMS Global Learning Consortium. URL: https://www.imsglobal.org/spec/lti-ags/v2p0/openapi/

[ISO8601]

Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874

[LIS-20]

IMS Global Learning Information Services v2.0. L. Feng; W. Lee; C. Smythe. IMS Global Learning Consortium. June 2011. URL: https://www.imsglobal.org/lis/

[LTI-11]

IMS Global Learning Tools Interoperability® Implementation Guide. G. McFall; M. McKell; L. Neumann; C. Severance. IMS Global Learning Consortium. March 13, 2012. URL: https://www.imsglobal.org/specs/ltiv1p1

[LTI-13]

IMS Global Learning Tools Interoperability® Core Specification v1.3. C. Vervoort; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/

[LTI-CERT-13]

IMS Global Learning Tools Interoperability® Advantage Conformance Certification Guide. D. Haskins; M. McKell. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/cert/

[LTI-IMPL-13]

IMS Global Learning Tools Interoperability® Advantage Implementation Guide. C. Vervoort; J. Rissler; M. McKell. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/impl/

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

[RFC8288]

Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html

C. List of Contributors

The following individuals contributed to the development of this document: