Learning Tools Interoperability (LTI)® Course Groups Service - 1EdTech Candidate Final Version 1.0
Spec Version 1.0
Document Version: | 3 |
Date Issued: | 1 October 2019 |
Status: | This document is for review and adoption by the IMS membership. |
This version: | https://www.imsglobal.org/spec/lti-gs/v1p0/ |
Latest version: | https://www.imsglobal.org/spec/lti-gs/latest/ |
Errata: | https://www.imsglobal.org/spec/lti-gs/v1p0/errata/ |
IPR and Distribution Notice
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .
The following participating organizations have made explicit license commitments to this specification:
Org name | Date election made | Necessary claims | Type |
---|---|---|---|
D2L Corporation | January 15, 2020 | No | RF RAND (Required Elements) |
Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.
Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.
The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .
© 2023 IMS Global Learning Consortium, Inc. All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
Abstract
The Learning Tools Interoperability (LTI)® Course Groups Service communicates to the tool the groups available in the course and their respective enrollment. For example, the tool could use this information to re-use LMS defined groups rather than having to define groups within the tool.
1. Introduction
1.1 Overview
The Context Groups Service is based on IMS Learning Information Services (LIS) [LIS-20] and W3C Organization Ontology [vocab-org]. It is concerned with providing access to data about users’ enrollments on groups within a context, a course being an example of a context.
1.2 Core Requirements
The LTI Context Groups Service requires the implementation of the LTI 1.3 Core specification [LTI-13].
1.2.1 Security Mechanisms
All service requests MUST be secured by including a properly scoped access token in the Authorization header as per the IMS Global Security Framework [SEC-10].
1.3 Relationship with other specifications
The Context Groups Service relates to the following specifications:
- Names and Roles Provisioning Service [LTI-NRPS-20]: The names and roles service allows for the discovery of all users' group enrollments within a particular context.
2. Context Groups Service
A context can contain several context groups. A context may also contain group sets. A group set is a group of groups. There is no direct user enrollment in group sets. A context group may be part of multiple group sets within a given context. A user may be a member of any number of groups in a given group set.
2.1 Context Groups
A Context Group specifies a grouping of members within the same context. Context groups are contained by a single context. They are not LTI contexts themselves. For example, when launching a group activity, the LTI context will still be the
CourseSection
context.
The purpose of the grouping is not defined within this specification. However the tag
field MAY be used as an indicator of purpose.
A set of context groups may be gathered together under a group set, see below. A group may only be part of at most a single group set.
Field | Description |
---|---|
id | REQUIRED. The unique identifier for the context group. This identifier must be unique within all context groups for the current context and MUST remain stable between requests. |
name | REQUIRED. The human readable name for the context group. The tool MAY use this value to display to end users. |
tag | OPTIONAL. A string value identifying the purpose of that group. |
set_ids | OPTIONAL. An array of ids of the sets that group belongs to. |
hidden | OPTIONAL. Indicates if the group and its membership is hidden to learners. The default is false. |
2.1.1 Media type
The accompanying documentation defines the following media type used by the groups service for fetching groups:
application/vnd.ims.lti-gs.v1.contextgroupcontainer+json
2.1.1.1 Example:
2.1.2 User Groups
To fetch the groups an individual user is associated with, the tool may append user_id
as a query parameter to the context groups endpoint. This filter MUST be supported by the platform and return an application/vnd.ims.lti-gs.v1.contextgroupcontainer+json
containing ONLY the groups within the current context that the supplied user is enrolled on. Additionally, the response must contain the user id used in the filter under the key user_id
.
2.1.2.1 Example:
2.2 Context Group Sets
A group set is a gathering of context groups from the same context that typically represent a division of the course roster for a specific task. There is no direct user enrollment in group set, and a context member may be enrolled in any number of the groups within a given group set.
Field | Description |
---|---|
id | REQUIRED. The unique identifier for the context group set. This identifier must be unique within all context group sets for the current context and MUST remain stable between requests. |
name | REQUIRED. The human readable name for the context group set. The tool MAY use this value to display to end users. |
tag | OPTIONAL. A string value identifying the purpose of that group set. This may be a URL from the LIS context type vocabulary or a custom string to indicate a platform's proprietary type. |
hidden | OPTIONAL. Indicates if the group set and its membership is hidden to learners. The default is false. |
Context Groups belonging to a given set are identified by the set_ids
property.
2.2.1 Media type
The accompanying documentation defines the following media type used by the groups service for fetching group sets:
application/vnd.ims.lti-gs.v1.contextgroupsetcontainer+json
2.2.1.1 Example:
2.3 Group enrollment
Enrollment in a Group is binary. A context member is either enrolled in a group or not, there is no role or condition within the enrollment.
2.4 Within memberships
To indicate the context group enrollments for each user within a context membership, a group_enrollments
field can be added to each member object within the membership container.
The tool must specify a groups=true
query parameter to get the group_enrollments.
2.5 Using the service
There are two actions defined for this service, both of which are HTTP GET requests.
The request must be properly secured as per the LTI Security Framework used by the LTI integration using the scope https://purl.imsglobal.org/spec/lti-gs/scope/contextgroup.readonly
.
2.5.1 Groups
The context groups endpoint is required for the platform to support. A request should be sent to the context_groups_url
endpoint provided and include an Accept
header with a value of application/vnd.ims.lti-gs.v1.contextgroupcontainer+json
.
2.5.2 Group Sets
The context group sets endpoint is optional for the platform to support. A request should be sent to the context_group_sets_url
endpoint provided and include an Accept
header with a value of application/vnd.ims.lti-gs.v1.contextgroupsetcontainer+json
.
2.5.3 Limit query parameter
The Tool may specify a maximum number of entities to be returned in the response from the Platform when requesting groups or group sets. The Platform may use this as a guide to the number it returns but may include more or less than the value provided. If the response from a Platform does not comprise all of the groups or sets a rel=next
header link will be included to indicate how to request the next set of groups. The absence of a rel=next
header link indicates that no more entities are available.
Link: https://www.myuniv.example.com/class/2344/groups/?p=2;rel=next
2.6 Substitution parameters
Message Variable Name | Corresponding LTI Value |
---|---|
Membership.course.groupIds | A comma-separated list of group identifiers that aligns to the group_enrollments array passed in the membership service |
2.7 Binding with LTI Core
2.7.1 LTI 1.3 integration
2.7.1.1 Claim for inclusion in LTI messages
The claim to include the Groups Service parameter in LTI 1.3 messages is:
https://purl.imsglobal.org/spec/lti-gs/claim/groupsservice
.
It contains 4 properties:
Field | Description |
---|---|
context_groups_url | REQUIRED. Groups service URL that is fully resolved, and matches the context of the launch. |
context_group_sets_url | OPTIONAL. Group Sets service URL that is fully resolved, and matches the context of the launch. |
scope | REQUIRED. This must always be an array containing the scope https://purl.imsglobal.org/spec/lti-gs/scope/contextgroup.readonly |
service_versions | REQUIRED. Specifies the versions of the service that are supported on that end point. |
2.7.1.2 Scope and Service security
All service requests should be secured by including a properly scoped access token in the Authorization header as per the IMS Global Security Framework [SEC-10].
The scope to request to access this service is:
Scope | Description | Allowed HTTP Methods |
---|---|---|
https://purl.imsglobal.org/spec/lti-gs/scope/contextgroup.readonly |
Tool can query context's enrollment | context_groups_url : GET |
2.8 Group Substitution Variables
Course groups and course memberships may have a many to many relationship. This means that a member can belong to multiple groups within a course. When performing an LTI launch, a tool may request a LaunchGroup variable to accept any specific course group that might be associated to the launch.
Message variable name | Corresponding LTI value |
---|---|
CourseGroup.id
| This variable will be substituted with the ID of any one context group asociated with the launch, or an empty string if there is no group associated with the launch. This is intended for tools that offer group activities and need to know which group the launch is intended for. The existence of this variable and any value it holds will not mean the launch user is part of the provided context group. For example, an instructor may launch a group activity of a course group where they not a member. Any id value provided by the platfrorm must be of a group in the context course and must never be an id of a group outside the course context. |
3. 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.
A. Revision History
This section is non-normative.
Spec Version | Document Version | Release Date | Comments |
---|---|---|---|
Candidate Final 1.0 | 1 | 1 October 2019 | First release of spec document. |
Candidate Final 1.0 | 2 | 24 January 2023 | |
Candidate Final Public 1.0 | 3 | 21 July 2023 |
|
B. References
B.1 Normative references
- [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-13]
- IMS Global Learning Tools Interoperability (LTI)® 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-NRPS-20]
- IMS Global Learning Tools Interoperability (LTI)® Names and Role Provisioning Services. C. Vervoort; E. Preston; J. Rissler. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti-nrps/v2p0/
- [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
- [SEC-10]
- IMS Global Security Framework v1.0. C. Smythe; C. Vervoort; M. McKell; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/security/v1p0/
- [vocab-org]
- The Organization Ontology. Dave Reynolds. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/vocab-org/
C. List of Contributors
The following individuals contributed to the development of this document:
Name | Organization | Role |
---|---|---|
Martin Lenord | Turnitin | Editor |
Bracken Mosbacker | IMS Global | |
Marc Phillips | Instructure | |
Jesse Poulos | Instructure | |
Eric Preston | Blackboard | |
Claude Vervoort | Cengage | |
Peter Franza | 42 Lines, Inc. |