LTI - Release 2.1.0 Notes

Owned by Former user (Deleted)
Last updated: Dec 07, 2021 by Wilma HodgesVersion comment
6 min read

Overview

The latest tag for LTI 2.1.0 is https://source.sakaiproject.org/svn/basiclti/tags/basiclti-2.1.0/

Video: Demonstrating test scenarios and features for LTI 2.1.0 (YouTube)

The Sakai LTI 2.1.0 release provides a release that greatly enhances administrator control over the tool placements created by the Site Info and LessonBuilder as well as bringing support for all of the IMS LTI 1.1 plus Sakai extensions to both the placements in LessonBuilder and the External Tools Portlet.   Many bugs were also fixed.  The Basic LTI 2.0.0 that shipped with Sakai 2.9.0 was only the minimum functionality that was needed to support the LessonBuilder uses cases to support IMS Common Cartridge 1.1 import.   This release flushes out the entirety of IMS LTI 1.1 and lays the foundation to start working on IMS LTI 2.0 (yes the Sakai software version numbers and IMS specification version numbers are not well lined up).

The Sakai LTI Release 2.1.0 is the default version of LTI shipped with the Sakai 2.9.2 release

LTI Administration Feature

This release greatly improves the ability for administrators to place tools for users without restarting the server.  This feature was introduced in LTI 2.0.0 and improved in this release. In order to make use of this feature, you need to add a new page to the !admin site and add the sakai.basiclti.admin tool to the page.   Then you can create (i.e. install) LTI tools to be used within Lessons and Site Info.  The link below is how the tool looks in 2.1.0 - it is greatly improved over the tool in 2.0.0 with the addition of paging search and many other features developed at the University of Michigan after a usability analysis of the tool as initially developed for 2.0.0.

If you don't already have the External Tools Administration tool in your !admin site, you can either add the tool to the !admin site manually or do it with the following SQL commands:

INSERT INTO SAKAI_SITE_PAGE (PAGE_ID,SITE_ID, TITLE, LAYOUT, SITE_ORDER, POPUP) 
     VALUES ('!admin-1200-blti-page','!admin', 'External Tools', 0, 16, 0) ;

