lti.ptx

<section xml:id="lti_integration">
    <title>Integrating with your LMS Using LTI 1.1</title>
    <subsection>
        <title>Introduction</title>
        <note>
            <p>
                Runestone provides two methods of LTI integration. LTI 1.1 and LTI 1.3.  LTI 1.3 is the newer standard and is more secure and more flexible.  However, it requires setup by an administrator of your Learning Management System (LMS). LTI 1.1 can be set up by an individual instructor without LMS admin support. If you are using an LMS that your institution administers, we recommend you explore using LTI 1.3. If you are using something like <q>Canvas Free-for-Teacher</q> that does not provide administrator access, you will need to use LTI 1.1.
            </p>
            <p>
                If you wish to use LTI 1.3, skip to the instructions in <xref ref="lti1p3_integration"/>. If you are using LTI 1.1 then follow the instructions in this section.
            </p>
        </note>
        <p>
            Runestone provides a rudimentary LTI integration using LTI 1.1. So far we have made this work very successfully with Canvas, Moodle, and Brightspace D2L. Others may or may not work. I call this a community supported feature of Runestone because LTI is a huge pain to work with, and it is very difficult to get access to and test against whatever LMS your school has chosen. Community support is available on the <c>#lti_community_support</c> channel of the <url href="https://discord.com/channels/1013815439161315348/1023237792697954324" visual="Runestone Discord Server">Runestone Discord Server</url>.
        </p>
        <p> When you use LTI your students do NOT and <em>should not register on Runestone Academy</em>, the LTI interface registers your student with Runestone the first time they access it from your LMS. In addition, <em>Instructors need to use one of the LTI links to your book in order for grades to transfer.</em> </p>
    </subsection>
    <subsection>
        <title>Phase 1 (All LMS platforms)</title>
        <p>
            Generate a shared/secret key pair for use with Canvas:

            <ol>
                <li> Browse to the
                    <url href="https://runestone.academy" visual="Runestone Academy" />
 and log in, then select your course (you must be the Instructor).
                </li>
                <li>
                    <p>Browse to the
                        <url href="https://runestone.academy/runestone/admin/admin" visual="Instructor's Page" />
