[BD-24] Add LTI 1.3 documentation and reorganize docs

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/
-

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.
 
-******************************
-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.
 
@@ -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:
 
@@ -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
@@ -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
@@ -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`.
 
@@ -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 imformation.
+
+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:
 
 **********************
@@ -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.