INSERT INTO SAKAI_SITE_TOOL (TOOL_ID,PAGE_ID,SITE_ID, REGISTRATION,PAGE_ORDER,TITLE ) VALUES 
    ('!admin-1200-blti-tool','!admin-1200-blti-page', '!admin', 'sakai.basiclti.admin' , 1, 'External Tools'

I did not include these in the conversion scripts below to give you a choice in how to use (or don't use the LTI admin interface).  Or perhaps you have already done this and I did not want to add a second copy of the tool to the !admin site.

Property Change

There is one new property that enables the encryption of the LTI secrets in the database and sets the encrypt/decrypt key for those columns.  This encryption key applies both the the External Tool portlet and the content items creates with the LTI administration tool wither in Site Info or the Admin workspace.

basiclti.encryption.key=280932732498734987498734987

Do not lose this key.  If you turn on encrypted secrets and lose this key - there is no way to recover the secrets.   It is a two-way encryption but without the secret, decrypting is not possible.  Once you turn this on, you should leave it on.    You are warned in the log if this key is not set after LTI 2.1.0:

2013-03-13 18:32:04,217  WARN Thread-2 org.sakaiproject.basiclti.impl.BasicLTISecurityServiceImpl - BasicLTI secrets in database unencrypted, please set basiclti.encryption.key

 It is recommended but not essential that you turn basiclti.encryption.key on.

Database Conversion

If you simply start Sakai with autoDDL=true in your sakai.properties the LTIService will automatically detect missing columns and issue ALTER commands to fix the columns as needed as the version LTI 2.1.0 service starts up for the first time.  If you start Sakai with autoDDL=false, it will notice that the tables need to be changed and spam the log ERROR messages indicating the needed SQL statements to bring the tables up to LTI 2.1.0 - the messages look as follows:

2013-03-12 18:16:01,774  INFO Thread-2 org.sakaiproject.basiclti.impl.BasicLTISecurityServiceImpl - org.sakaiproject.basiclti.impl.BasicLTISecurityServiceImpl@261e70ac.init()
2013-03-12 18:16:01,799 ERROR Thread-2 org.sakaiproject.lti.impl.DBLTIService - SQL Needed:
ALTER TABLE lti_content ADD     pagetitle VARCHAR(255) NOT NULL
2013-03-12 18:16:01,799 ERROR Thread-2 org.sakaiproject.lti.impl.DBLTIService - SQL Needed:
ALTER TABLE lti_content MODIFY     launch TEXT(1024)
2013-03-12 18:16:01,799 ERROR Thread-2 org.sakaiproject.lti.impl.DBLTIService - SQL Needed:
ALTER TABLE lti_content ADD     consumerkey VARCHAR(255)
...

If you see these messages and try to use the LTI Admin tool or LTI from within LessonBuilder - it will almost certainly blow up very quickly as it will expect columns that will not be there.  The LTI (External Tool) portlet does not depend on these tables as it stores all of its data in the placement as properties so it will happily work with or without this conversion being run.

If you want to run the conversaion manually so you never have to use autoDDL you can use these conversion scripts

These scripts are in SVN in basiclti/notes These scripts were generated by simply taking a Sakai 2.9.0 database with Basic LTI 2.0.0 and bringing up Basic LTI 2.1.0 with autoDDL=false and extracting the recommended ALTER statements from the log and adding the ALTER statements from BLTI-208.

Note: If you are using some version of LTI between 2.0.0 and 2.1.0 because you have been pulling modifications from trunk all along, simply start with autoDDL=true and let the columns get created automatically or start with autoDDL=false and pull out the ALTER statements from catalina.out and apply them by hand.  The ORM run-time that underlies LTI looks at the table and computes the necessary ALTER statements to move it from wherever it is to 2.1.0 (i.e. the autoDDL conversions are not hard-coded) - the ORM figures out which columns are missing or even needs the length or type adjusted and makes ALTER commands to fix the database.  You can also run this conversion script even if you have done some of the conversions already through autoDDL.   Since it is simply ALTER commands it can be run more than once with no harmful effect.

If you have been using LTI Placements in Lessons and want to enable API access for those placements, you will have to run one more command to set the newly created placementsecret column in the lti_content table.  The placementsecret is independent of the launch secret and insures fine-grained control of whether we give a tool access to the outcomes API.  You can check if you have blank placement secrets with the following command:

select title,placementsecret from lti_content;

Most 2.9.x installations will have no lti_content rows unless they have already been using Lessons+LTI heavily or have been tracking the trunk of LTI.  The following  the columns in each lti_content row each to a suitably different random number:

MySql:
 
update lti_content set placementsecret=rand() where placementsecret is null;
 
Oracle:
 
update lti_content set placementsecret=dbms_random.random where placementsecret is null;

For tools and content items created after the LTI 2.1.0 upgrade, the placementsecret is generated automatically - this SQL command is only needed once.

New Site Info Improvements (Optional)

The new tool also articulates with some very nice improvements to Site Info in trunk that nicely manages the ability for users to add these new kind of pre-configured tools to their sites.  That code is in the trunk of Site Info (2.10-SNAPSHOT) and is not part of the LTI 2.1.0 release - but interested schools may want to separately back-port the changes to Site Info described in

  BLTI-142 - Getting issue details... STATUS  and  SAK-22108 - Getting issue details... STATUS  

If you upgrade Site Info - you will need LTI 2.1.0 as the newest Site Info in 2.10-SNAPSHOT depends on the new features in LTI 2.1.0.  Moving to LTI 2.1.0 does not require that Site Info be upgraded.  This could be upgraded at a later date long after LTI 2.1.0 is in place.   Once LTI 2.1.0 is in place, it will run properly with either the Site Info in 2.9.x or the Site Info in trunk (2.10-SNAPSHOT).

Testing / Test Plans

Here is the test plan https://source.sakaiproject.org/svn/basiclti/trunk/basiclti-docs/resources/docs/BLTI_TestPlan.xls

Testing Notes

You can go back and forth between the LTI 2.1.0 and LTI 2.0.0 code pretty trivially.  The 2.0.0 code will run run fine after the 2.1.0 database conversions have been run.  The only thing that will not work is if you have edited tools or portlet data in a way to cause the secrets to get encrypted.   LTI 2.0.0 will have no idea what to do with encrypted secrets.  You do need to remove these files from your Tomcat when you switch back and forth:

-rw-r--r--  1 csev  staff  5575 Mar 15 09:36 shared/lib/basiclti-api-2.0.2-SNAPSHOT.jar
-rw-r--r--  1 csev  staff  3703 Mar 15 09:36 shared/lib/basiclti-help-2.0.2-SNAPSHOT.jar

Of course the version is different - just remove all the "basiclti*.jar" files and re-compile/deploy whichever version you like.

JIRA Issues Addressed in LTI 2.1.0

There are quite a few fixes that are addressed in 2.1.0

key summary resolution updated

Unable to locate Jira server for this macro. It may be due to Application Link configuration.