Show Advanced KnowledgeHide Advanced Knowledge

ILIAS as LTI tool provider

This requirement has originally been made on the page LTI Support in ILIAS and later moved to a special wiki page for not mixing the two aspects of offering and integrating tools via LTI.

1 Requirements

ILIAS could be a LTI tool provider and allow to use ILIAS components like the test, survey or wiki in another LMS or CMS. The following concept is based on a workshop with L&M Software, Matthias Kunkel and Fred Neumann at the ILIAS office on April 21, 2015.

A new service in ILIAS should allow the integration of selected ILIAS objects in external tools with LTI. The service should support an LTI 1.1 interface for calling the following objects in ILIAS:

• SCORM module
• Test
• Survey
• Course (this would include a display of all course contents within the LTI Kiosk mode)

This document describes the needed changes in ILIAS to support LTI 1.1 as an LTI provider.

See also: Specification (Implementation Guide) of IMS LTI 1.1

1.1 ILIAS Administration

See: Administrating ILIAS as an LTI-Provider

1.2 Object Administration

Each repository object supporting LTI has an own tab or sub tab for the LTI specific settings.

See: New Objects-Settings for LTI-Provider

Later extensions of the LTI interface may add the generation of a “Common Cartridge” package. Such a package includes the link, an icon, title and description and vendor information. A Common Cartridges can include a couple of LTI links and may be generated in a container for all child objects with activated LTI. This extension is not needed for the initial implementation.

1.3 LTI Launch

The LTI launch link can look similar to the permanent link of a repository object. It is used for POSTrequests. The client_id and ref_id are included in the launch link and provided as GET variables. All other parameters are provided by the Tool Consumer as OAuth signed POST variables.

ILIAS checks the OAuth signature by looking up the consumer key in the target object or in the global credentials table. It checks the related user account (see user management) and permissions on the target object.

An error may occur in the following cases:

• The LTI request can’t be authentified by key and secret oImportant LTI parameters are missing
• The user account exists and is deactivated (e.g. to block users)
• The target object is not found, is deleted or offline
• LTI is not activated for the target object
• The permissions of the LTI roles are not sufficient for viewing the target object

If a return URL is provided with the LTI launch then ILIAS redirects to this URL and adds the error message as a parameter. If no return URL is provided, then ILIAS shows its standard error page.

If everything is ok, then ILIAS:

• Creates or updates the LTI user account (see below) and automatically logs it in
• Saves the launch parameters that are needed for a further processing (outcome service)
• Activates the LTI Kiosk Mode (see below)
• Calls the _goto() function of the target object

See: LTI Authentication

1.4 User Management

LTI users are created on the fly when an ILIAS object is launched by LTI. For this purpose ILIAS generates a deterministic login name, based on the following components:

• Globally defined LTI prefix (see ILIAS Administration)
• LTI parameter consumer_key
• LTI parameter user_id (recommended) or resource_link_id (if user_id is not provided)

If a user with this login name does not exist and LTI access to the target object is potentially possible then the user account is created. The password is set to a random value to prevent a direct login in ILIAS. Other profile fields are filled with parameters provided in the LTI launch:

• lis_person_name_given
• lis_person_name_family
• lis_person_contact_email_primary
• picture downloaded from the URL given by user_image

The user is automatically added to the global LTI user role (that should guarantee a readable path to the target object) and the local role of the target object. The local role is selected based on the LTI parameter roles:

• Course Tutor or LTI Instructor for users with an LTI role Instructor
• Course Member or LTI User for all other LTI users

The user agreement is automatically accepted and no time limit is set for the user (decided at the workshop).

The LTI interface needs to store launch parameters and maintain a retry list for calling the outcome service. These records are assigned to LTI users. When an LTI user is deleted then all assigned records should be deleted from these lists.

See: LTI User Management

1.5 LTI Kiosk Mode

When ILIAS is launched by LTI, the user interface should be reduced. This “LTI Kiosk Mode” should be activated in the user’s session for all subsequent requests:

• The main header is replaced with a minimalistic one, similar to the ‘Member View’ for course administrators
• The ILIAS Footer is hidden
• The side bar is hidden on repository pages
• The breadcrumb starts at the launched object
• If the LTI parameter launch_presentation_css_url is provided, then ILIAS adds this css file on all pages (as the last css file in the sequence).

The reduced main header has a button to finish the LTI session and log out the user. The further action of this button is controlled by the LTI launch_presentation_return_url:

• If a return URL is given, then ILIAS redirects to this URL
• Otherwise ILIAS shows a ‘finished’ page with a button to restart the LTI session

See: LTI Kiosk Mode

1.6 Outcome Service

