Learning Tools Interoperability (LTI)® Course Groups Service - 1EdTech Candidate Final Version 1.0

Learning Tools Interoperability (LTI)® Course Groups Service

IMS Candidate Final Public
Spec Version 1.0
IMS Candidate Final Public
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:
{
  "id" : "https://lms.example.com/class/2923/groups/",
  "groups" : [
    {
      "id": "44711f9f-64af-443a-bc3d-0abbfff73790",
      "name": "Bob's Tuesday Group",
      "set_ids": ["912cc53f-b431-447e-aff6-9d49aa9b72f2"],
      "tag": "marking"
    },
    {
      "id": "bf2042b4-fdad-486a-86f3-bdb84e28a099",
      "name": "Bob's Friday Group",
      "set_ids": ["912cc53f-b431-447e-aff6-9d49aa9b72f2", "8127ccca-1d2d-496d-976c-393616ad1ff4"],
      "tag": "marking",
      "hidden": true
    },
    {
      "id": "89230b3-a341-447e-aff6-9d354aa9b72a6",
      "name": "The cool kids group"
    }
  ]
}
Figure 1 Example of application/vnd.ims.lti-gs.v1.contextgroupcontainer+json media type.

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:
{
  "id" : "https://lms.example.com/class/2923/groups?user_id=0ae836b9-7fc9-4060-006f-27b2066ac545",
  "user_id" : "0ae836b9-7fc9-4060-006f-27b2066ac545",
  "groups" : [
    {
      "id": "44711f9f-64af-443a-bc3d-0abbfff73790",
      "name": "Bob's Tuesday Group",
      "set_ids": ["912cc53f-b431-447e-aff6-9d49aa9b72f2"],
      "tag": "marking"
    }
  ]
}
Figure 2 Example of application/vnd.ims.lti-gs.v1.contextgroupcontainer+json media type, filtered by user_id.

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:
{
  "id" : "https://lms.example.com/class/2923/groups/sets",
  "sets": [
    {
      "id": "912cc53f-b431-447e-aff6-9d49aa9b72f2",
      "name": "The Chemistry Lab Group Set"
    },
    {
      "id": "6af307fc-cc7d-4867-9e6f-20c85601367a",
      "name": "Course Sections",
      "tag": "http://purl.imsglobal.org/vocab/lis/v2/course#CourseSection"
    },
    {
      "id": "02d133a7-d26e-41ec-8e63-c97fe562f0ca",
      "name": "The Physics Lab Group Set"
      "hidden": true
    }
  ]
}
Figure 3 Example of application/vnd.ims.lti-gs.v1.contextgroupsetcontainer+json media type.

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.

{
  "id" : "https://lms.example.com/sections/2923/memberships",
  "context": {
    ...
  },
  "members" : [
    {
      "status" : "Active",
      "name": "Jane Q. Public",
      "user_id" : "0ae836b9-7fc9-4060-006f-27b2066ac545",
      "roles": [
        ...
      ],
      "group_enrollments": [
        {"group_id":"44711f9f-64af-443a-bc3d-0abbfff73790"},
        {"group_id":"bf2042b4-fdad-486a-86f3-bdb84e28a099"}
      ],
      ...
    }
  ]
}
Figure 4

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.
"https://purl.imsglobal.org/spec/lti-gs/claim/groupsservice": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-gs/scope/contextgroup.readonly"
    ],
    "context_groups_url": "https://www.myuniv.example.com/2344/groups",
    "context_group_sets_url": "https://www.myuniv.example.com/2344/groups/sets",
    "service_versions": ["1.0"]
  }
Figure 5 Example of the https://purl.imsglobal.org/spec/lti-gs/claim/groupsservice claim.
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
  • Added section on substitution parameters. (docs)
  • Added hidden to ContextGroup. (docs)
  • Added tag to ContextGroup. (docs)
  • Switch to LtiContextLaunchRequest from ContextLaunchRequest.
  • Allow multiple set IDs, so switch set_id to set_ids for ContextGroup. (docs)
  • Add group substitution variables. (docs)
Candidate Final Public 1.0 3 21 July 2023
  • Updated to Candidate Final Public

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 LenordTurnitinEditor
Bracken MosbackerIMS Global
Marc PhillipsInstructure
Jesse PoulosInstructure
Eric PrestonBlackboard
Claude VervoortCengage
Peter Franza42 Lines, Inc.

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: Learning Tools Interoperability (LTI)® Course Groups Service 1.0

Date: 1 October 2019