Variable substitution (aka variable expansion) is where custom variables really start to shine. They provide a mechanism for tool providers to request that specific, contextual information be sent across in the launch. When the tool consumer processes the launch request, it detects requested variable substitutions and sends the appropriate data where possible. Adding variable substitutions is exactly the same as adding custom variables, except the values are variables instead of constants. This is denoted by prefixing the value with a $. If the tool consumer doesn't recognize, or can't substitute, the value it will just send the variable as if it were are regular custom variable (i.e. the name of the substitution variable will be sent rather than the value).
This allows Canvas to expose data as LTI launch parameters during the LTI launch rather than requiring access to the Canvas API, which can be expensive for Canvas and the tool. It allows tool providers to be much more surgical when requesting user data, and it paves the way for us to be more transparent to tool installers, by showing them exactly what data the LTI tool will be given access to. Additionally, variable substitutions are generally simple to add to Canvas relative to gaining API access.
There are currently over 80 substitutions available. Many of the substitutions simply give access to additional user and context information. An LTI tool can request things like SIS ids, names, an avatar image, and an email address. Other variable substitutions assist tools with accessibility (prefersHighContrast), course copy (previousCourseIds), and masquerading users. Additionally, when we don't provide enough information or customization directly through LTI, tools can request everything they need to use the Canvas API for an even richer experience.
Some substitutions may be used as 'enabled_capabilities' for LTI2 tools. These substitutions have a 'Launch Parameter' label indicating the parameter name that will be sent in the tool launch if enabled.
For more information on variable substitution, see the [https://www.imsglobal.org/specs/ltiv1p1p1/implementation-guide#toc-9](IMS LTI specification).
Variable substitutions can be configured for a tool in 3 ways:
Custom fields can be configured via UI by editing the tool configuration and adding the desired variable to the Custom Fields text box.
The following would add the domain as a launch parameter called custom_arbitrary_name:
arbitrary_name=$Canvas.api.domain
Custom fields can also be configured via API.
This would install a course-level tool with domain as a custom field:
curl 'https://<domain>.instructure.com/api/v1/courses/<course_id>/external_tools' \
-X POST \
-H "Authorization: Bearer <token>;" \
-F 'name=LTI Example' \
-F 'consumer_key=some_key' \
-F 'shared_secret=some_secret' \
-F 'url=https://example.com/ims/lti' \
-F 'privacy_level=name_only' \
-F 'custom_fields[domain]=$Canvas.api.domain'
Custom fields can also be configured via XML.
This would create a tool in a course with custom fields, some of which are specific for a particular placement:
<?xml version="1.0" encoding="UTF-8"?>
<cartridge_basiclti_link xmlns="http://www.imsglobal.org/xsd/imslticc_v1p0"
xmlns:blti = "http://www.imsglobal.org/xsd/imsbasiclti_v1p0"
xmlns:lticm ="http://www.imsglobal.org/xsd/imslticm_v1p0"
xmlns:lticp ="http://www.imsglobal.org/xsd/imslticp_v1p0"
xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation = "http://www.imsglobal.org/xsd/imslticc_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd
http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0.xsd
http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd
http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd">
<blti:title>Wikipedia</blti:title>
<blti:launch_url>https://www.wikipedia.org/</blti:launch_url>
<blti:custom>
<lticm:property name="user_sis_id">$Person.sourcedId</lticm:property>
</blti:custom>
<blti:extensions platform="canvas.instructure.com">
<lticm:property name="domain">wikipedia.org</lticm:property>
<lticm:options name="custom_fields">
<lticm:property name="canvas_api_domain">$Canvas.api.domain</lticm:property>
<lticm:property name="canvas_user_id">$Canvas.user.id</lticm:property>
</lticm:options>
<lticm:options name="course_navigation">
<lticm:property name="url">https://en.wikipedia.org/wiki/Wikipedia:Unusual_articles#mediaviewer/File:Cow-on_pole,_with_antlers.jpeg</lticm:property>
<lticm:property name="text">Cow With Antlers</lticm:property>
<lticm:options name="custom_fields">
<lticm:property name="concluded_roles">$Canvas.membership.concludedRoles</lticm:property>
</lticm:options>
</lticm:options>
</blti:extensions>
</cartridge_basiclti_link>
an opaque identifier that uniquely identifies the context of the tool launch.
Availability: always
Launch Parameter: context_id
cdca1fe2c392a208bd8a657f8865ddb9ca359534
communicates the kind of browser window/frame where the Canvas has launched a tool.
Availability: always
Launch Parameter: launch_presentation_document_target
iframe
returns the current locale.
Availability: always
Launch Parameter: launch_presentation_locale
de
returns a unique identifier for the Tool Consumer (Canvas).
Availability: always
Launch Parameter: tool_consumer_instance_guid
0dWtgJjjFWRNT41WdQMvrleejGgv7AynCVm3lmZ2:canvas-lms
returns the canvas domain for the current context.
Availability: always
canvas.instructure.com
returns the api url for the members of the collaboration.
Availability: always
https://canvas.instructure.com/api/v1/collaborations/1/members
returns the base URL for the current context.
Availability: always
https://canvas.instructure.com
returns the URL for the membership service associated with the current context.
This variable is for future use only. Complete support for the IMS Membership Service has not been added to Canvas. This will be updated when we fully support and certify the IMS Membership Service.
Availability: always
https://canvas.instructure.com/api/lti/courses/1/membership_service
returns the account id for the current context.
Availability: always
1234
returns the account name for the current context.
Availability: always
School Name
returns the account's sis source id for the current context.
Availability: always
sis_account_id_1234
returns the Root Account ID for the current context.
Availability: always
1234
returns the root account's sis source id for the current context.
Availability: always
sis_account_id_1234
returns the URL for the external tool that was launched. Only available for LTI 1.
Availability: always and when in an LTI 1
http://example.url/path
returns the URL for the common css file.
Availability: always
http://example.url/path.css
returns the shard id for the current context.
Availability: always
1234
returns the root account's global id for the current context.
Availability: always
123400000000123
returns the root account id for the current context.
Availability: always
1234
returns the account uuid for the current context.
Availability: always
Launch Parameter: vnd_canvas_root_account_uuid
Ioe3sJPt0KZp9Pw6xAvcHuLCl0z4TvPKP0iIOLbo
returns the root account sis source id for the current context.
Availability: always
1234
returns the current course id.
Availability: when launched in a course
1234
returns the current course name.
Availability: when launched in a course
Course Name
returns the current course sis source id.
Availability: when launched in a course
1234
returns the current course start date.
Availability: when launched in a course
YYY-MM-DD HH:MM:SS -0700
returns the current course workflow state. Workflow states of "claimed" or "created" indicate an unpublished course.
Availability: when launched in a course
active
returns the current course's term start date.
Availability: when launched in a course that has a term with a start date
YYY-MM-DD HH:MM:SS -0700
returns the current course sis source id to return the section source id use Canvas.course.sectionIds.
Availability: when launched in a course
Launch Parameter: lis_course_section_sourcedid
1234
returns the current course enrollment state.
Availability: when launched in a course
active
returns the current course membership roles.
Availability: when launched from a course or an account
StudentEnrollment
This is a list of IMS LIS roles should have a different key.
Availability: when launched in a course
urn:lti:sysrole:ims/lis/None
Returns the context ids from the course that the current course was copied from (excludes cartridge imports).
Availability: when launched in a course
1234
Returns the course ids of the course that the current course was copied from (excludes cartridge imports).
Availability: when launched in a course
1234
Returns the full name of the launching user.
Availability: when launched by a logged in user
Launch Parameter: lis_person_name_full
John Doe
Returns the last name of the launching user.
Availability: when launched by a logged in user
Launch Parameter: lis_person_name_family
Doe
Returns the first name of the launching user.
Availability: when launched by a logged in user
Launch Parameter: lis_person_name_given
John
Returns the primary email of the launching user.
Availability: when launched by a logged in user
Launch Parameter: lis_person_contact_email_primary
john.doe@example.com
Returns the institution assigned email of the launching user.
Availability: when launched by a logged in user that was added via SIS
john.doe@example.com
Returns the name of the timezone of the launching user.
Availability: when launched by a logged in user
America/Denver
Returns the profile picture URL of the launching user.
Availability: when launched by a logged in user
Launch Parameter: user_image
https://example.com/picture.jpg
Returns the Canvas user_id of the launching user.
Availability: when launched by a logged in user
Launch Parameter: user_id
420000000000042
Returns the Canvas user_id of the launching user.
Availability: when launched by a logged in user
420000000000042
Returns the users preference for high contrast colors (an accessibility feature).
Availability: when launched by a logged in user
false
returns the context ids for the groups the user belongs to in the course.
Availability: always
1c16f0de65a080803785ecb3097da99872616f0d,d4d8d6ae1611e2c7581ce1b2f5c58019d928b79d,...
Returns the IMS LTI membership service roles for filtering via query parameters.
Availability: when launched by a logged in user
Launch Parameter: roles
http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator
Returns list of LIS role full URNs.
Availability: always
urn:lti:instrole:ims/lis/Administrator,urn:lti:instrole:ims/lis/Instructor,urn:lti:sysrole:ims/lis/SysAdmin,urn:lti:sysrole:ims/lis/User
Returns the Canvas global user_id of the launching user.
Availability: when launched by a logged in user
420000000000042
Returns true for root account admins and false for all other roles.
Availability: when launched by a logged in user
true
Username/Login ID for the primary pseudonym for the user for the account. This may not be the pseudonym the user is actually logged in with.
Availability: when pseudonym is in use
jdoe
Username/Login ID for the primary pseudonym for the user for the account. This may not be the pseudonym the user is actually logged in with.
Availability: when pseudonym is in use
jdoe
Returns the sis source id for the primary pseudonym for the user for the account This may not be the pseudonym the user is actually logged in with.
Availability: when pseudonym is in use
sis_user_42
Returns the integration id for the primary pseudonym for the user for the account This may not be the pseudonym the user is actually logged in with.
Availability: when pseudonym is in use
integration_user_42
Returns the sis source id for the primary pseudonym for the user for the account This may not be the pseudonym the user is actually logged in with.
Availability: when pseudonym is in use
Launch Parameter: lis_person_sourcedid
sis_user_42
Returns the logout service url for the user. This is the pseudonym the user is actually logged in as. It may not hold all the sis info needed in other launch substitutions.
Availability: always
https://<domain>.instructure.com/api/lti/v1/logout_service/<external_tool_id>-<user_id>-<current_unix_timestamp>-<opaque_string>
Returns the Canvas user_id for the masquerading user. This is the pseudonym the user is actually logged in as. It may not hold all the sis info needed in other launch substitutions.
Availability: when the user is being masqueraded
420000000000042
Returns the 40 character opaque user_id for masquerading user. This is the pseudonym the user is actually logged in as. It may not hold all the sis info needed in other launch substitutions.
Availability: when the user is being masqueraded
da12345678cb37ba1e522fc7c5ef086b7704eff9
Returns the xapi url for the user.
Availability: always
https://<domain>.instructure.com/api/lti/v1/xapi/<external_tool_id>-<user_id>-<course_id>-<current_unix_timestamp>-<opaque_id>
Returns the caliper url for the user.
Availability: always
https://<domain>.instructure.com/api/lti/v1/caliper/<external_tool_id>-<user_id>-<course_id>-<current_unix_timestamp>-<opaque_id>
Returns a comma separated list of section_id's that the user is enrolled in.
Availability: when launched from a course
42, 43
Returns a comma separated list of section sis_id's that the user is enrolled in.
Availability: when launched from a course
section_sis_id_1, section_sis_id_2
Returns the module_id that the module item was launched from.
Availability: when content tag is present
1234
Returns the module_item_id of the module item that was launched.
Availability: when content tag is present
1234
Returns the assignment_id of the assignment that was launched.
Availability: when launched as an assignment
1234
Returns the title of the assignment that was launched.
Availability: when launched as an assignment
Deep thought experiment
Returns the points possible of the assignment that was launched.
Availability: when launched as an assignment
100
deprecated in favor of ISO8601.
Availability: when launched as an assignment
deprecated in favor of ISO8601.
Availability: when launched as an assignment
deprecated in favor of ISO8601.
Availability: when launched as an assignment
Returns the unlock_at date of the assignment that was launched.
Only available when launched as an assignment with an unlock_at set.
Availability: always
YYYY-MM-DDT07:00:00Z
Returns the lock_at date of the assignment that was launched.
Only available when launched as an assignment with a lock_at set.
Availability: always
YYYY-MM-DDT07:00:00Z
Returns the due_at date of the assignment that was launched.
Only available when launched as an assignment with a due_at set.
Availability: always
YYYY-MM-DDT07:00:00Z
Returns true if the assignment that was launched is published. Only available when launched as an assignment.
Availability: when launched as an assignment
true
Returns the endpoint url for accessing link-level tool settings Only available for LTI 2.0.
Availability: always
https://<domain>.instructure.com/api/lti/tool_settings/<link_id>
Returns the endpoint url for accessing context-level tool settings Only available for LTI 2.0.
Availability: always
https://<domain>.instructure.com/api/lti/tool_settings/<binding_id>
Returns the endpoint url for accessing system-wide tool settings Only available for LTI 2.0.
Availability: always
https://<domain>.instructure.com/api/lti/tool_settings/<proxy_id>
Returns the Tool Consumer Profile url for the tool. Only available for LTI 2.0.
Availability: always
https://<domain>.instructure.com/api/lti/courses/<course_id>/tool_consumer_profile/<opaque_id>
https://<domain>.instructure.com/api/lti/accounts/<account_id>/tool_consumer_profile/<opaque_id>
Availability: when an attachment is present and it has either a media object or media entry id defined
Availability: when an attachment is present and has a media object defined
Availability: when an attachment is present and has a media object defined
Availability: when an attachment is present and has a media object defined
Availability: when an attachment is present and has a media object defined
Availability: when an attachment is present and has usage rights defined
Availability: when an attachment is present and has usage rights defined
Availability: when an attachment is present and has usage rights defined