Usage

A link to an LTI tool can be added to a content page using the WordPress shortcodes facility; for example:

Launch the [lti-platform tool=saltire id=iofkljfg]saLTIre[/lti-platform] LTI testing tool.

or just:

[lti-platform tool=saltire id=iofkljfg]

The latter format is particularly useful when the LTI tool is to be opened in an embedded iframe. A pro-forma shortcode can be inserted into the page by hand, or by selecting the LTI tool option from the More rich text controls menu on the content editor toolbar (highlight any text to be hyperlinked first).

This will display a list of available tools to select from.

A shortcode for the selected tool will be created.

If the tool is configured to use the content-item/deep linking message type, the user will be redirected to the tool to use its interface to make a selection. On completion,

All LTI shortcodes must include the following attributes:

• tool - the code for the LTI tool to be launched
• id - an identifier used as the LTI resource_link_id message parameter. If more than one link to an LTI tool link is included on a page, the id values must be unique. The ID of the content page is used as a prefix for the resource_link_id value to ensure that it is unique across the entire platform.

If either of these attributes is omitted a message of Missing attribute(s): ... is displayed. If no LTI tool exists with the value of the tool attribute then a message of Tool parameter not recognised: test is displayed.

The following attributes are optional:

• title - a value to be used as the resource_link_title parameter in the launch message (enclose the value in quotes if it contains spaces)
• url - override the message URL (see below)
• target - a value of window, popup, iframe or embed to override where the LTI tool will be opened
• width - override the width to be used when opening the LTI tool in a popup window or iframe, including when embedded
• height - override the height to be used when opening the LTI tool in a popup window or iframe, including when embedded
• custom - additional custom parameters to include in the launch message, entered in the format name=value with multiple parameters separated with a semi-colon, for example, debug=true;source=WordPress (any parameters with the same name as one specified in the configuration of the LTI tool will be ignored)

If the url attribute is not a full URL, its contents will be prefixed with the message URL defined for the tool. Otherwise the start of the URL must match the tool's message URL. It is not possible to launch a tool to a URL which does not at least start with the message URL configured for the tool. The following table provides some examples of how the two values are combined:

Message URL	URL attribute	Launch URL
https://tool.com/lti	None	https://tool.com/lti
https://tool.com/lti	https://tool.com/lti/xyz	https://tool.com/lti/xyz
https://tool.com/lti	https://www.tool.com/lti/xyz	None - this is not allowed
https://tool.com/lti/	xyz	https://tool.com/lti/xyz
https://tool.com/lti?	id=xyz	https://tool.com/lti?id=xyz
https://tool.com/lti?id=	xyz	https://tool.com/lti?id=xyz

LTI 1.0 message parameters

The message generated to connect to an LTI tool includes the following parameters:

• context_id - ID of the content page
• context_title - title of the content page
• context_type - the value CourseSection
• ext_username - user's login ID (omitted if the privacy setting has not been selected for the LTI tool)
• launch_presentation_document_target - the value window or iframe
• launch_presentation_height - the height of the popup window or iframe (omitted when opening the LTI tool in a new window)
• launch_presentation_width - the width of the popup window or iframe (omitted when opening the LTI tool in a new window)
• lis_person_contact_email_primary - user's email address (omitted if the privacy setting has not been selected for the LTI tool)
• lis_person_name_family - user's last name (omitted if the privacy setting has not been selected for the LTI tool)
• lis_person_name_full - user's display name (omitted if the privacy setting has not been selected for the LTI tool)
• lis_person_name_given - user's first name (omitted if the privacy setting has not been selected for the LTI tool)
• lti_message_type - the value basic-lti-launch-request
• lti_version - the value LTI-1p0
• oauth_signature_method - the value HMAC-SHA1
• resource_link_id - the value of the id attribute prefixed with the ID of the content page and a dash (for example, 183-iofkljfg)
• resource_link_title - the value of the title attribute, the text between the shortcode tags, or the code of the LTI tool
• roles - the role(s) configured for the tool based on the user's WordPress role (it is also possible for no roles to be passed)
• tool_consumer_info_product_family_code - the value WordPress
• tool_consumer_info_version - the WordPress version (for rxample, 5.6)
• tool_consumer_instance_contact_email - the site's administration email address
• tool_consumer_instance_description - the sites description
• tool_consumer_instance_guid - the GUID value specified on the default settings page
• tool_consumer_instance_name - the site's name
• tool_consumer_instance_url - the site's URL
• user_id - user's ID (omitted if the privacy setting has not been selected for the LTI tool)

The resource_link_id and resource_link_title parameters are not included in content-item messages.

In addition any custom parameters will be included, with their names given a prefix of custom_.

LTI 1.3 message JWT claims

LTI 1.3 passes the same parameter values as LTI 1.0 but as claims in a JWT; for example:

{
    "aud": [
      "..."
    ],
    "email": "...",
    "exp": ...,
    "family_name": "...",
    "given_name": "...",
    "https://purl.imsglobal.org/spec/lti/claim/context": {
        "id": "...",
        "title": "...",
        "type": [
            "CourseSection"
        ]
    },
    "https://purl.imsglobal.org/spec/lti/claim/custom": {
        "...": "..."
    },
    "https://purl.imsglobal.org/spec/lti/claim/deployment_id": "...",
    "https://purl.imsglobal.org/spec/lti/claim/ext": {
        "username": "..."
    },
    "https://purl.imsglobal.org/spec/lti/claim/launch_presentation": {
        "document_target": "..."
    },
    "https://purl.imsglobal.org/spec/lti/claim/message_type": "LtiResourceLinkRequest",
    "https://purl.imsglobal.org/spec/lti/claim/resource_link": {
        "id": "...-...",
        "title": "..."
    },
    "https://purl.imsglobal.org/spec/lti/claim/roles": [
        "http://purl.imsglobal.org/vocab/lis/v2/membership#..."
    ],
    "https://purl.imsglobal.org/spec/lti/claim/target_link_uri": "...",
    "https://purl.imsglobal.org/spec/lti/claim/tool_platform": {
        "contact_email": "...",
        "description": "...",
        "family_code": "WordPress",
        "name": "...",
        "url": "...",
        "version": "..."
    },
    "https://purl.imsglobal.org/spec/lti/claim/version": "1.3.0",
    "nonce": "rjoa6QtbSsDqndTbVmEzccr1DTNvIZOI",
    "iat": ...,
    "iss": "...",
    "name": "...",
    "sub": "..."
}

The only differences in values are the message type and the LTI version, with the addition of the following values:

• iss - Platform ID
• aud - Client ID
• https://purl.imsglobal.org/spec/lti/claim/deployment_id - Deployment ID
• iat - timestamp for when the JWT was issued
• exp - timestamp for when the JWT expires
• nonce - a unique identifier for the JWT

Presentation options

The configuration of each tool determines how it is displayed to a user. If a value of embed has been selected, the tool will be displayed within an iframe on the page. Otherwise the tool is displayed as a hyperlink which, when clicked, will open the tool in a new browser tab or window (window), a popup window (popup) or an iframe (iframe). The iframe option renders the tool in exactly the way as the embed option, except that it only does so after the hyperlink has been clicked, rather than doing so immediately.