, then click on “LTI Integration” in the Admin tab.</p>
                    <image source="Figures/lti_config.png" description="LTI configuration panel" />
                </li>
                <li> Click on the <term>Create LTI Key and Secret</term> button. Click the <term>Show Secret</term> button. You will use these in the next phase. Note that there is also a <term>Remove LTI Key and Secret</term> if you can't get LTI working with your LMS or just decide you don't want to use it you should remove the keys.  This will allow your students to access assignments from the regular assignments page.</li>
                <li> Once the LTI Key and Secret have been set up, your course is in LTI mode, and the assignments will only be accessible from your LTI, so you must do Phase 2, below, or your students won't have access to any assignments.</li>
            </ol>
        </p>
    </subsection>

    <subsection>
        <title>Phase 2 (LMS-specific Steps)</title>
        <introduction>
            <p>
                Follow instructions for your LMS:
                <ul>
                <li><xref ref="lms-canvas-setup" text="title" /> </li>
                <li><xref ref="lms-moodle-setup" text="title" /> </li>
                <li><xref ref="lms-d2l-setup" text="title"/></li>
                </ul>
            </p>
        </introduction>

        <subsubsection xml:id="lms-canvas-setup">
            <title>Canvas</title>
            <ol>
                <li> Follow the
                    <url href="https://community.canvaslms.com/t5/Instructor-Guide/How-do-I-configure-a-manual-entry-external-app-for-a-course/ta-p/1137" visual="Canvas instructions" />
 to add an external app:

                    <pre>
    :Name: Runestone
    :Consumer key: Enter this from Phase 1.
    :Shared Secret: Enter this from Phase 1.
    :Launch URL: ``https://runestone.academy/runestone/lti``
    :Domain: Leave blank.
    :Privacy: Select Public; otherwise, Runestone won’t work.
    :Custom Fields: Depends on the installation type:

        -   For a site-wide installation, or for installing the Runestone external app for use across multiple courses, leave this blank.
        -   If installing for a single course, add ``custom_course_id=xxx``, where ``xxx`` is the Runestone ID of the course (visible in the upper lefthand corner of each page in your Runestone course).
    :Description: Interactive textbooks from Runestone Academy
                    </pre>
                </li>
                <li>
                    <p>Add an assignment in Canvas that uses the Runestone external tool:
                        <ol>
                            <li> At `Runestone Academy`_, create an assignment; be sure you’ve checked the “Visible to Students” box and saved that change.</li>
                            <li> Still on the assignments page, copy the LTI link.</li>
                            <li> In Canvas, add an assignment. For the submission type, select “External Tool.” For the External Tool URL, use the LTI link you just copied. You’ll have to manually enter the same due date/time and a similar assignment name; these aren’t copied automatically. You must be sure the Load This Tool In A New Tab checkbox is checked.</li>
                        </ol>
                    </p>
                    <li> Students can now click on this assignment and work it. **If they don’t click on the assignment, they won’t receive a grade.**</li>
                    <li> When the assignment is due, <em>go to Runestone directly from your Canvas course by using an assignment link</em>. Otherwise, grade reporting <em>won’t work</em>.</li>
                    <li> In the grading tab of the instructor interface, grade the assignment, then click the “Release Grades” button. Doing this will push all grades to Canvas.  (If you need to regrade later, you can always click the “Hide Grades” button, and then do “Release Grades” again.)</li>
                </li>
            </ol>
        </subsubsection>

        <subsubsection xml:id="lms-moodle-setup">
            <title>Moodle</title>
            <p>
                <ol>
                    <li> The following instructions are for Moodle, but should work for any LMS with LTI Support. Please note that certain items may have naming variations (ie. Moodle External Tool / Canvas External App).</li>

                    <li>
                        <p>In Moodle, create a new external tool called "LTI Login Link".</p>
                        <pre>
        :Name: Login to Runestone
        :Tool URL: https://yourHost.blahblah.edu/runestone/lti
        :Consumer key: Enter the key you copied for `consumer` from Phase 1
        :Shared secret: Enter the key you copied for `secret` from Phase 1
        :Icon URL: https://yourHost.blahblah.edu/runestone/static/images/logo_small.png
        :Share Email: True
        :Share Name: True
        :Custom params: custom_course_id=xxx, where xxx is the Runestone ID of the course (visible in the upper lefthand corner of each page in your Runestone course).
                        </pre>
                    </li>
                    <li> Login to your Runestone instance with the tool just created, and create your class as well as your assignments.</li>

                    <li>
                        <p> In Moodle, create a new enrollment external app directly to your course and assignment. You will need to repeat this for each assignment. You will also need the database values for your course ID, and assignment ID. Get these from step 2.2. Please note that in order to receive roles and grades, "Accept Grades" must be checked in Moodle. In other LMS's this may be referenced by a "Share IMS Names and Roles" or similar.</p>
                        <p> Note: in order for students to have access to the assignment from moodle, the visible checkbox for the assignment on runestone must be checked.</p>                        