LTI 1.1 specifies an Outcome Service that can be called by the Tool Provider so send back a grade value between 0 and 1. The URL of this service is provided with the LTI launch. The service is asynchronously called when the status or grade changes.

The outcome value determined by ILIAS depends on the object type:

• SCORM modules directly provide a score
• Tests provide the percentage of correct answers
• All other objects can provide a value, if the learning progress is activated:
  • Status changes to ‘not started’ or ‘in progress’ will not send a value
  • A status change to ‘failed’ will send 0
  • A status change to ‘completed’ will send 1

The call of the outcome service may fail, e.g. to a missing connection or timeout. To allow a retry ofsending the outcome, a new cron job is defined in ILIAS. The cron job can be activated/deactivated and edited with the following settings:

• Frequency
• Number of retries

The ‘replaceResult’ function of the outcome service is called every time the user’s score or status changes in the target object. If the cron job is activated, then a failed request will be put on a retry list. The successful sending of a following status change will delete a previous entry from the list.

Requirements as FILE

2 Contact

• Idea / concept: Neumann, Fred [fneumann]
• Maintainer: Kohnle, Uwe [ukohnle]
• Implementation of the feature is done by Meyer, Stefan [smeyer], Kohnle, Uwe [ukohnle]

3 Discussion

Kunkel, Matthias [mkunkel], June 08, 2015: A concept paper about ILIAS as LTI provider has been written and uploaded by Fred Neumann in chap 2.

Killing, Alexander [alex], 27 June 2015: I have read the paper about ILIAS as a LTI provider. The paper describes the basic requirements and outlines the basic configuration and processes. But it lacks a clear definition of a central LTI service and its interfaces for other components. This is necessary to get an idea about the effort that is needed to integrate the service into its consuming components like the test or the survey. In my opinion we need a specification of this LTI service and someone that implements it and takes over the maintainership.

Neumann, Fred [fneumann], 28 June 2015:
The concept paper for ILIAS as LTI provider is intended as a requirements definition for the external behavior of an LTI service. This is already approved by the potential funder L&M. For the next steps we should follow an iterative process:

1. First the maintainers of the related services and modules can check if they have objections or suggestions for changes in functionality. On this basis the Jour Fix can decide on the feature as such and it can also clarify who will be involved in the next step.
2. The service and its interfaces to other ILIAS components can be designed. This step needs funding and therefore it should start after the feature is appreciated in the JF.

Regarding the interfaces to other ILIAS components I see the following dependencies:

• The global LTI settings have to be presented in the administration area.
• The LTI settings per object have to be accessible (I suggest a sub tab of “Permissions”).
• The Kiosk mode must be respected. This already works well for the “Member view” in courses and therefore I suggest to extend this concept (e.g. as a set of “presentation modes” in the UICore service).
• The LTI service must be notified about LP changes in the objects. Here I suggest using event handlers.
• The cron job for the LTI outcome service has to be presented in the list of cron jobs.

As far as I see all other dependencies would be the use of other components by the LTI service.

Neumann, Fred [fneumann], September 13, 2015: Some answers to questions given by Uwe Kohle (questions shortened and translated).

Why not LTI 1.2 or 2.0?
 
We start with LTI 1.1 which is a widely adopted version and fulfils all requirements of the funding organization. It is a rather leight-weight protocol and therefore a good entry point. LTI 1.1.1 would just add a “mentor” role support. LTI 1.2 is declared as a step towards LTI 2.0 and would require an additional REST service implementation.
 
Why is the user agreement automatically accepted and no time limit set?
 
LTI is based on a trust between the tool provider and tool consumer system. We assume that the user agreement is already done correctly in the tool consumer. The launch of a tool provider should be as seamless as possible (e.g. display in an iframe of the tool consumer).
For the same reason no time limit is set. But we can think of a time limit as an option that is bound to a consumer key and secret pair.
 
How can the LTI users be identified (e.g. for clean-up)?
 
LTI users are identified in two ways: 1) they are members of the global LTI user role that is selected in the LTI administration. 2) their user name has a prefix that can be specified in the global user administration.
 
Multi-SCOs in SCORM modules do not necessarily provide a direct score. It has to be selected if the working progress or a score should count.
 
The Outcome Service specification of LTI 1.1 just declares an outcome value between 0.0 and 1.0 and names it “grade”.
Most ILIAS objects only provide the learning progress status as a source for this value which would then only be 0 or 1. It should only be sent when the final status of an object is reached, i.e. “failed” or completed”.
This default behavior may be overwritten by objects that can provide a more precise value. But according to LTI 1.1 it should always be a grade between 0 and 1. Any suggestion for SCORM modules is welcome.
 
