Skip to content

Commit

Permalink
docs: add LTI 1.3 documentation and reorganize docs (#1934) [BD-24]
Browse files Browse the repository at this point in the history 
* docs: Update LTI component documentation

* Add LTI 1.3 and LTI Advantage documentation
* Reorganize docs

Signed-off-by: Giovanni Cimolin da Silva <[email protected]>

* Finish writing docs

* docs: Address review comments

* fix: Fix quality issue

* Update en_us/shared/exercises_tools/lti_component.rst

Co-authored-by: Ned Batchelder <[email protected]>

* fix: Revert change in LTI Provider URL

Co-authored-by: Ned Batchelder <[email protected]>
  • Loading branch information
@giovannicimolin @nedbat
giovannicimolin and nedbat authored May 5, 2021
1 parent 3992f39 commit ed79509
Show file tree
Hide file tree
Showing 2 changed files with 236 additions and 40 deletions.
10 changes: 8 additions & 2 deletions en_us/links/links.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -377,8 +377,15 @@

.. _IMS LTI 1.1 Consumer Launch: http://www.imsglobal.org/developers/LTI/test/v1p1/lms.php

.. _IMS Global Learning Tools Interoperability: http://www.imsglobal.org/LTI/v1p1p1/ltiIMGv1p1p1.html
.. _LTI 1.1: https://www.imsglobal.org/LTI/v1p1p1/ltiIMGv1p1p1.html

.. _LTI 1.3: https://www.imsglobal.org/spec/lti/v1p3

.. _LTI Advantage: https://www.imsglobal.org/lti-advantage-overview

.. _Deep Linking: https://www.imsglobal.org/spec/lti-dl/v2p0

.. _Assignments and Grades services: https://www.imsglobal.org/spec/lti-ags/v2p0

.. _Issuing Badges: https://wiki.mozilla.org/Badges/Onboarding-Issuer#Issuing_Badges

Expand Down Expand Up @@ -608,4 +615,3 @@
.. _Stanford Online xqueue_pull_ref: https://github.com/Stanford-Online/xqueue_pull_ref

.. _Mozilla Firefox: https://www.mozilla.org/en-US/firefox/new/

266 changes: 228 additions & 38 deletions en_us/shared/exercises_tools/lti_component.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ LTI Component

You can integrate remote learning tools, such as applications and textbooks,
into your course with the learning tools interoperability (LTI) component. The
LTI component is based on the `IMS Global Learning Tools Interoperability`_
version 1.1.1 specifications.
LTI component supports tools with the `LTI 1.1`_ and `LTI 1.3`_ specifications.
Additionally, the LTI 1.3 tools can use the following LTI Advantage extensions:
`Deep Linking`_ and `Assignments and Grades services`_.

.. contents::
:local:
Expand Down Expand Up @@ -71,13 +72,37 @@ system such as Canvas or Blackboard.

.. note the slightly different destination links ^. Alison 23 Nov 2015
.. _LTI Information:
.. _enable_lti_components:

******************************************
Enabling LTI Components for a Course
******************************************

Before you can add LTI components to your course, you must enable the LTI tool
in Studio.

******************************
LTI Authentication Information
******************************
To enable the LTI tool in Studio, add ``"lti_consumer"`` to the
**Advanced Module List** on the **Advanced Settings** page. For more
information, see :ref:`Enable Additional Exercises and Tools`.

.. note::
The ``lti_consumer`` module replaces a previous version of the LTI component.
The name of the module for the previous LTI component is ``lti`` and it may
appear in the **Advanced Module List** for older courses.

Some LTI tools require users to provide authentication credentials. If the LTI
The ``lti_consumer`` module includes all of the functionality of the previous
LTI component and it should be used for all new courses. Courses that include
the previous LTI component will continue to work correctly, even if the
``lti`` module is no longer present in the **Advanced Module List**.


.. _Setting up a LTI 1.1 component:

*******************************
Setting up an LTI 1.1 component
*******************************

Some LTI 1.1 tools require users to provide authentication credentials. If the LTI
tool you are including in your course requires authentication, you must add an
LTI passport for that tool to your course configuration.

Expand Down Expand Up @@ -133,8 +158,7 @@ passport string.

``id_21441:b289378-f88d-2929-ctools.school.edu:23746387264``

``book_lti_provider_from_new_york:b289378-f88d-2929-ctools.company.com:yt4984yr
8``
``book_lti_provider_from_new_york:b289378-f88d-2929-ctools.company.com:yt4984yr8``

.. _adding_an_lti_passport:

Expand All @@ -155,7 +179,7 @@ To add an LTI passport for an LTI tool to the configuration for your course, fol

``"test_lti_id:b289378-f88d-2929-ctools.umich.edu:secret"``

For more information about creating your key, see :ref:`LTI Information`.
For more information about creating your key, see :ref:`Setting up a LTI 1.1 component`.

#. If you use more than one LTI provider in your course, separate each LTI
passport string with commas. Make sure to surround each entry with quotation
Expand All @@ -175,38 +199,17 @@ To add an LTI passport for an LTI tool to the configuration for your course, fol
The page refreshes automatically, reformats your entry in the **LTI Passports**
field, and displays a notification that your changes have been saved.

.. _enable_lti_components:

******************************************
Enabling LTI Components for a Course
******************************************

Before you can add LTI components to your course, you must enable the LTI tool
in Studio.

To enable the LTI tool in Studio, add the ``"lti_consumer"`` module to the
**Advanced Module List** on the **Advanced Settings** page. For more
information, see :ref:`Enable Additional Exercises and Tools`.

.. note::
The ``lti_consumer`` module replaces a previous version of the LTI component.
The name of the module for the previous LTI component is ``lti`` and it may
appear in the **Advanced Module List** for older courses.

The ``lti_consumer`` module includes all of the functionality of the previous
LTI component and it should be used for all new courses. Courses that include
the previous LTI component will continue to work correctly, even if the
``lti`` module is no longer present in the **Advanced Module List**.

******************************************
=========================================
Adding an LTI Component to a Course Unit
******************************************
=========================================

To add an LTI component to a course unit, follow these steps.
To add an LTI 1.1 component to a course unit, follow these steps.

#. If the LTI tool requires authentication, register the key and shared secret
for the LTI tool in the configuration for your course. For more information
about registering authentication credentials, see :ref:`LTI Information`.
about registering authentication credentials, see
:ref:`Setting up a LTI 1.1 component`.

#. Edit the unit in which you want to add the remote LTI tool and select
**Advanced** from the **Add New Component** section. Select **LTI
Expand All @@ -217,6 +220,8 @@ To add an LTI component to a course unit, follow these steps.

#. Select **Edit** in the component that appears.

#. In the **LTI Version** field, select **LTI 1.1/1.2**.

#. Configure the LTI component in the component editor. For more information
about each setting, see :ref:`LTI Component settings`.

Expand All @@ -225,6 +230,147 @@ To add an LTI component to a course unit, follow these steps.
To test an LTI component, use the **Preview** feature or view the live version
in the LMS. For more information, see :ref:`Testing Your Course Content`.

.. _Setting up a LTI 1.3 component:

*******************************
Setting up an LTI 1.3 component
*******************************

To add an LTI 1.3 component to a course unit, follow these steps.

#. Edit the unit in which you want to add the remote LTI tool and select
**Advanced** from the **Add New Component** section. Select **LTI
Consumer**.

If the **Advanced** component type is not available, make sure you have
enabled LTI components. To do this, see :ref:`enable_lti_components`.

#. Select **Edit** in the component that appears.

#. In the **LTI Version** field, select **LTI 1.3**.

#. Enter the LTI 1.3 settings provided from your tool. For basic LTI 1.3
tools, without LTI Advantage, you need to set the following settings:

* **LTI 1.3 Tool Launch URL** (can also be called redirect url)
* **LTI 1.3 OIDC URL** (can also be called login url)

To enable *LTI Advantage* features, such as grades pass back and Deep Linking,
you also need to set **LTI 1.3 Tool Public Key** with a key provided by the
LTI tool. The key will look similar to this example:

.. code-block:: bash
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApAbQVx8FLXOflwvmV4dE
merOO/C+syqDG7MniysYzbMm+egZ8Z3Dq0e2YuggZlRSHVtT9TpTu6BrP7GyWrhH
7nOgCx5Rz+9g/B+KsasZ9x35bPjMeqNAu5aP3b0xgaRtnWec0h0a6T1L2xaQLuPS
bDTJhABs0d22OYmdlMNN0+fWPmqxxAz8t7DBmjMMAmPLG4tjyEOwKCBlYCx0WELP
Izg9bYA7MhCpHyD6+kTB51dbOA6lBbrIszCO9PBV4RD96LQWPs3YQ+DTqvPfLeTQ
Q9XwiOe7yzsG1Ml+dkUODpZbuBk5Z9X486l36WbRWGBDWIWlsNE7M9Nl3eS42oS4
IQIDAQAB
-----END PUBLIC KEY-----
You should paste the key from the tool directly into the configuration field.
For more information about each setting, see :ref:`LTI Component settings`.

#. Select **Save**.

#. The Studio page will refresh and display LTI configuration required by the
tool. Copy each of those values and follow the instructions provided by the
tool to set them up.

For basic LTI 1.3 launches, the following configuration values are required
(they are provided by the LTI tool being set up):

* **Client**
* **Deployment ID**
* **Keyset URL**
* **OIDC Callback URL** (some tools refer to this as launch or redirect urls).

For LTI Advantage, you'll also need to set **OAuth Token URL** (token/login url)
in the tool.

.. note:: LTI 1.3 launches only work with published blocks, make sure the block is
published before doing a launch.

.. _Enabling and using LTI Advantage features:

*****************************************
Enabling and using LTI Advantage features
*****************************************

LTI Advantage is an extension of the LTI 1.3 specification that enables additional
features in LTI components. See `LTI Advantage`_ for more information.

Currently, the platform supports the following LTI Advantage extensions:

* `Assignments and Grades services`_
* `Deep Linking`_


.. _Enabling LTI Assignments and Grades services:

============================================
Enabling LTI Assignments and Grades services
============================================

To set up LTI Assignments and Grades (LTI-AGS) services on a component, follow these steps.

#. Locate the unit and LTI component in which you want to enable LTI-AGS functionality.

#. Select **Edit** in the component that appears.

#. Locate the **LTI Assignment and Grades Service** setting.

#. Select the operation mode of the Assignments and Grades services. You can disable
the LTI-AGS service by selecting **Disabled** or pick one of the operation
modes available: *declarative* to allow only one grade per problem, or *programmatic*
to let the tool create many grades. For more information about each mode, read the
corresponding entry on :ref:`LTI Component settings`.

#. Select **Save**.

.. _Enabling and using LTI Deep Linking:

===================================
Enabling and using LTI Deep Linking
===================================

To set up LTI Deep Linking (LTI-DL) services on a component, follow these steps.

#. Locate the unit and LTI component in which you want to enable LTI-DL functionality.

#. Select **Edit** in the component that appears.

#. Locate the **Deep linking** setting and set it to **True** (enabled).

#. Locate the **LTI Advantage Deep Linking Launch URL** setting.

#. Retrieve the Deep Linking Launch url from the tool you're integrating with. If it's not
provided, try using the same value as in the **LTI 1.3 Tool Launch URL**.

#. Select **Save**. The Studio page will refresh and show the updated details page.

To use LTI Deep Linking, follow these steps:

#. Ensure that LTI-DL is enabled by following the steps above.

#. Locate the unit and LTI component in Studio.

#. In the LTI component page in Studio, locate the **Deep Linking Launch - Configure tool**
link and select it.

#. You'll be redirected to the Tool and presented with a page to select the options.

#. Once the configuration is complete, you'll be redirected back to the Studio and the
Deep Linking setup will be complete.

#. The content you selected in the tool will be presented to your students in the LMS.

.. note:: LTI 1.3 launches only work with published blocks, make sure the block is
published before doing a Deep Link Launch.

.. _LTI Component settings:

**********************
Expand All @@ -248,14 +394,58 @@ LTI Component Settings
requires a username or email address, use this field to inform learners
that their information will be forwarded to the external application.

* - LTI ID
* - LTI Version
- Used to select the LTI version used in for the current LTI component.

* - LTI ID (LTI 1.1 only)
- Specifies the LTI ID for the remote LTI tool provider. This value must
match the LTI ID that you entered as part of the LTI passport string for
the LTI tool. For more information about LTI passports, see :ref:`LTI
Information`.

* - LTI URL
* - LTI URL (LTI 1.1 only)
- Specifies the URL of the remote LTI tool that this component launches.

* - LTI 1.3 Tool Launch URL (LTI 1.3 only)
- Specifies the URL of the remote LTI tool that this component launches.
This is sometimes called *Redirect URL* in some tools.

* - LTI 1.3 OIDC URL (LTI 1.3 only)
- Specifies the URL of the login URL for the remote LTI tool for the
authentication flow. This can also be called *Login URL* on some tools.

* - LTI 1.3 Tool Public Key (LTI 1.3 only)
- The LTI 1.3 Tool's public key. This is a string that starts with
'-----BEGIN PUBLIC KEY-----' and is required so that the LMS can check if
the messages and launch requests received have the signature from the tool.
This is not required when doing LTI 1.3 Launches without LTI Advantage.

* - Deep linking (LTI 1.3 only)
- Toggle to enable or disable LTI Advantage Deep Linking. Select **True** if
the tool supports this feature and you want to use it in this component.

* - LTI Advantage Deep Linking Launch URL (LTI 1.3 only)
- Specifies the URL of the remote LTI tool that this component uses to perform
deep linking launches. If not specified by the tool, use the same URL as
in **LTI 1.3 Tool Launch URL**.

* - LTI Assignment and Grades Service (LTI 1.3 only)
- Toggle to enable LTI Advantage Assignment and Grades services and set the
grading model.

Options are:

* **Disabled** - LTI AGS service will be disabled. Use this for tools that
don't send any grades back to the platform.

* **Allow tools to submit grades only (declarative) (Default)** - the platform
will enable LTI AGS and prepare a single grade container for problems to
send grades back to. Use this for simple LTI problems.

* **Allow tools to manage and submit grade (programmatic)** - The tool will have
full control over the grading process, enabling it to create and edit one or
more grade containers and manage the learner scores that will be reported
to the LMS.

* - Custom Parameters
- Sends additional parameters that are required by the remote LTI tool.
Expand Down

0 comments on commit ed79509

Please sign in to comment.