Custom parameter substitutions

Introduction

This document describes the support for substitutable custom parameters for LTIs in itslearning. In the following you will find a list with the message variable name s itslearning supports substitution for, and the value that they are substituted with. Any other parameters with unsupported message variable name s , if provided, values will be passed along in their unsubstituted form.

E.g. $ Person.name is not a message variable name that itslearning supports substitution for. If the following custom parameter is configured:

person_name=$Person.name

the following will be passed to Tool Provider:

custom_person_name=$Person.name

Message variables

The following tables list all Message variables itslearning supports substitution for. Some of these will only be substituited if they are passed in e.g. Course context, and some of custom parameters containing these will only be passed in e.g. Course context.

LTI User variables

Message variable name

Description

Value

$User.id

Platform user entity id (not sync key in any case)
Note: This is platform user id, and not the itslearning person id.

E.g.: 400012

(Same as for user_id from LTI standard parameters)

$User.username

User's username.
Only provided if privacy level is set to Public.

E.g.: adamsmith

LIS Person variables

Message variable name

Description

Value

$Person.name.full

Person full name
Only provided if privacy level is set to Public or NameOnly

E.g.: [email protected]

(Same as for lis_person_name_full from LTI standard parameters )

$Person.name.family

Person family name
Only provided if privacy level is set to Public or NameOnly

E.g.: Smith

(Same as for lis_person_name_family from LTI standard parameters )

$Person.name.given

Person given name
Only provided if privacy level is set to Public or NameOnly

E.g.: Adam Smith

(Same as for lis_person_name_given from LTI standard parameters )

$Person.address.locality

Person locale

E.g. : en-GB

(Same as for launch_presentation_locale from LTI standard parameters )

$Person.address.timezone

Person windows timezone

E.g: GMT Standard Time

$Person.email.primary

Person primary e-mail address
Only provided if privacy level is set to Public or EmailOnly

E.g : [email protected]

(Same as for lis_person_contact_email_primary from LTI standard parameters )

LIS Course Offering Variables

These Message variables are only substituted in course context, and the custom parameters containing these are only passed in course context.

Message variable name

Description

Value

$CourseOffering.sourcedId

Identifier for course

E.g. : ltitest.itslearning.com:MYCA

(Same as for lis_course_offering_sourcedid from LTI standard parameters)

$CourseOffering.title

Course title

E.g.: Course A

(Same as for context_title from LTI standard parameters)

$CourseOffering.courseNumber

Course code

E.g. : MYCA

(Same as for context_label from LTI standard parameters)

LIS Course Section Variables

These Message variables are only substituted in course context, and the custom parameters containing these are only passed in course context.

Message variable name

Description

Value

$CourseSection.sourcedId

Identifier for Learning tool instance in course

E.g.: ltitest.itslearning.com:MYCA-104454

(Same as for lis_course_section_sourcedid from LTI standard parameters)

$CourseSection.title

Learning tool instance title

E.g.: LTI tool title

$CourseSection.shortDescription

Max 200 characters of learning tool instance description

A short description describing the learning tool instance

$CourseSection.longDescription

Learning tool instance description

A long description elaborately describing the learning tool instance and possible some more details

$CourseSection.courseNumber

Course code

E.g. : MYCA

(Same as for context_label from LTI standard parameters)

$CourseSection.timeFrame.begin

Time the learning tool instance is active from

E.g. : 01.01.1900 23:59:59

$CourseSection.timeFrame.end

Time the learning tool instance is active to

E.g. : 31.12.9999 23:59:59

$CourseSection.sourceSectionId

Learning tool instance ID

E.g. : 104454

LIS Result Variables

These Message variables are only substituted in course context, and the custom parameters containing these are only passed in course context.

Message variable name

Description

Value

$Result.sourcedGUID

Unique result identifier

E.g. : mzkaxjv4rwgjrt55eov0tj55;104454;114662;18619

(Same as for lis_result_sourcedid from LTI standard parameters)

$Result.resultScore

Result in format valid according to LTI specs

E.g: 0.6

itslearning Context Variables

These Message variables are only substituted in course context, and the custom parameters containing these are only passed in course context.

Message variable name

Description

Value

$Context.courseId

Course ID for course this instance is placed in

Format: <CustomerId>-<CourseId>

E.g. : 23002-6

$Context.organisationId

Course organisation ID for course this instance is placed in

E.g.: 1233

$Context.organisationSyncKey

Course organisation SyncKey for course this instance is placed in

E.g. : ASD1234

itslearning Instance Variables

These Message variables are only substituted in course context, and the custom parameters containing these are only passed in course context.

Message variable name

Description

Value

$Instance.creatorOrganisationIds

List of organisation IDs for creator of this instance in course

E.g. : 123, 423, 3423

$Instance.creatorOrganisationSyncKeys

List of organisation SyncKeys for creator of this instance in course

E.g. : ADE123, DSE423, DSE3423

$ToolConsumerProfile.url

An endpoint where TP could go to read description of itslearning as LTI Tool Consumer (a TC profile)

E.g: https://ltitest.itslearning.com/api/toolConsumerProfile

itslearning Person Variables

Message variable name

Description

Value

$Person.customerId

Customer\site Identifier the Person belong to

E.g. : 2

(Same as for tool_consumer_instance_guid from LTI standard parameters)

Tool consumer variables

Message variable name

Description

Value

$ToolConsumerProfile.url

An endpoint where TP could go to read description of itslearning as LTI Tool Consumer (a TC profile)

E.g: https://ltitest.itslearning.com/api/toolConsumerProfile