The LTI specification allows the outcome service being called any time. Can that lead to problems with timed-out sessions?
 
I think not. The calls of the outcome service are stateless and provide their own OAuth bases authentication. The authentication parameters for this outcome call are provided at the LTI launch and have to be stored by ILIAS. The standard launch may be done directly when the learning progress status changes. If that fails it is scheduled for a cron job based retry.

Kohnle, Uwe [ukohnle], September 14, 2015:
Hi Fred,

now you were faster than me. But you have forgotton the most important part of my mail: the concept really makes a very well-rounded impression and that it makes sense, is for me no question.

If it is possible i would integrate LTI 1.2. LTI 2.0 could be ignored now.

For SCORM the status 'failed' might result in a score=0.

It would be sufficient to set the user agreement automatically if the user agreement is done correctly by the tool consumer.

JourFixe, ILIAS [jourfixe]: September 28, 2015: Fred Neumann gave a presentation of the current concept to extend ILIAS towards becoming an LTI tool provider. There are still some open questions that should be clarified:

• To identify the consumer we could think about a consumer prefix per institution similar to the ECS implementation
• Activation of LTI per object should happen in the object settings and additional administration should take place in a separate tab.
• Course mails have to be deactivated for LTI users (similar problem as ECS) because LTI user cannot consume permalinks / courselinks as they do not enter ILIAS via login but via other installation.
• A global setting per installation should be offered to accept the user agreement.
• In a whitelist it has to be defined which objects support LTI and can be used via LTI (at the time being: course, test, survey, SCORM LM). Other objects are not displayed by the container. The whitelist can be extended in accordance with the responsible module maintainer.

We highly appreciate the concept and schedule the feature for 5.2. Stefan Meyer and Uwe Kohnle are interested in becoming both LTI maintainer and will take over the specification and coordination activities from Fred Neumann. The open questions should be discussed in one of the next Jour Fixes.

Neumann, Fred [fneumann] September 29, 2015: I propose an easy extension of the whitelist of supported course contents, perhaps to implement it on configuration level (e.g. settings table with defaults by dbupdate). This gives interested admins the possibility to test an extended list without code changes.

I believe many course contents will work fine in the LTI kiosk as they already do in the member view. The main potential problem mentioned in the JF was the display of ILIAS in an iframe of the Tool Consumer. The LTI implementation guide describes this (UseCase LTIv1p1-04):

1. The TC User clicks on the link in the TC UI.
2. The tool or content from the TP appears in the TC UI or in another window. 
   

This may be a problem when ILIAS links have target="_top" in some modules. On the other hand, many LTI settings will not use an embedding but open ILIAS in a new window or open it in the same window and provide a return url. In such a case a small whitelist would be an unneccessary restriction. The description for extending the whitelist can be given with a "handle with care" message and a link to a feature wiki page for collecting experiences and suggestions for "official" extensions.

JourFixe, ILIAS [jourfixe], July 24, 2017: We highly appreciate the feature request to make ILIAS an LTI tool provider. Scheduling the entire feature depends from the last request New Objects-Settings for LTI-Provider that will be discussed on July 31.

JourFixe, ILIAS [jourfixe], July 31, 2017: After acceptance of New Objects-Settings for LTI-Provider the general feature request for ILIAS as tool provider can be scheduled for 5.3.

4 Implementation

The Implementation is not completely finished (ILIAS 5.3). Many ILIAS objects are not yet considered.
The Implementation is described in these Articels:

• Administrating ILIAS as an LTI-Provider
• LTI User Management
• New Objects-Settings for LTI-Provider
• LTI-Outcome-Service

You can find technical details also here:

• LTI Authentication
• LTI Kiosk Mode

To clarify the outcome service: In general and if the learning progress is activated:

• Status changes to ‘not started’ or ‘in progress’ will not send a value
• A status change to ‘failed’ will send 0
• A status change to ‘completed’ will send 1

SCORM does not provide a score because there is in most cases no mechanism to get an overall score for learning modules with more than one SCO.

Test Cases

Test cases completed on 2017-08-27 by Tödt, Alexandra [atoedt]

• 18752: LTI in der Administration
• 18755: LTI-Benutzer in der ILIAS Benutzerverwaltung 
• 18753: Benutzer wird für LTI authentifiziert
• 18754: Zielobjekt wird im LTI Kiosk-Modus angezeigt
• 18768: Einstellungen in Kursen
• 18773: Einstellungen in Gruppen
• 18774: Einstellungen in ILIAS Lernmodulen
• 18775: Einstellungen in SCORM Lernmodulen
• 18776: Einstellungen in Tests

Approval

Approved at August 28, 2017 by Kunkel, Matthias [mkunkel]