<pre>
        :Name: Assignment 1
        :Tool URL: https://runestone.colorado.edu/runestone/lti?assignment_id=&amp;custom_course_id
        :Consumer key: Enter the key you copied for `consumer` from Phase 1
        :Shared secret: Enter the key you copied for `secret` from Phase 1
        :Icon URL: https://yourHost.blahblah.edu/runestone/static/images/logo_small.png
        :Share Email: True
        :Share Name: True
        :Custom params:
        :Accept Grades: True
                        </pre>
                    </li>
                    <li> Copy the tool as many times as you need within your Moodle Course, updating the Name and Tool URL each time.</li>

                    <li> Students can now click on these external tool assignments to be enrolled/logged directly into your Runestone course and assignment. The grades should appear in Moodle once they are released in Runestone through the Instructor interface using the “Release Grades” button.  (If you need to regrade later, you can always click the “Hide Grades” button, and then do “Release Grades” again.)</li>

                    <li> The course instructor must also be an LTI sourced user, <em>so use the "LTI Login Link" URL</em>. This can be hidden for users.</li>
                </ol>
            </p>
        </subsubsection>


    <subsubsection xml:id="lms-d2l-setup">
        <title>Brightspace D2L</title>
         <p>Depending on how D2L is set up, you may need to be an administrator in order to set up your links for class. However, in some setups, instructors have permission to make their own LTI links.
            </p>
            <ol> <li>
                <p>
                    To check, while in your class on D2L, you can go to <term>Course Admin</term> - <term>External Learning Tools</term>, then click the <term>Manage Tool Links (Legacy)</term>. From there, click the <term>New Link</term> button.
                </p>
            </li>
             <li> <p>If that is successful, then here are the settings. <em>(Otherwise, talk to your LMS Admin to configure this for you)</em> </p>
                    <dl>
                    <li>
                    <title>Title</title>
<p>Enter either the Textbook Name or the assignment name on Runestone</p></li>
<li><title>URL</title> <p> copy this from the LTI configuration panel for the textbook login <term>https://runestone.academy/runestone/lti</term> or from the individual assignment in the Assignments tab of the Instructor's Page.</p></li>
<li><title>Description</title> <p> Leave blank or add a description.</p></li>
<li><title>Visibility</title> <p> Allow users to view the link should be checked.</p></li>
<li><title>Key/Secret</title> <p></p></li>
<li><title>Signature</title> <p> check <term>Sign messages with key/secret with</term> </p><p> select <term>Link key/secret</term></p><p> then fill in </p></li>

<li><title>Key</title> <p> Enter this from Phase 1.</p></li>
<li><title>Secret</title> <p> Enter this from Phase 1.</p></li>
                    </dl>
                </li>
 <li><p>Click the <term>Save</term> button before adding custom parameters.</p>

                 <dl>

<li><title>Custom Parameters</title> <p> </p></li>

    <li>   click the <term>Add custom parameters</term> link.</li>
       <li><title>Name</title> <p> <term>custom_course_id</term></p></li>
       <li><title>Value</title> <p> the Runestone ID of the course (visible in the upper lefthand corner of each page in your Runestone course).</p></li>

<li><title>Security Settings</title> <p>Select <term>use link security settings</term></p></li>

<li><p>
Make sure at least the following settings are checked:</p>

<ul>
    <li> Send tool consumer information to tool provider</li>
    <li> Send context information to tool provider </li>
    <li> Send LTI user ID and LTI role list to tool provider </li>
    <li> Send user name to tool provider </li>
    <li> Send user email to tool provider </li>
    <li> Send link title to tool provider </li>
    <li> Send link description to tool provider </li>

    </ul></li> </dl></li>


            <li> Once everything is selected, click <term>Save and Close</term> </li>

                <li>
                    Now, from anywhere in your course, you can select  <term>Existing Activities</term> - <term>External Learning Tools</term> and then the link you created. After adding this link, make sure that you make sure the link is configured to <term>Open as External Resource</term>. That way the right information will be passed to the textbook.
                </li>

            <li> Students will be able to click on this link when you make it available to them <em>as long a the <term>Visible to Students</term> checkbox is checked on the assignment in runestone. </em></li>
            <li> When the assignment is due, go to Runestone <em>directly from your D2L course by using an assignment link</em>. Otherwise, grade reporting <em>won't work</em>.</li>
            <li> In the grading tab of the instructor interface click the <term>Release Grades</term> button. Doing this will push all grades to D2L.  (If you need to regrade later, you can always click the “Hide Grades” button, and then do “Release Grades” again.)</li>
            </ol>

    </subsubsection>
    </subsection>
</section>