From fab1a635c4a24d6f06bd465bae53c28262ea7311 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Wed, 14 Apr 2021 15:12:08 -0300 Subject: [PATCH 1/6] docs: Update LTI component documentation * Add LTI 1.3 and LTI Advantage documentation * Reorganize docs Signed-off-by: Giovanni Cimolin da Silva --- en_us/links/links.rst | 12 +- .../shared/exercises_tools/lti_component.rst | 160 ++++++++++++++---- 2 files changed, 134 insertions(+), 38 deletions(-) diff --git a/en_us/links/links.rst b/en_us/links/links.rst index c7fb71adc2..45f389800f 100644 --- a/en_us/links/links.rst +++ b/en_us/links/links.rst @@ -373,10 +373,17 @@ .. _python-social-auth backend documentation: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends -.. _IMS LTI 1.1 Consumer Launch: http://www.imsglobal.org/developers/LTI/test/v1p1/lms.php +.. _IMS LTI 1.1 Consumer Launch: https://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 @@ -606,4 +613,3 @@ .. _Stanford Online xqueue_pull_ref: https://github.com/Stanford-Online/xqueue_pull_ref .. _Mozilla Firefox: https://www.mozilla.org/en-US/firefox/new/ - diff --git a/en_us/shared/exercises_tools/lti_component.rst b/en_us/shared/exercises_tools/lti_component.rst index bde7263e86..5fe27b323e 100644 --- a/en_us/shared/exercises_tools/lti_component.rst +++ b/en_us/shared/exercises_tools/lti_component.rst @@ -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: @@ -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. + +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**. + -****************************** -LTI Authentication Information -****************************** +.. _Setting up a LTI 1.1 component: -Some LTI tools require users to provide authentication credentials. If the LTI +******************************* +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. @@ -155,7 +180,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 @@ -175,38 +200,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. #. 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 @@ -217,6 +221,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`. @@ -225,6 +231,46 @@ 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 +******************************* + + + +.. _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 imformation. + +Currently, Open edX supports the following LTI Advantage extensions: + +* `Assignments and Grades services`_ +* `Deep Linking`_ + + +.. _Enabling LTI Assignments and Grades services: + +============================================ +Enabling LTI Assignments and Grades services +============================================ + +TBD LTI AGS setup and usage + + +.. _Enabling and using LTI Deep Linking: + +=================================== +Enabling and using LTI Deep Linking +=================================== + +TBD LTI DL setup and usage + .. _LTI Component settings: ********************** @@ -248,14 +294,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)** - LTI AGS is enabled + and 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 linked to the LMS. * - Custom Parameters - Sends additional parameters that are required by the remote LTI tool. From b3d4651409fac9734150eaeeb468d7f627e15449 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Tue, 20 Apr 2021 17:54:25 -0300 Subject: [PATCH 2/6] Finish writing docs --- .../shared/exercises_tools/lti_component.rst | 107 +++++++++++++++++- 1 file changed, 103 insertions(+), 4 deletions(-) diff --git a/en_us/shared/exercises_tools/lti_component.rst b/en_us/shared/exercises_tools/lti_component.rst index 5fe27b323e..6f0b594f68 100644 --- a/en_us/shared/exercises_tools/lti_component.rst +++ b/en_us/shared/exercises_tools/lti_component.rst @@ -205,7 +205,7 @@ field, and displays a notification that your changes have been saved. 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 @@ -237,7 +237,62 @@ in the LMS. For more information, see :ref:`Testing Your Course Content`. 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 see to set **LTI 1.3 Tool Public Key** with a key provided by the + LTI tool. An example key is shown below, and should be pasted directly in + the configuration field. + + .. 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----- + + 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 variables are required: + + * **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: @@ -260,8 +315,20 @@ Currently, Open edX supports the following LTI Advantage extensions: Enabling LTI Assignments and Grades services ============================================ -TBD LTI AGS setup and usage +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 tho operation + modes available. For more information about each mode, read the corresponding + entry on :ref:`LTI Component settings`. + +#. Select **Save**. .. _Enabling and using LTI Deep Linking: @@ -269,7 +336,39 @@ TBD LTI AGS setup and usage Enabling and using LTI Deep Linking =================================== -TBD LTI DL setup and usage +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 LMS 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: @@ -333,7 +432,7 @@ LTI Component Settings - Toggle to enable LTI Advantage Assignment and Grades services and set the grading model. - Options are: + Options are: * **Disabled** - LTI AGS service will be disabled. Use this for tools that don't send any grades back to the platform. From e7c728877f0ff53392cdfa68e34297bc299dd8a0 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Mon, 26 Apr 2021 11:38:20 -0300 Subject: [PATCH 3/6] docs: Address review comments --- .../shared/exercises_tools/lti_component.rst | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/en_us/shared/exercises_tools/lti_component.rst b/en_us/shared/exercises_tools/lti_component.rst index 6f0b594f68..5db147081a 100644 --- a/en_us/shared/exercises_tools/lti_component.rst +++ b/en_us/shared/exercises_tools/lti_component.rst @@ -81,7 +81,7 @@ 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 +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`. @@ -158,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: @@ -257,9 +256,8 @@ To add an LTI 1.3 component to a course unit, follow these steps. * **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 see to set **LTI 1.3 Tool Public Key** with a key provided by the - LTI tool. An example key is shown below, and should be pasted directly in - the configuration field. + 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 @@ -273,15 +271,17 @@ To add an LTI 1.3 component to a course unit, follow these steps. 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 +#. 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 variables are required: + 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** @@ -303,7 +303,7 @@ 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 imformation. -Currently, Open edX supports the following LTI Advantage extensions: +Currently, the platform supports the following LTI Advantage extensions: * `Assignments and Grades services`_ * `Deep Linking`_ @@ -324,9 +324,10 @@ To set up LTI Assignments and Grades (LTI-AGS) services on a component, follow t #. 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 tho operation - modes available. For more information about each mode, read the corresponding - entry on :ref:`LTI Component settings`. + 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**. @@ -362,7 +363,7 @@ To use LTI Deep Linking, follow these steps: #. 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 LMS and the +#. 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. @@ -407,7 +408,7 @@ LTI Component Settings * - 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. + 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 @@ -441,10 +442,10 @@ LTI Component Settings 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)** - LTI AGS is enabled - and 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 linked to the LMS. + * **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. From 8a7de487606bb4aa973deb9397cd67033c2b87e5 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Mon, 26 Apr 2021 11:44:51 -0300 Subject: [PATCH 4/6] fix: Fix quality issue --- en_us/shared/exercises_tools/lti_component.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en_us/shared/exercises_tools/lti_component.rst b/en_us/shared/exercises_tools/lti_component.rst index 5db147081a..3a94a5f915 100644 --- a/en_us/shared/exercises_tools/lti_component.rst +++ b/en_us/shared/exercises_tools/lti_component.rst @@ -445,7 +445,7 @@ LTI Component Settings * **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. + to the LMS. * - Custom Parameters - Sends additional parameters that are required by the remote LTI tool. From a5d4d86c10964111724c1d851dae3a4d4f436260 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Tue, 27 Apr 2021 10:54:46 -0300 Subject: [PATCH 5/6] Update en_us/shared/exercises_tools/lti_component.rst Co-authored-by: Ned Batchelder --- en_us/shared/exercises_tools/lti_component.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en_us/shared/exercises_tools/lti_component.rst b/en_us/shared/exercises_tools/lti_component.rst index 3a94a5f915..30e7ef40fa 100644 --- a/en_us/shared/exercises_tools/lti_component.rst +++ b/en_us/shared/exercises_tools/lti_component.rst @@ -301,7 +301,7 @@ 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 imformation. +features in LTI components. See `LTI Advantage`_ for more information. Currently, the platform supports the following LTI Advantage extensions: From a3e113c58fdad6c6cadaf96d96f28186513c1952 Mon Sep 17 00:00:00 2001 From: Giovanni Cimolin da Silva Date: Wed, 28 Apr 2021 16:51:55 -0300 Subject: [PATCH 6/6] fix: Revert change in LTI Provider URL --- en_us/links/links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en_us/links/links.rst b/en_us/links/links.rst index 45f389800f..e0b2635c09 100644 --- a/en_us/links/links.rst +++ b/en_us/links/links.rst @@ -373,7 +373,7 @@ .. _python-social-auth backend documentation: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends -.. _IMS LTI 1.1 Consumer Launch: https://www.imsglobal.org/developers/LTI/test/v1p1/lms.php +.. _IMS LTI 1.1 Consumer Launch: http://www.imsglobal.org/developers/LTI/test/v1p1/lms.php .. _LTI 1.1: https://www.imsglobal.org/LTI/v1p1p1/ltiIMGv1p1p1.html